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: Configure Webchat Settings

Navigate to Settings > Webchat in your Apten dashboard to configure your webchat behavior.

​
Required Settings

Webchat Customer Profile Select the customer profile that will handle all webchat conversations. This profile defines your agent’s tone, and conversational flow.
Not sure which profile to use? Learn more about customer profiles and how to configure them for webchat.

​
Optional Settings

Lead Conversion Profile Choose a different customer profile for follow-up when webchat leads are converted to phone outreach. If not set, the webchat customer profile is used for follow-up. Greeting Message Customize the first message visitors see when they open the chat. Default: “How can I help?” Enable Auto-Conversion Automatically convert webchat sessions with collected contact information to leads after a period of inactivity. When enabled, you can set the inactivity timeout (default: 60 minutes).

​
Step 2: Create an API Key

API keys authenticate your website and protect against unauthorized use.
  1. In Settings > Webchat, click Create API Key
  2. Add your allowed domains:
    • For a specific domain: example.com
    • For all subdomains: *.example.com
    • You can add multiple domains to one key
  3. Click Save and copy your generated API key
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.

​
Step 3: 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 src="https://cdn.apten.com/latest/apten-widget.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 src="https://cdn.apten.com/latest/apten-widget.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 4: 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 your 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