Chat Widget

​

Before You Start

• An agent built and saved in 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)
• The address of each website that will carry the widget, such as https://www.example.com — you’ll add it to the agent’s Allowed Origins list in Step 1
• Access to your website’s HTML source code

​

Step 1 — Add the Widget to Your Website

• Embed Code — the theme and version dropdowns, and the snippet to copy
• Widget Config — Allowed Origins, Chat Variables, and your Widget Key
• Customize Widget — how the widget looks (logo, avatar, name, disclaimer, position, size and colors) and its Proactive notification

​

Get Your Embed Code

1. Open your agent in Build → AI Agents.
2. Go to Chat Configuration. The Embed Code section is at the top.
3. Open the version dropdown (the one with the tag icon) and choose a 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. Open the theme dropdown and choose your starting theme: Default (Light) or Dark. Visitors can still switch between light and dark with the sun/moon button in the widget header.
5. Copy the generated embed snippet with Copy.

​

Widget Versions

​

Allow Your Website

1. In Chat Configuration, find Widget Config → Allowed Origins.
2. Type your website’s address, for example https://www.example.com, and click Add Origin.
3. Studio asks you to confirm. Check that the address is correct and one you trust, then click Add Origin in the dialog.

• Start with http:// or https://.
• Leave out any path. Use https://www.example.com, not https://www.example.com/contact. A trailing slash is removed for you.
• Add a port only if the site uses a non-standard one, such as http://localhost:3000. The same domain on a different port is a different origin.
• Each domain and subdomain needs its own entry. https://example.com and https://www.example.com are different origins, so add both if your site answers on both. Wildcards such as *.example.com are not supported. Studio may still let you save an entry like https://*.example.com without showing an error, but it never matches a real site, so a site covered only by that entry stays blocked.
• Type the address in lowercase. Studio doesn’t accept capital letters in an origin.

​

Paste It Into Your Page

<script>
  window.SquawkVoiceChatVariables = {
    "email": <REPLACE-WITH-EMAIL>
  };
</script>

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

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

​

What Visitors See First

​

Your Widget Key

​

Step 2 — Customize the Widget’s Appearance

• Show Preview opens a floating, live preview of the widget so you can see changes as you make them. It becomes Hide Preview while the preview is open.
• Reset to Defaults restores the default colors, position and size. Your uploaded logo, AI Agent Name, AI Disclaimer, Proactive notification and widget version are left as they are.

​

Proactive Notification

​

Behaviour worth knowing

• The bubble appears only when all of these are true: the widget started minimized (the launcher is closed), the visitor isn’t returning to a chat from the last 10 minutes, they have never opened the chat in that browser, they haven’t dismissed the bubble on this visit, and the delay has elapsed.
• A visitor can dismiss the bubble with the X that appears when they hover over it. Dismissing hides it for that visit only, so it can come back the next time they visit.
• Once a visitor opens the chat, the bubble does not show again in that browser. This is remembered in the visitor’s own browser, separately for each agent.
• As with the other appearance settings, you don’t need to touch the embed code. A change reaches your site straight away for an agent that has never been published, and at your next Publish for one that has.

​

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.

​

Skip the Email Screen

• You don’t create or map it. The first row of Chat Variables is always email, read-only, linked to interaction.CHAT.email with DEFAULT VALUE Provided at runtime. You can’t add your own email key or create that variable — so leave it out of Parts A and B below, and just pass it in Part C.
• The value has to look like an email address. If it is missing, blank or not a valid address, visitors see the Welcome! screen as usual.
• The agent can use it. The address is available to the agent as {{interaction.CHAT.email}}.

​

Part A — Create the Variables in the Studio

1. Open your agent and go to its Variables card (see Variables Manager).
2. Click Create variable.
3. Set Type to Chat widget. (The other choice, Custom, is for variables the widget doesn’t fill in.)
4. In Name, type the part after the fixed interaction.CHAT. prefix — for example customer_name. Studio adds the prefix for you.
5. Click Create variable to save.

​

Part B — Set Up the Mappings in Widget Config

1. In your agent, go to Chat Configuration → Widget Config → Chat Variables. It is a table with the columns KEY, VARIABLE, DEFAULT VALUE and TEST VALUE.
2. Click the empty Add key… row at the bottom of the table, type the name you’ll use in your JavaScript (e.g., customerName), and press Enter (or click away). The key is saved as a new row straight away.
3. In that row’s VARIABLE column, open Select or create variable. Pick a variable you created in Part A, or type a new name and click Add Variable — the variable is created with the interaction.CHAT. prefix and mapped in one step.
4. Optionally fill in the row’s other two columns. They stay greyed out until the row has a variable.
   • DEFAULT VALUE — a fallback if the page doesn’t provide a value (e.g., Guest)
   • TEST VALUE — a sample value used only in the in-platform test chat (e.g., Sarah Johnson)

