Embed Widgets

Embed Widgets let your backend authenticate a website visitor, while Vonative provides the chat, voice, or LiveAvatar experience. The visitor token is signed on your server. Never send a widget signing secret to the browser in production.

Type	Experience	Runtime
`chat_only`	Text chat	Chat Runtime
`voice_chat`	Voice conversation with chat transcript	LiveKit Runtime Agent
`liveavatar`	Voice/video LiveAvatar conversation	LiveKit Runtime Agent + LiveAvatar

Every widget targets exactly one assistant or workflow and supports popup or inline display mode.

Integration flow

Your backend creates a widget through the authenticated Vonative API.
Save the returned signing secret in your server-side secret store. It is returned only at creation and rotation.
Configure each website origin that may load the widget.
When an authenticated visitor loads your page, your backend mints a short-lived visitor JWT.
Your page loads the Vonative embed script with the widget ID, visitor JWT, and any optional cosmetic overrides.
The script verifies the origin and token through Vonative, then starts the configured runtime.

Use your Vonative API bearer token from a trusted server.

curl -X POST https://api.vonative.com/v1/widgets \
  -H "Authorization: Bearer YOUR_VONATIVE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Website support",
    "widget_type": "chat_only",
    "display_mode": "popup",
    "assistant_id": "ASSISTANT_UUID",
    "allowed_origins": ["https://www.example.com"],
    "branding": {
      "color": "#0A84FF",
      "logo_url": "https://cdn.example.com/logo.png",
      "theme": "system"
    }
  }'

Pass either assistant_id or workflow_id, using its public UUID, not its internal database ID. For LiveAvatar, also pass an avatar_id.

Supported branding keys

The widget branding object supports these stable keys:

Key	Type	Rules
`color`	string	Strict hex color in `#RRGGBB` format
`logo_url`	string	Absolute `https://` URL
`theme`	string	`light`, `dark`, or `system`

Manage allowed origins

Allowed origins are exact origins such as https://www.example.com. Wildcard subdomains use *.example.com. Do not include paths.

curl -X PATCH https://api.vonative.com/v1/widgets/WIDGET_UUID \
  -H "Authorization: Bearer YOUR_VONATIVE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "allowed_origins": [
      "https://www.example.com",
      "http://localhost:3000"
    ]
  }'

The authenticated management endpoints are:

GET    /v1/widgets
POST   /v1/widgets
GET    /v1/widgets/{widget_id}
PATCH  /v1/widgets/{widget_id}
DELETE /v1/widgets/{widget_id}
POST   /v1/widgets/{widget_id}/rotate-secret

Rotating the secret invalidates visitor JWTs signed with the previous secret.

Mint a visitor JWT

Mint a fresh HS256 token on your server for each page load or session refresh. Tokens must include:

Claim	Required	Description
`sub`	Yes	Your stable visitor identity
`aud`	Yes	The widget `public_embed_id`, for example `bw_abc123`
`exp`	Yes	Unix expiry no more than 15 minutes from issuance
`name`	No	Visitor display name
`metadata`	No	Visitor metadata object or string
`attrs`	No	Visitor attributes object

Example using the jose package in a Node.js server route:

import { SignJWT } from "jose";

const secret = new TextEncoder().encode(process.env.VONATIVE_WIDGET_SIGNING_SECRET);

export async function createVisitorToken(visitor: { id: string; name?: string }) {
  return new SignJWT({
    name: visitor.name,
    metadata: { source: "web" },
    attrs: { plan: "pro" }
  })
    .setProtectedHeader({ alg: "HS256", typ: "JWT" })
    .setSubject(visitor.id)
    .setAudience(process.env.VONATIVE_WIDGET_ID!)
    .setIssuedAt()
    .setExpirationTime("15m")
    .sign(secret);
}

job metadata also stays JWT-only. Do not trust or forward those values from snippet HTML.

Cosmetic-only HTML snippet

You can add cosmetic overrides directly to the snippet. These override saved widget branding for that placement only.

