Install a widget
Create a publishable key, paste the loader script, and set the attributes it accepts.
A widget needs a publishable key that identifies the agent and a script tag on your page. Both come from the agent's Channels > Website chat page. For what the widgets do once installed, see Website widgets.
Create a publishable key
On the agent's Website chat page, under Website keys, choose Create key.
- Name the key so you can recognise it later (default:
Website widget). - Pick the Environment: Live (production site) mints a
pk_live_key, Test (staging or local) mints apk_test_key. Both authorise the same agent. - List the allowed sites, one origin per line (e.g.
https://www.example.comandhttp://localhost:3000). Each entry is reduced to its scheme and host: paths and query strings are ignored, and each subdomain is a separate entry. - Create key, then copy it from the confirmation. It is shown once.
Allowed sites cannot be edited after creation. To change the list, revoke the key and create a new one, then update the script tag on your site. Revoking takes effect immediately, and any widget still using that key stops working.
A key with no allowed sites cannot connect from any website.
Install the chat widget
Paste this before the closing </body> tag of every page you want the bubble
on, with your own key in data-key:
<script src="https://app.verticalai.com.au/embed/widget.js" data-key="pk_live_…" async></script>The loader adds a round launcher button in the bottom right corner. Clicking it opens the chat panel in an iframe. Closing the panel hides it but keeps the conversation, so reopening resumes where the visitor left off.
Install the voice widget
The voice widget uses the same script with data-widget="voice":
<script src="https://app.verticalai.com.au/embed/widget.js" data-key="pk_live_…" data-widget="voice" async></script>It mounts the call pill in the bottom right corner on a transparent overlay. The iframe requests microphone access, so the browser prompts the visitor on their first call. If the agent's voice surface is off, or the key is not allowed on that site, the overlay renders nothing.
Install both widgets
To run both, add both script tags. They can share the same key.
<script src="https://app.verticalai.com.au/embed/widget.js" data-key="pk_live_…" async></script>
<script src="https://app.verticalai.com.au/embed/widget.js" data-key="pk_live_…" data-widget="voice" async></script>Script attributes
| Attribute | Required | Default | Purpose |
|---|---|---|---|
data-key | Yes | none | The agent's publishable key. Without it the loader does nothing. |
data-widget | No | chat | chat for the launcher bubble and panel, voice for the call pill. Any other value is treated as chat. |
data-base | No | the origin the script was loaded from | Overrides the API origin the widget talks to. |
data-accent | No | the agent's widget theme, else #171717 | Hex colour of the chat launcher bubble. It does not affect the voice pill. |
data-position | No | right | left puts the chat launcher and panel in the bottom left corner. It does not affect the voice pill. |
data-offset-bottom | No | 20 | Gap in pixels between the chat launcher and the bottom of the window, from 0 to 1000. It does not affect the voice pill. |
data-offset-side | No | 20 | Gap in pixels between the chat launcher and the side of the window, from 0 to 1000. It does not affect the voice pill. |
data-credit-text | No | Made by Vertical AI | One line of text shown under the chat panel. It does not affect the voice pill. |
data-credit-url | No | none, or the Vertical AI site for the default credit | An http or https link for the credit line. Any other value is ignored and the credit shows as plain text. |
data-credit | No | none | off hides the credit line. It does not affect the voice pill. |
data-open | No | none | auto opens the chat panel when the page loads, without moving the visitor's cursor or focus, on screens wider than 640 px. On narrower screens the panel is full screen, so it stays closed. A visitor who closes it is not shown it open again in that browser tab. It does not affect the voice pill. |
Use a plain hex value such as #0a7cff: the loader ignores any other colour
syntax and keeps the default.
Tell the agent who is calling
A page that starts voice calls from its own code can tell the agent about the
person on the call. Add a visitor object to the JSON body of the start
request, POST https://app.verticalai.com.au/api/embed/start, sent from one of
the key's allowed sites with the publishable key as a bearer token:
{
"visitor": {
"name": "Mia",
"age": 5,
"favourite_game": "Dino Dig"
}
}The agent has these details from the start of the call.
namebecomes the caller's name, as if they'd typed it into a form before the call. It needs to read as a name, such asMiaorMary-Kate O'Neil, with four words and 50 characters at most. Any othernameis passed on with the rest.- Every other entry reaches the agent as a detail about the person. The agent uses them to know who it's talking to and how best to talk with them, and never treats them as instructions.
- Values can be text or numbers. Keys are cut at 40 characters and values at
200. The first eight usable entries are kept and anything else is ignored,
so a malformed
visitornever stops the call starting. - A greeting set on the agent is spoken as written. Leave the greeting empty if you want the agent to open with the visitor's name.
- The details are kept with the call's record. Send only what the agent needs.
The script tag doesn't send visitor details.