Skip to main content
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.
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.

​
Paste It Into Your Page

Open your website’s HTML and paste the snippet just before the closing </body> tag:
That’s it — save your file, reload your site, and the chat button should appear.
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.

​
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. 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.
Chat variables require widget version 1.1.0 or later. If you’re on latest, you’re already covered.

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

​
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)
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.

​
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.
Do not enter real customer information in Test Value fields — use representative sample data.
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.
In a real application, you’d replace the hardcoded values with dynamic ones from your server or session:
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.

​
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

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