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

# Configuration Settings

> Complete reference for webchat configuration options

## Webchat Key Settings

Each webchat API key holds its own configuration. Manage keys in **Settings > Webchat > API Keys** and edit these fields in the Create or Edit key dialog.

### Webchat Customer Profile

<ParamField path="Webchat Customer Profile" type="Customer Profile" required>
  The customer profile used for conversations on this key. Defines your agent's behavior, tone, and conversational flow.
</ParamField>

### Lead Conversion Profile

<ParamField path="Lead Conversion Profile" type="Customer Profile">
  A separate customer profile used when converting webchat leads to phone outreach, so you can use different messaging for chat versus follow-up calls.

  **Default:** Uses the webchat customer profile.
</ParamField>

### Greeting Message

<ParamField path="Greeting Message" type="string">
  The first message displayed when a visitor opens the chat, shown before the agent responds.

  **Default:** "How can I help?"
</ParamField>

### Opt-In Message

<ParamField path="Opt-In Message" type="string">
  A consent message displayed above the submit button on the contact form. Use this to collect explicit consent before capturing contact information — commonly required for [TCPA](https://www.fcc.gov/general/telemarketing-and-robocalls) compliance.

  **Default:** None
</ParamField>

### Enable Auto-Conversion

<ParamField path="Enable Auto-Conversion" type="boolean">
  Automatically convert webchat sessions with collected contact information to leads after a period of inactivity. When disabled, sessions must be manually converted.

  **Default:** Disabled
</ParamField>

### Inactivity Timeout

<ParamField path="Inactivity Timeout" type="number">
  Minutes of inactivity before a session auto-converts to a lead. Only applies when auto-conversion is enabled. The timer resets whenever the visitor sends a message.

  **Default:** 60 minutes
  **Range:** 15-1440 minutes (1 day)
</ParamField>

### Send SMS on Duplicate Conversion

<ParamField path="Send SMS on Duplicate Conversion" type="boolean">
  When a webchat session converts and the contact already exists as a lead, send that existing lead an SMS.

  **Default:** Disabled
</ParamField>

### Allowed Domains

<ParamField path="Allowed Domains" type="string[]" required>
  Whitelist of domains authorized to use this API key. This prevents
  unauthorized use of your webchat widget.
</ParamField>

**Domain Format Options:**

| Format              | Example                      | Matches                                                        |
| ------------------- | ---------------------------- | -------------------------------------------------------------- |
| Exact domain        | `example.com`                | Only `example.com`                                             |
| With subdomain      | `www.example.com`            | Only `www.example.com`                                         |
| Wildcard subdomains | `*.example.com`              | `www.example.com`, `app.example.com`, `blog.example.com`, etc. |
| Multiple domains    | `example.com`, `example.org` | Both domains                                                   |

<Warning>
  **Security Note:** `example.com` does NOT automatically include
  `www.example.com`. Add both or use `*.example.com` to cover all subdomains.
</Warning>

**Best Practices:**

* Add all domains where you'll deploy the widget
* Use wildcards for subdomain flexibility
* Don't add domains you don't control
* Review and remove old domains when sites are retired

### Active Status

<ParamField path="Active" type="boolean">
  Enable or disable this API key. Inactive keys cannot authenticate requests.

  **Default:** Active when created
</ParamField>

**Use Cases for Disabling:**

* Temporarily disable webchat on specific sites
* Rotate keys by creating new key before disabling old one
* Respond to security concerns quickly
* Control access without deleting key history

### Usage Tracking

Monitor your API key activity:

* **Request Count** - Total number of authenticated requests
* **Last Used** - Timestamp of most recent usage
* **Created** - When the key was generated

Use this information to:

* Identify unused keys
* Monitor webchat traffic
* Detect unusual activity
* Track deployment across multiple sites

## Widget Appearance Settings

Configure widget appearance in your website's integration code by setting `window.AptenWidget` properties.

### theme

<ParamField path="theme" type="string">
  Controls the overall color scheme of the widget.

  **Options:** `"light"`, `"dark"`
  **Default:** `"light"`
</ParamField>

The theme automatically adjusts:

* Background colors
* Text colors
* Border colors
* Shadow styles
* Icon colors

**Light Theme:** Best for bright, clean websites
**Dark Theme:** Best for dark-themed sites or evening/night users

### position

<ParamField path="position" type="string">
  Controls where the chat bubble appears on the page.

  **Options:** `"bottom-right"`, `"bottom-left"`, `"top-right"`, `"top-left"`
  **Default:** `"bottom-right"`
</ParamField>

**Choosing Position:**

* **Bottom-right:** Standard position, familiar to most users
* **Bottom-left:** Alternative if right side has other widgets
* **Top-right:** Unusual but visible above the fold
* **Top-left:** Rare, use if layout demands it

<Tip>
  Test different positions on mobile devices. Bottom positions are generally
  more accessible on mobile screens.
</Tip>

### primaryColor

<ParamField path="primaryColor" type="string">
  Custom brand color for buttons, accents, and highlights.

  **Format:** Hex color code (e.g., `"#0073CF"`)
  **Default:** Apten blue
</ParamField>

The primary color is used for:

* Chat bubble background
* Send button
* Active states
* Links and accents
* User message bubbles

**Color Tips:**

* Use your brand's primary color for consistency
* Ensure sufficient contrast with background
* Test readability on both light and dark themes
* Hover and active states are automatically calculated

**Example Values:**

* `"#0073CF"` - Professional blue
* `"#10B981"` - Friendly green
* `"#8B5CF6"` - Modern purple
* `"#EF4444"` - Bold red

## Customer Profile Settings

These settings are configured in your customer profile but directly affect webchat behavior. Edit them in **Settings > Customer Profiles**.

### Tone and Messaging Style

Your customer profile's tone settings determine how the webchat agent communicates:

* **Conversation style** - Formal, casual, friendly, professional
* **Message length** - Concise chat messages vs. detailed explanations
* **Emoji usage** - Whether agent uses emojis in responses
* **Personality traits** - Helpful, enthusiastic, serious, etc.

<Info>
  For webchat, shorter messages with frequent back-and-forth work better than
  long-form responses. Consider creating a dedicated webchat profile with
  chat-optimized messaging.
</Info>

### Email Requirement

<ParamField path="Require Email" type="boolean">
  Whether email address is required for contact collection.

  **Location:** Customer Profile > Contact Settings
  **Default:** Optional
</ParamField>

**When to Require Email:**

* Email is your primary follow-up channel
* You send automated email sequences
* You need email for your CRM

**When to Make Optional:**

* Phone is your primary contact method
* Reduce friction in contact collection
* Some visitors are reluctant to share email

### Transfer Call Number

<ParamField path="Transfer Call Number" type="string">
  Phone number to call when agent transfers a visitor to human sales team.

  **Location:** Customer Profile > Transfer Settings
  **Format:** E.164 format (e.g., +1234567890)
</ParamField>

**Required for:**

* Human transfer capability
* "Talk to sales" requests
* Escalations from agent to human

**Not required if:**

* You don't offer human transfers from webchat
* You only want automated lead capture

### Guardrails

Configure content restrictions and conversation boundaries in your customer profile:

* **Topic restrictions** - Subjects the agent should avoid
* **Content policies** - Language and behavior rules
* **Disclosure requirements** - Required disclaimers or notices
* **Compliance rules** - Industry-specific regulations

These guardrails ensure your webchat agent maintains appropriate, brand-aligned conversations.

## Next Steps

<CardGroup cols={2}>
  <Card title="Webchat Overview" icon="comments" href="/webchat/overview">
    Learn about webchat features and use cases
  </Card>

  <Card title="Setup Guide" icon="rocket" href="/webchat/setup">
    Install the webchat widget on your website
  </Card>

  <Card title="Agent Capabilities" icon="stars" href="/webchat/capabilities">
    Understand what your webchat agent can do
  </Card>

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