<script
  src="https://embed.vonative.com/embed-popup.js"
  data-vonative-widget="bw_abc123"
  data-vonative-token="SERVER_MINTED_VISITOR_JWT"
  data-vonative-color="#0A84FF"
  data-vonative-logo="https://cdn.example.com/logo.png"
  data-vonative-theme="system"
></script>

For an inline widget, add data-vonative-mode="inline":

<script
  src="https://embed.vonative.com/embed-popup.js"
  data-vonative-widget="bw_abc123"
  data-vonative-token="SERVER_MINTED_VISITOR_JWT"
  data-vonative-mode="inline"
></script>

The embed accepts legacy data-boboyii-* attributes during the compatibility window, but new integrations should emit only data-vonative-*.

Trusted vs untrusted fields

The snippet is only for widget bootstrapping and cosmetics. Visitor identity stays in the signed JWT.

LiveKit concept	Vonative support
`data-lk-color`	`data-vonative-color`
`data-lk-logo`	`data-vonative-logo`
`data-lk-theme`	`data-vonative-theme`
`data-lk-identity`	JWT `sub` claim
`data-lk-name`	JWT `name` claim
`data-lk-metadata`	JWT `metadata` claim
`data-lk-attrs`	JWT `attrs` claim
`data-lk-job-metadata`	JWT-only claim path, not trusted from snippet HTML

SPA token refresh

For single-page apps, retrieve a newly minted token from your backend before mounting the script. Remove an existing script before adding a new one to avoid mounting twice.

export async function mountVonativeWidget() {
  const { token } = await fetch("/api/vonative/widget-token").then((res) => res.json());

  document.querySelector("script[data-vonative-widget]")?.remove();

  const script = document.createElement("script");
  script.src = "https://embed.vonative.com/embed-popup.js";
  script.dataset.vonativeWidget = "bw_abc123";
  script.dataset.vonativeToken = token;
  script.dataset.vonativeTheme = "dark";
  script.async = true;
  document.body.appendChild(script);
}

Test and troubleshoot

Test from a page hosted at an allowed origin, for example http://localhost:3000. Do not test by opening embed.vonative.com directly.

Response	Likely cause	Fix
`404 Widget not found`	The widget is disabled, deleted, or the page origin is not allowed	Enable the widget and add the exact origin via `PATCH`
`401 Invalid widget visitor token`	Incorrect signature, expired token, or mismatched audience	Sign with the current secret, set `aud` to the public widget ID, and use a maximum 15-minute expiry
Widget does not mount	Required widget/token attributes are missing	Include `data-vonative-widget` and `data-vonative-token`
Cosmetic override does not apply	Invalid color, logo URL, or theme	Use `#RRGGBB`, `https://...`, and one of `light`, `dark`, `system`

The public runtime endpoints are used by the embed script and do not require your Vonative API bearer token:

GET  /v1/public/widgets/{public_embed_id}/config
POST /v1/public/widgets/{public_embed_id}/bootstrap

They validate the requesting origin and the visitor JWT before returning any runtime connection details.

Getting Started

Assistants

WebRTC & Realtime

Workflows

Phone Numbers

Tools

Developer

Billing

Monitoring

Embed Widgets

Embed Widgets

Widget types

Integration flow

Create a widget

Supported branding keys

Manage allowed origins

Mint a visitor JWT

Cosmetic-only HTML snippet

Trusted vs untrusted fields

SPA token refresh

Test and troubleshoot

​Embed Widgets

​Widget types

​Integration flow

​Create a widget

​Supported branding keys

​Manage allowed origins

​Mint a visitor JWT

​Cosmetic-only HTML snippet

​Trusted vs untrusted fields

​SPA token refresh

​Test and troubleshoot

Embed Widgets

Widget types

Integration flow

Create a widget

Supported branding keys

Manage allowed origins

Mint a visitor JWT

Cosmetic-only HTML snippet

Trusted vs untrusted fields

SPA token refresh

Test and troubleshoot