​

Preview With Test Values

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.

• Must start with a letter (not a number or symbol)
• Can only contain letters (a–z, A–Z), numbers (0–9), and underscores (_)
• Cannot end with an underscore
• Maximum 64 characters
• Each key must be unique, and each variable can be mapped to only one key
• email is reserved, in any capitalization — it is the built-in key described in Skip the Email Screen

​

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"
></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 Visitors See in the Chat Window

• Header controls. New session starts a fresh chat (it is turned off while the chat is still connecting). The sun/moon button switches between light and dark. The X minimizes the chat back to the launcher.
• Powered by SquawkVoice.ai. A small link with this label sits under the message box, and under the Start button on the email screen. There is no Studio setting to remove it.

​

When a Chat Ends

​

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: text, numbers and true/false are accepted and sent as text; other 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 (for an agent you’ve published, the mappings as they were at its last Publish), plus the built-in email key. 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 in-conversation actions.

​

Limits & Constraints

​

Troubleshooting

• Check that your website’s address is on the agent’s Allowed Origins list (Chat Configuration → Widget Config → Allowed Origins), spelled exactly as visitors reach it — https://example.com and https://www.example.com are separate entries.
• 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). If you regenerated the Widget Key, paste in the updated snippet.
• Check your browser’s developer console (F12) for any JavaScript errors.

• The message reads “This chat cannot be accessed from this website.” It means the page’s address isn’t on the Allowed Origins list, or the list is empty. Add the exact address under Chat Configuration → Widget Config → Allowed Origins — see Allow Your Website.

• That is a general message with a Try Again button, so it can have more than one cause. One cause is a wallet balance that can’t cover a chat session. Each chat session is charged to your wallet when the visitor sends their first message, and the balance is checked when the chat opens and again at that first message. A visitor can’t start a chat when the balance is too low to pay for one, and if it falls too low in between, the screen appears after their first message and that message isn’t answered.
• The visitor isn’t told why, but you can see it in Chat History. A chat refused when it opens is listed as a REJECTED row with INSUFFICIENT_BALANCE as its Disposition, and Chat Analytics counts it as Insufficient-Balance. A chat refused at the first message is listed with the same Disposition and a cost of $0.00. A refused chat is never billed. See Chat History.
• Check your balance under Manage → Billing → Overview, then add credits or turn on auto top-up. Billing isn’t in an account user’s default sidebar. See Navigating Studio to add it or find it with search.

• That is the Welcome! screen, and it is on by default. To skip it, pass a valid email for each visitor — see Skip the Email Screen.
• If you already pass email and visitors still see the screen, check that the value is a real email address, that the script block comes before the loader script, and that you’re on widget version 1.2.0 or later.

• Confirm the window.SquawkVoiceChatVariables script block is placed before the widget loader script in your HTML.
• Confirm you replaced every <REPLACE-WITH-…> placeholder in the snippet. While one is still there, the browser console shows a script error and no values are passed.
• Check that your key names match exactly what you configured under Chat Configuration → Widget Config → Chat Variables — they are case-sensitive.
• If the agent has been published, check that you published after adding the mapping. A key added since the last Publish is ignored by the live widget.
• Make sure your keys follow the naming rules (start with a letter, no hyphens or dots, no trailing underscore).
• Verify you’re using widget version 1.1.0 or later — check the src URL or set it to @latest.

• Confirm each mapping points at a matching interaction.CHAT.* variable on your agent’s Variables card.
• 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}}).

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

• If the agent has been published, your site shows the published settings until you publish again. Look in the agent’s header: Unpublished edits means changes are waiting. Select Publish, review the changes, and choose Confirm & Publish. See Publishing Your Agent.
• Show Preview and the Studio’s test chat always show your latest edits, so they can differ from your site until you publish.
• Allowed Origins and the Widget Key don’t wait for a Publish, and a new widget version only takes effect once you paste the updated snippet into your site.
• Reload the page. The widget reads its settings each time a page loads.

• Studio shows “Cannot delete variable while it is still used: the published chat widget of “agent name” maps it. Publish the agent first, then delete the variable.” The agent’s live version still maps that variable, even if you have since removed the mapping from Chat Variables. Remove the mapping if it is still there, Publish the agent, then delete the variable.

​

What the error screens mean