Start widget chat

Start a chat from a web page with a public key and get a chat token for the rest of the conversation.

POSThttps://api.tried.com.au/public/chat/start

Starts a chat with the public key's chat agent and returns a chat_token for the follow-up calls. The chat widget calls this when a visitor opens it. Call it from the browser: the request must carry an Origin that the key allows. No Authorization header is used.

The key must have a chat agent (chat_agent_id or chat_agents). With chat_agents, one is picked at random by weight and the pick is stored in the chat's metadata.ab_test. The chat has channel: "widget", and its metadata records public_key_id and origin.

Request#

Body#

Field	Type	Required	Description
`public_key`	string	Yes	The public key, `public_key_...`. See Public keys.
`dynamic_variables`	object	No	String values only. Stored as the chat's `retell_llm_dynamic_variables`. Default `{}`.
`recaptcha_token`	string	No	reCAPTCHA v3 token. Needed when the key has `recaptcha_enabled`. The `x-recaptcha-token` header works too.

Checks#

In order: the Origin must match the key's allowed_domains, then the blocked country, per-IP, key rate limit and reCAPTCHA checks run, then the workspace's credit is checked. See Public key checks.

Example request#

# A browser sends Origin itself; cURL must set it to an allowed domain.
curl -X POST "https://api.tried.com.au/public/chat/start" \
  -H "Origin: https://www.example.com" \
  -H "Content-Type: application/json" \
  -d '{
  "public_key": "public_key_c6190cdfff21015a05ac4e386d1158ce",
  "dynamic_variables": { "page": "pricing" }
}'

// Runs in the browser on an allowed domain.
const res = await fetch("https://api.tried.com.au/public/chat/start", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    public_key: "public_key_c6190cdfff21015a05ac4e386d1158ce",
    dynamic_variables: { page: "pricing" },
    recaptcha_token: token,
  }),
});
const chat = await res.json(); // keep chat.chat_id and chat.chat_token

import requests

res = requests.post(
    "https://api.tried.com.au/public/chat/start",
    headers={"Origin": "https://www.example.com"},
    json={
        "public_key": "public_key_c6190cdfff21015a05ac4e386d1158ce",
        "dynamic_variables": {"page": "pricing"},
    },
)
chat = res.json()

Response#

201 Created

{
  "chat_id": "chat_0a1b2c3d4e5f6a7b8c9d0e1f",
  "chat_token": "Xq3v9mZ0b1Rk2LpT8wYc4nHs6aGd5eFj7uQi0oPl1Ns",
  "messages": [
    { "role": "agent", "content": "Hi, how can I help today?", "created_timestamp": 1792310400100 }
  ]
}

Field	Type	Description
`chat_id`	string	The new chat.
`chat_token`	string	Authorises Send widget chat message and End widget chat for this chat. It is derived from the chat ID with a server secret and does not expire, so keep it only in the page.
`messages`	array	Message items so far. Holds the greeting when the agent speaks first, otherwise empty.

Errors#

Status	When
`400`	Validation failed, for example a missing `public_key` or a non-string value in `dynamic_variables`.
`402`	Credit exhausted or monthly budget reached (`error_code` `credit_exhausted` or `budget_reached`).
`403`	`Unknown public key` (no such key, or the key has no chat agent), `Origin <origin> is not allowed for this key`, a blocked country, or a failed reCAPTCHA check.
`404`	The key's chat agent no longer exists.
`429`	Per-IP or public key rate limit exceeded. See Rate limits.

See Errors for the body format.