Chat Widget

​

Before You Start

• An agent built and saved in Studio → Build → AI Agents
• The assistant ID and public key for that agent (found in its Embed settings panel)
• Access to your website’s HTML source code

​

Step 1 — Add the Widget to Your Website

​

Get Your Embed Code

1. Open your agent in Studio → Build → AI Agents.
2. Click the Embed tab (or Widget Settings).
3. Choose a Widget Version — use latest unless you need to pin a specific release.
4. Choose your starting theme: light or dark.
5. Copy the generated embed snippet.

​

Paste It Into Your Page

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

​

Step 2 — Customize the Widget’s Appearance

​

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

​

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.

​

Part A — Create the Variables in the Studio

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.

​

Part B — Set Up the Mappings in Widget Settings

1. In your agent settings, go to Widget Settings → 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)

• 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

​

Part C — Inject the Values on Your Web Page

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

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

​

What Happens Behind the Scenes

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 in your Widget Settings. 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

​

Troubleshooting

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

• 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 in Widget Settings — 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.

• Confirm you’ve created matching interaction.CHAT.* variables in your agent’s variable editor.
• Confirm each mapping in Widget Settings 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}}).

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