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

# Chat Widget

> Add an AI chat assistant to your website — no coding expertise required

The **SquawkVoice Chat Widget** lets you place an AI chat assistant directly on any webpage. Visitors can type questions and get instant, intelligent responses — powered by the agent you built in the Studio.

This guide walks you through embedding the widget, customizing how it looks, and optionally passing customer details (like a name or account ID) so the agent can personalize every conversation.

***

## Before You Start

Make sure you have:

* An agent built and saved in **Studio → Build → AI Agents**
* The **assistant ID** and **public key** for that agent (found under **Chat Configuration → Embed Code**, with the key also shown as **Widget Key** in **Widget Config**)
* Access to your website's HTML source code

***

## Step 1 — Add the Widget to Your Website

The widget is a small piece of HTML you paste into your website. It loads as a floating chat button, usually in the bottom-right corner of the page.

Everything about the widget is managed from one place in the Studio: open your agent and go to **Chat Configuration**, which has two sections —

* **Widget Config** — appearance, allowed origins, agent escalation, chat variables, and your widget key
* **Embed Code** — the theme and version pickers, and the snippet to copy

### Get Your Embed Code

1. Open your agent in **Studio → Build → AI Agents**.
2. Go to **Chat Configuration → Embed Code**.
3. Choose a **Widget Version** — leave it on **Latest (2.0.0)** unless you need to pin a specific release. Versions 1.0.0 through 1.4.0 are still available to pin.
4. Choose your starting theme: `light` or `dark`.
5. Copy the generated embed snippet.

### Widget Versions

The version you pick controls **only which loader file your snippet points at**. The chat experience itself is not version-pinned — it is always the current release — so appearance and behavior improvements reach every page that already has the widget embedded, with no change on your side.

<Info>
  Agents that were previously pinned to an older widget version have been moved to **Latest**. If you need a specific loader file, re-pin it under **Chat Configuration → Embed Code**.
</Info>

### Paste It Into Your Page

Open your website's HTML and paste the snippet **just before the closing `</body>` tag**:

```html theme={null}
<squawkvoice-widget
  assistant-id="your-assistant-uuid"
  public-key="squawk_pk_your_public_key"
  theme="light"
></squawkvoice-widget>

<script
  src="https://app.squawkvoice.ai/widget/loader/squawk-chat-widget@latest.js"
  defer
  type="text/javascript"
></script>
```

That's it — save your file, reload your site, and the chat button should appear.

<Tip>
  The `defer` attribute on the script tag means it loads after the rest of your page, so it won't slow down your site's initial load time.
</Tip>

***

## Step 2 — Customize the Widget's Appearance

You can change how the widget looks directly from the Studio — no code changes needed. These controls live under **Chat Configuration → Widget Config**.

| Setting             | What It Controls                                                                                                                                                                                                                                                                                          |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Theme**           | `light` or `dark` starting mode                                                                                                                                                                                                                                                                           |
| **Position**        | Corner of the screen: `bottom-right`, `bottom-left`, `top-right`, `top-left`                                                                                                                                                                                                                              |
| **AI Agent Name**   | The name shown in the chat header and on the sender line under each AI reply. Defaults to **AI Agent** — it does **not** fall back to your agent's internal name                                                                                                                                          |
| **Widget Logo**     | Your brand logo, shown in the widget header (cropped to fill a circle)                                                                                                                                                                                                                                    |
| **AI Agent Avatar** | The image shown on the disc beside AI replies. Falls back to a default icon                                                                                                                                                                                                                               |
| **Colors**          | Five pickers — **Brand**, **User Message Text**, **AI Agent Message Text**, **AI Agent Message Background**, **Header Text** — each set separately for light and dark mode. Changing a light color auto-derives the dark one. The AI avatar disc inherits the AI Agent Message Background and Text colors |
| **AI Disclaimer**   | Optional fine-print text shown below the chat input                                                                                                                                                                                                                                                       |

**Widget Logo** and **AI Agent Avatar** accept PNG, JPG, GIF and WebP files up to 10 MB. SVG is not supported.

