chat_started | Tried Docs

Sent when a chat session with a chat agent is created through the API or the website widget.

chat_started tells you a text conversation with one of your chat agents has begun. Chat events cover the API chat channel and the website chat widget.

Event	Meaning
`chat_started`	A chat was created
`chat_ended`	The chat was ended or timed out
`chat_analyzed`	Post-chat analysis is stored

SMS conversations on phone numbers are handled separately and do not send chat events.

When it fires#

Once per chat, right after the chat is created:

You call POST /create-chat with a chat_agent_id, or with chat_agents for a weighted A/B pick.
A visitor starts a conversation in the website widget (/public/chat/start).

If the chat agent's engine speaks first, the greeting is generated before the event is sent, so the payload already contains the first agent message.

Which settings enable it#

chat_started in the chat agent's webhook_events (on by default).
URL: the chat agent's webhook_url, else the workspace webhook URL.
Timeout: the workspace timeout, else 10 s.

Set these in Chat Agents, Settings (Webhook URL, Events) or with update-chat-agent. See Register a webhook.

Payload#

The body is { event, chat }.

{
  "event": "chat_started",
  "chat": {
    "chat_id": "chat_2d7f1a4c8e0b3f6a9c5e1d42",
    "chat_agent_id": "chat_agent_0c4f8e2a6b1d3f5a7c9e2b40",
    "agent_name": "Receptionist (chat)",
    "chat_type": "api_chat",
    "channel": "widget",
    "chat_status": "ongoing",
    "retell_llm_dynamic_variables": {
      "business_name": "Bondi Dental"
    },
    "metadata": {
      "origin": "https://www.bondidental.com.au",
      "public_key_id": "pk_4b8e1d5a9c2f6e0a3d7b1c58"
    },
    "start_timestamp": 1760679000210,
    "end_timestamp": null,
    "transcript": "Agent: Hi, I'm Ava from Bondi Dental. How can I help?",
    "message_with_tool_calls": [
      { "role": "agent", "content": "Hi, I'm Ava from Bondi Dental. How can I help?", "created_timestamp": 1760679000845 }
    ],
    "chat_analysis": null,
    "chat_cost": { "combined_cost": 0.002 }
  }
}

Fields#

Field	Type	Description
`chat_id`	string	Chat id, prefix `chat_`
`chat_agent_id`	string	The chat agent handling the chat. For A/B starts, the agent that was picked
`agent_name`	string or null	The chat agent's name
`chat_type`	string	`api_chat` for API and widget chats
`channel`	string	`api` for chats created with the API, `widget` for the website widget
`chat_status`	string	`ongoing`
`retell_llm_dynamic_variables`	object	Variables passed when the chat was created
`metadata`	object	Your metadata. Widget chats add `origin` (the page origin) and `public_key_id`. A/B starts add `ab_test` with the picked agent, its weight and all variants
`start_timestamp`	integer	Unix ms
`end_timestamp`	null	Not ended yet
`transcript`	string	`Agent:` and `User:` lines so far
`message_with_tool_calls`	array	Messages, tool call invocations and node transitions, each with `created_timestamp`
`chat_analysis`	null	Arrives in `chat_analyzed`
`chat_cost.combined_cost`	number	AUD so far. Chats are billed per message

Message items#

`role`	Other fields
`agent`, `user`	`content`, `created_timestamp`
`tool_call_invocation`	`tool_call_id`, `name`, `arguments`, `created_timestamp`
`node_transition`	`former_node_id`, `new_node_id`, `created_timestamp`

How to respond#

Reply 2xx. The body is ignored. Delivery is in the background and retried up to 3 times (1 s, 2 s, 4 s). Your reply cannot change the chat; use create-chat-completion to take part in it.