Skip to main content

​
Prerequisites

Before setting up webchat, ensure you have:
  • An active Apten account
  • A website where you can add JavaScript code (access to edit HTML)
  • At least one customer profile configured for webchat conversations

​
Step 1: Create an API Key

API keys authenticate your website, hold your webchat configuration, and protect against unauthorized use. In Settings > Webchat > API Keys, click Create API Key and configure: Allowed Domains (required) — Domains authorized to use this key.
  • Specific domain: example.com
  • All subdomains: *.example.com
  • Add multiple domains to one key
Webchat Customer Profile (required) — The customer profile that handles conversations on this key. Defines the agent’s tone and conversational flow. Lead Conversion Profile — Customer profile used when converting webchat leads to phone outreach. Defaults to the webchat customer profile. Greeting Message — First message shown when a visitor opens the chat. Default: “How can I help?” Opt-In Message — Consent message displayed above the contact form submit button. Commonly used for TCPA compliance. Enable Auto-Conversion — Automatically convert sessions with contact info to leads after a period of inactivity. Inactivity Timeout — Minutes of inactivity before auto-conversion (default: 60, range: 15–1440). Only applies when auto-conversion is enabled. Send SMS on Duplicate Conversion — When a session converts and the contact already exists as a lead, send that existing lead an SMS. Click Save and copy your generated API key.
Not sure which profile to use? Learn more about customer profiles and how to configure them for webchat.
Keep your API key secure! Never commit API keys to public repositories or expose them in client-side code that could be copied. The widget code on your website is safe because domain whitelisting prevents misuse.
See the configuration reference for full details on each field.

​
Step 2: Add Widget to Your Website

Copy the integration code below and paste it before the closing </body> tag on every page where you want the webchat widget to appear.

​
Basic Integration

<script>
  window.AptenWidget = {
    apiKey: 'ak_live_org_your_key_here',
  };
</script>
<script type="module" src="https://widget.apten.ai/apten-loader.js"></script>

​
Custom Configuration

Customize the widget appearance with these optional parameters: 
<script>
  window.AptenWidget = {
    apiKey: 'ak_live_org_your_key_here',
    theme: 'light', // "light" or "dark" (default: "light")
    position: 'bottom-right', // "bottom-right", "bottom-left", "top-right", "top-left" (default: "bottom-right")
    primaryColor: '#0073CF', // Hex color for branding (e.g., "#0073CF")
  };
</script>
<script type="module" src="https://widget.apten.ai/apten-loader.js"></script>

​
Configuration Options

ParameterTypeRequiredDescription
apiKeystringYesYour API key from the Apten dashboard
themestringNoWidget color scheme: "light" or "dark" (default: "light")
positionstringNoChat bubble position: "bottom-right", "bottom-left", "top-right", "top-left" (default: "bottom-right")
primaryColorstringNoBrand color in hex format (e.g., "#0073CF") for buttons and accents

​
Step 3: Test Your Integration

After adding the widget code to your website:
  1. Open your website in a web browser
  2. Look for the chat bubble in the position you configured
  3. Click the bubble to open the chat interface
  4. Send a test message to your agent
  5. Return to your Apten dashboard and navigate to the Webchat tab
  6. Verify your test conversation appears in the session list
Success! If you see your test conversation in the dashboard, your webchat is working correctly.

​
Troubleshooting

​
Widget Not Appearing

Problem: The chat bubble doesn’t show up on your website. Solutions:
  • Verify the domain is added to your API key’s allowed domains list
  • Check browser console for JavaScript errors
  • Ensure the widget script is loading (check Network tab in developer tools)
  • Confirm the script is placed before the closing </body> tag

​
”Invalid API Key” Error

Problem: Console shows authentication errors or “Invalid API key” message. Solutions:
  • Double-check you copied the complete API key correctly
  • Verify the API key status is “Active” in dashboard settings
  • Ensure you’re using the correct API key format (starts with ak_live_org_)

​
CORS or Origin Errors

Problem: Browser console shows CORS policy errors. Solutions:
  • Ensure your website’s domain exactly matches an entry in allowed domains
  • For www.example.com, add both example.com and *.example.com, or be explicit
  • Check for typos in the allowed domains list
  • Remember: example.com does not automatically include www.example.com

​
Widget Appears But Agent Doesn’t Respond

Problem: Chat opens but messages don’t get responses. Solutions:
  • Verify the API key’s webchat customer profile is properly configured
  • Check that the customer profile has active conversation flows
  • Ensure your Apten account has sufficient credits
  • Review the session in your dashboard to see if messages are being received

​
Next Steps

Webchat Capabilities

Learn what your webchat agent can do

Configuration Settings

Explore all customization options

Customer Profiles

Optimize your agent’s conversation flow

Custom Knowledge

Connect your documentation for better answers