> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apten.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup and Integration

> Add the Apten webchat widget to your website in minutes

## 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](/tutorials/customer_profiles) 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.

<Info>
  Not sure which profile to use? Learn more about [customer
  profiles](/tutorials/customer_profiles) and how to configure them for webchat.
</Info>

<Warning>
  **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.
</Warning>

See the [configuration reference](/webchat/settings) 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

```html theme={null}
<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:

```html theme={null}
<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

| Parameter      | Type   | Required | Description                                                                                                      |
| -------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------- |
| `apiKey`       | string | Yes      | Your API key from the Apten dashboard                                                                            |
| `theme`        | string | No       | Widget color scheme: `"light"` or `"dark"` (default: `"light"`)                                                  |
| `position`     | string | No       | Chat bubble position: `"bottom-right"`, `"bottom-left"`, `"top-right"`, `"top-left"` (default: `"bottom-right"`) |
| `primaryColor` | string | No       | Brand 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

<Check>
  **Success!** If you see your test conversation in the dashboard, your webchat
  is working correctly.
</Check>

## 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

<CardGroup cols={2}>
  <Card title="Webchat Capabilities" icon="stars" href="/webchat/capabilities">
    Learn what your webchat agent can do
  </Card>

  <Card title="Configuration Settings" icon="gear" href="/webchat/settings">
    Explore all customization options
  </Card>

  <Card title="Customer Profiles" icon="user-tie" href="/tutorials/customer_profiles">
    Optimize your agent's conversation flow
  </Card>

  <Card title="Custom Knowledge" icon="brain" href="/tutorials/custom_knowledge">
    Connect your documentation for better answers
  </Card>
</CardGroup>