Changes to these settings take effect automatically — you don't need to update the embed code. Edits save as you make them, and any pending change is written out when you leave the panel.

On your site, the launcher stays hidden until its saved position, size, color and logo have loaded, so it fades in already branded rather than flashing in the default corner first.

***

## Step 3 — Pass Customer Data Into the Chat (Optional)

This is one of the most powerful features of the widget. You can tell the agent who the customer is *before* they type a single word — things like their name, email address, subscription plan, or account ID.

Think of it like giving your agent a briefing sheet before starting a conversation.

### How It Works (Plain English)

1. You define which pieces of customer information you want to share — these are called **chat variables**.
2. You map each piece of information to a named slot in the agent (e.g., `"customerName"` → the agent's `interaction.CHAT.customer_name` variable).
3. When your page loads, your JavaScript puts the actual customer values into a global object called `window.SquawkVoiceChatVariables`.
4. The widget reads those values, strips them from the browser window (so other scripts can't snoop on them), and sends them securely to the agent's session.
5. The agent can immediately use those values — in its greeting, its guidelines, or any API calls it makes on the customer's behalf.

<Info>
  Chat variables require **widget version 1.1.0 or later**. If you're on `latest`, you're already covered.
</Info>

***

### Part A — Create the Variables in the Studio

Before the widget can pass any data, the agent needs to know where to store it.

1. Open your agent and go to **Pre-Call** (or the **Variables** / **Guidelines** section).
2. Create new variables of type **INTERACTION**.
3. Name each variable using the prefix `interaction.CHAT.` followed by a descriptive name.

**Example variable names:**

| Variable Name                    | What It Stores              |
| -------------------------------- | --------------------------- |
| `interaction.CHAT.customer_name` | The customer's display name |
| `interaction.CHAT.email`         | Their email address         |
| `interaction.CHAT.account_id`    | Their account or user ID    |
| `interaction.CHAT.plan`          | Their subscription tier     |

***

### Part B — Set Up the Mappings in Widget Config

This step connects your JavaScript keys (what you'll type in your website's code) to the agent variables you just created.

1. In your agent, go to **Chat Configuration → Widget Config → Chat Variables**.
2. Click **Add Mapping** and fill in:
   * **Key** — the name you'll use in your JavaScript (e.g., `customerName`)
   * **Variable** — the agent variable to receive the value (e.g., `interaction.CHAT.customer_name`)
   * **Default Value** *(optional)* — a fallback if the page doesn't provide a value (e.g., `Guest`)
   * **Test Value** *(optional)* — a sample value used **only** in the in-platform test chat (e.g., `Sarah Johnson`)

<Tip>
  Use the **Default Value** field for things like a customer name — set it to `Guest` so the agent always has something to work with, even for anonymous visitors.
</Tip>

### Preview With Test Values

Every mapping has a **Test Value** field so you can preview variable-driven behavior without touching your website:

1. Enter a test value next to each mapping (e.g. `Sarah Johnson` for `customerName`).
2. Open the in-platform test chat — the agent session is seeded with your test values, exactly as if the live page had passed them.

Test values are strictly a Studio-side tool: they are stripped from the widget configuration served to your website and are **never** sent to real visitor sessions.

<Warning>
  Do not enter real customer information in Test Value fields — use representative sample data.
</Warning>

**Key naming rules:**

* Must start with a letter (not a number or symbol)
* Can only contain letters (`a–z`, `A–Z`), numbers (`0–9`), and underscores (`_`)
* Maximum 64 characters

Valid examples: `customerName`, `account_id`, `planTier2`

Invalid examples: `123customer`, `my-key`, `customer.name`

***

### Part C — Inject the Values on Your Web Page

On your website, define the `window.SquawkVoiceChatVariables` object **in a separate `<script>` block that appears before the widget loader script**. Use the exact key names you set up in Part B.

```html theme={null}
<script>
  window.SquawkVoiceChatVariables = {
    "customerName": "Sarah Johnson",
    "email": "sarah@example.com",
    "accountId": "acc_98765",
    "plan": "Pro"
  };
</script>

<squawkvoice-widget
  assistant-id="your-assistant-uuid"
  public-key="squawk_pk_your_public_key"
  theme="light"
></squawkvoice-widget>

<script
  src="https://app.squawkvoice.ai/widget/loader/squawk-chat-widget@latest.js"
  defer
  type="text/javascript"
></script>
```

In a real application, you'd replace the hardcoded values with dynamic ones from your server or session:

```html theme={null}
<script>
  window.SquawkVoiceChatVariables = {
    "customerName": "{{ current_user.display_name }}",
    "email": "{{ current_user.email }}",
    "accountId": "{{ current_user.id }}"
  };
</script>
```

<Warning>
  The `window.SquawkVoiceChatVariables` script block **must come before** the `<script src=".../squawk-chat-widget.js">` tag. If the loader runs first, it won't find your variables.
</Warning>

***

## What Happens Behind the Scenes

You don't need to understand this to use the widget, but it helps to know the widget is designed with security in mind.

1. **The loader reads your variables** — When the widget loader script runs, it immediately reads whatever is in `window.SquawkVoiceChatVariables`.
2. **It deletes the global object** — The loader then removes `window.SquawkVoiceChatVariables` from the browser window, so other scripts on the page can no longer access that customer data.
3. **Values are sanitized** — Keys and values are validated: invalid types (objects, arrays, functions) are dropped; values are capped at 500 characters.
4. **A secure session is started** — The widget establishes an authenticated session with the SquawkVoice backend using a challenge-response handshake. Your variables are sent as part of this secure session setup.
5. **The backend validates mappings** — The backend only accepts keys that are explicitly configured under **Chat Configuration → Widget Config → Chat Variables**. Any extra keys sent from the page are silently ignored.
6. **Variables become available to the agent** — Once the session is established, your agent can reference these values in its greeting, guidelines, or during-call actions.

***

## Limits & Constraints

| Constraint                               | Limit                                                            |
| ---------------------------------------- | ---------------------------------------------------------------- |
| Maximum chat variable mappings per agent | **20**                                                           |
| Maximum value length                     | **500 characters** (longer values are truncated)                 |
| Key naming                               | Must start with a letter; letters, numbers, and underscores only |
| Maximum key length                       | **64 characters**                                                |
| Variable name format                     | Must use the `interaction.CHAT.` prefix in the Studio            |

***

## Troubleshooting

**The chat button doesn't appear.**

* Give it a moment. The launcher is deliberately hidden while its saved appearance loads, so it fades in already branded instead of flashing in the default corner. It will always appear within about 10 seconds — falling back to the default corner, size and color if that request is slow or fails.
* Check that both the `<squawkvoice-widget>` tag and the `<script src="...">` tag are present in your HTML.
* Make sure the `assistant-id` and `public-key` attributes are filled in with your actual values (not placeholder text).
* Check your browser's developer console (F12) for any JavaScript errors.

**My customer variables aren't reaching the agent.**

* Confirm the `window.SquawkVoiceChatVariables` script block is placed *before* the widget loader script in your HTML.
* Check that your key names match exactly what you configured under **Chat Configuration → Widget Config → Chat Variables** — they are case-sensitive.
* Make sure your keys follow the naming rules (start with a letter, no hyphens or dots).
* Verify you're using widget version **1.1.0 or later** — check the `src` URL or set it to `@latest`.

**The agent doesn't use the variable values I passed.**

* Confirm you've created matching `interaction.CHAT.*` variables in your agent's variable editor.
* Confirm each mapping under **Chat Configuration → Widget Config → Chat Variables** has both a **Key** and a **Variable** selected.
* Check that the variable is referenced correctly in your agent's guidelines (e.g., `{{interaction.CHAT.customer_name}}`).

**I'm seeing "Guest" instead of the customer name.**

* Your default value is working as intended — it means the page didn't pass a value for that key. Check that `window.SquawkVoiceChatVariables` is being set with the correct data before the widget loads.