Go live

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.

  1. Name the key so you can recognise it later (default: Website widget).
  2. Pick the Environment: Live (production site) mints a pk_live_ key, Test (staging or local) mints a pk_test_ key. Both authorise the same agent.
  3. List the allowed sites, one origin per line (e.g. https://www.example.com and http://localhost:3000). Each entry is reduced to its scheme and host: paths and query strings are ignored, and each subdomain is a separate entry.
  4. 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

AttributeRequiredDefaultPurpose
data-keyYesnoneThe agent's publishable key. Without it the loader does nothing.
data-widgetNochatchat for the launcher bubble and panel, voice for the call pill. Any other value is treated as chat.
data-baseNothe origin the script was loaded fromOverrides the API origin the widget talks to.
data-accentNothe agent's widget theme, else #171717Hex colour of the chat launcher bubble. It does not affect the voice pill.
data-positionNorightleft puts the chat launcher and panel in the bottom left corner. It does not affect the voice pill.
data-offset-bottomNo20Gap 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-sideNo20Gap 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-textNoMade by Vertical AIOne line of text shown under the chat panel. It does not affect the voice pill.
data-credit-urlNonone, or the Vertical AI site for the default creditAn http or https link for the credit line. Any other value is ignored and the credit shows as plain text.
data-creditNononeoff hides the credit line. It does not affect the voice pill.
data-openNononeauto 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.

  • name becomes the caller's name, as if they'd typed it into a form before the call. It needs to read as a name, such as Mia or Mary-Kate O'Neil, with four words and 50 characters at most. Any other name is 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 visitor never 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.

On this page