Skip to content
TriedDocs
Build agents

Chat agents

Text agents for the chat API and the website widget, built on the same Retell LLM or conversation flow as your voice agents.

A chat agent answers by text. It runs the same Retell LLM (single or multi-prompt) or conversation flow engine as a voice agent, so one prompt can serve calls and chats. Chats have their own post-chat analysis, webhooks and history.

Chat agents answer on two channels:

  • The chat API.
  • The website widget, through a public key.
Chat Agents list

Create a chat agent#

Open Chat Agents and select Create chat agent:

Option What it does
From a voice agent Copies the voice agent's engine, post-call analysis fields, analysis prompts and webhook URL. The new agent is named "Voice agent name (chat)".
From a prompt or flow Pick an existing Retell LLM or conversation flow as the Engine.

Custom LLM engines are not supported for chat agents.

The API equivalents are Create chat agent and POST /convert-agent-to-chat/{agent_id}.

Settings#

Chat agent settings
Setting Field Default
Name agent_name "New chat agent"
Engine response_engine (retell-llm or conversation-flow) required
Analysis fields post_chat_analysis_data none
post_chat_analysis_model gpt-5.6-terra
analysis_summary_prompt, analysis_successful_prompt not set
End the chat after end_chat_after_silence_ms 1 hour
Closing message auto_close_message (up to 500 characters) not set
Webhook URL webhook_url the workspace webhook
Events webhook_events all three

End the chat after offers 10 minutes, 30 minutes, 1 hour, 4 hours, 12 hours or 24 hours. The API accepts 60,000 ms (1 minute) to 86,400,000 ms (24 hours). A chat with no new message for that long is closed and analysed.

When a chat times out and the agent has a Closing message, that message is added as the last agent message before the chat ends, so it appears in the chat, the transcript and the chat_ended webhook. Without one, the chat closes silently.

The engine's prompt, functions, knowledge bases and dynamic variables work as they do in calls. {{session_type}} is chat and {{chat_id}} holds the chat ID, so one prompt can behave differently in chats. Chat agents use the Australia/Sydney timezone for time variables.

Chat lifecycle#

  1. Start. Create chat with chat_agent_id (or weighted chat_agents), plus optional retell_llm_dynamic_variables and metadata. If the engine has a welcome message, it is the first message. The chat_started webhook is sent.
  2. Messages. Create chat completion with the chat ID and the user's message returns the agent's reply, including any function calls and flow node transitions.
  3. End. POST /end-chat/{chat_id}, or the silence timeout. The chat_ended webhook is sent.
  4. Analysis. Post-chat analysis runs and the chat_analyzed webhook is sent with chat_analysis.

The chat object has transcript, message_with_tool_calls (messages, tool_call_invocation items and node_transition items), chat_analysis (chat_summary, chat_successful, user_sentiment and your custom fields) and chat_cost.

curl https://api.tried.com.au/create-chat-completion \
  -H "Authorization: Bearer $TRIED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "chat_id": "chat_5e1d2c3b4a5968778695a4b3", "content": "Can I move my appointment to Friday?" }'

Test a chat agent#

Each chat agent has Test chat, which opens a live chat with the current settings. Function calls appear inline as Function: name. End chat closes it so you can check the analysis in Chat History.

Versions#

Chat agents have their own version history, separate from voice agents.

Chat agent versions
  • Publish saves a numbered snapshot of the current settings (Publish chat agent).
  • Versions lists the current draft (Editing) and every published version.
  • Restore copies a published version back into the draft.

Chats always use the chat agent's current settings. Publishing records history; restoring is how you roll back.

A/B tests#

Chat A/B tests split traffic across chat agents, not versions:

  • Give a widget public key two or more chat agents with weights on the Website widget tab.
  • Or pass chat_agents with weights to create-chat, for example [{ "chat_agent_id": "chat_agent_a...", "weight": 0.5 }, { "chat_agent_id": "chat_agent_b...", "weight": 0.5 }]. Up to 10 agents.

The chosen agent is stored in the chat's metadata.ab_test.

Widget key with weighted chat agents

Website widget#

The Website widget tab manages public keys for the embeddable chat widget. Each key has allowed domains, optional reCAPTCHA, a rate limit and blocked countries. See Deploy for the embed code.

Website widget public keys

SMS#

SMS conversations do not use chat agents. When a phone number receives a text and no SMS chat is open with that sender, Tried starts an SMS chat with the number's inbound voice agent, which replies by text using its own engine. You can also start one with Create SMS chat. Replies of STOP and similar opt the sender out. See Do-not-call.

Needs keys SMS chats need Telnyx messaging configured.

Pricing#

Chats cost $0.002 per message, counting both user and agent messages.

API#

Action Endpoint
Chat agents POST /create-chat-agent, GET /list-chat-agents, GET /get-chat-agent/{id}, PATCH /update-chat-agent/{id}, DELETE /delete-chat-agent/{id}
From a voice agent POST /convert-agent-to-chat/{agent_id}
Chats POST /create-chat, POST /create-chat-completion, POST /end-chat/{id}, GET /get-chat/{id}, GET /list-chats
Versions POST /publish-chat-agent/{id}, GET /get-chat-agent-versions/{id}, POST /restore-chat-agent-version/{id}/{version}