Create a chat widget

Creates a widget and mints its publicKey — the non-secret key that goes in the embed snippet. A publicKey in the request body is ignored.

A widget with an empty allowedOrigins list is valid and will not load anywhere: the public endpoints fail closed on origin. That is deliberate, so a snippet lifted from one site cannot be run on another.

Authorization

bearerAuth

AuthorizationBearer <token>

A Tandem bearer token. Requests are scoped to the organization the token belongs to; no organization header is required.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

The widget's name inside Tandem: how it is labelled in the dashboard. Visitors never see it — the chat header shows displayName, or this name when there is none.

Length1 <= length <= 60

displayName?string

The bot name a visitor reads in the chat header. Omitted, the header shows name.

Separate from name so a persona can be shared: several widgets may use the same display name while each keeps a distinct name you can tell apart in the dashboard. It is not required to be unique.

Length1 <= length <= 60

agentId?string

The voice agent that answers this chat. Its system prompt, tools, knowledge base, skills, and safety settings all apply. Voice-only settings do not: nothing is synthesized or transcribed, and the telephony built-ins (DTMF capture, recording control, warm transfer) are unavailable in a chat.

Supply either this or workflowId, never both and never neither. Neither is marked required because exactly one of the two is, and that is a rule this schema cannot express; a request naming both or naming neither is rejected with invalid_target.

workflowId?string

The workflow that answers this chat, instead of an agent. A scripted conversation rather than a model deciding what to say: the workflow starts on the visitor's first message and a Send Chat Message node writes into their panel, optionally waiting for a typed reply.

The widget's own greeting still greets, so nothing about the embed snippet changes. The workflow must have a published version — unlike an agent, an unpublished one cannot answer at all, so it is rejected with workflow_not_published rather than accepted.

Voice nodes do not work here: Play Message, the recording nodes, Disconnect and the transfer nodes all need a phone call. The conversation ends when the workflow runs out of nodes.

description?string

One line under the bot name.

Lengthlength <= 280

Default""

avatarUrl?string

An https:// image URL. http:// and data: URLs are rejected — the first is blocked as mixed content on every site the allowlist permits, and the second would put unbounded bytes in every visitor's page. Omitted, the widget draws the initials of the name in the header.

Header only. It does not fill the launcher bubble — that is launcherIcon.

Lengthlength <= 2048

showAvatar?boolean

Whether the chat header shows an image at all. Set to false and the header is the bot name alone — no picture and no initials disc.

Different from leaving avatarUrl empty, which draws the initials.

Defaulttrue

position?string

Which corner of the visitor's screen the launcher, and the panel above it, sits in.

Default"bottom-right"

Value in

"bottom-right"
"bottom-left"

launcherIcon?string

The glyph on the launcher bubble. bubble and message are drawn by the widget itself; custom renders launcherIconUrl instead.

custom with no usable launcherIconUrl falls back to bubble rather than rendering a broken image.

Default"bubble"

Value in

"bubble"
"message"
"custom"

launcherIconUrl?string

The launcher's image when launcherIcon is custom, and ignored otherwise. Same rule as avatarUrl: https:// only, no data: URLs.

Lengthlength <= 2048

brandColor?string

Your brand color as a six-digit hex, e.g. #16a34a. It fills the chat header, the launcher bubble, the send button, and the visitor's own messages. The text color on top of it is not configurable — the widget picks black or white per color, whichever is readable, so a pale brand color cannot produce a header nobody can read.

Six digits only: no shorthand (#4f5), no rgb(), and no color keyword. Omitted, the widget uses its own default.

Match^#[0-9a-fA-F]{6}$

greeting?string

The first message a visitor sees. Omitted, the agent's own greeting is used — which is usually written for a phone call.

Lengthlength <= 1000

allowedOrigins?array<>

The websites allowed to open this widget. This is the widget's authorization, not the public key — the key is readable by anyone who views your page source, and what they cannot do is make a browser send someone else's Origin.

An empty list allows nothing. A widget saved with no origins does not work anywhere, which you notice immediately; the alternative — empty meaning "any site" — is a widget that works in testing and lets anyone on the internet spend your model and tool budget.

Itemsitems <= 20

Default[]

Response Body

`application/json`

curl -X POST "https://example.com/v1/agent-media/chat-widgets" \  -H "Content-Type: application/json" \  -d '{    "name": "string"  }'

{  "widget": {    "id": "string",    "publicKey": "string",    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "name": "string",    "displayName": "string",    "agentId": "string",    "workflowId": "string",    "description": "",    "avatarUrl": "string",    "showAvatar": true,    "position": "bottom-right",    "launcherIcon": "bubble",    "launcherIconUrl": "string",    "brandColor": "string",    "greeting": "string",    "allowedOrigins": []  }}

{  "error": "string",  "errors": [    {      "field": "string",      "message": "string"    }  ]}

{  "error": "string",  "message": "string",  "limit": 0,  "length": 0,  "reason": "string"}

Create a chat widget

Authorization

Request Body

Response Body

201application/json

400application/json

401application/json

`application/json`

`application/json`

`application/json`