Create chat

Start a text chat session with a chat agent.

POSThttps://api.tried.com.au/create-chat

Starts a chat with a chat agent. If the agent's engine starts with the agent speaking (start_speaker: "agent"), the response already contains the agent's opening message. Send user messages with Create chat completion. The chat_started webhook is sent in the background.

You can call this from a browser with a public key (Authorization: Bearer public_key_...) from an allowed domain. The key's chat agent (or its weighted chat agents) is used, and public_key_id and origin are added to metadata.

Request#

Body#

Field	Type	Required	Description
`chat_agent_id`	string	One of these two	Chat agent to use.
`chat_agents`	object[]	One of these two	Weighted split for A/B tests, up to 10 entries of `{ "chat_agent_id", "weight" }` (weight 0 or more). One agent is picked by weight when the chat starts. Ignored when `chat_agent_id` is set.
`retell_llm_dynamic_variables`	object	No	Values for `{{variables}}` in the prompt. Default `{}`.
`metadata`	object	No	Any JSON stored on the chat. Default `{}`.

With chat_agents, the pick is stored in metadata.ab_test as { "chat_agent_id", "weight", "variants" }.

Example request#

curl -X POST "https://api.tried.com.au/create-chat" \
  -H "Authorization: Bearer $TRIED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "chat_agent_id": "chat_agent_6a7b8c9d0e1f2a3b4c5d6e7f",
  "retell_llm_dynamic_variables": {
    "customer_name": "Sam"
  },
  "metadata": {
    "ticket": "T-881"
  }
}'

const res = await fetch("https://api.tried.com.au/create-chat", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TRIED_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "chat_agent_id": "chat_agent_6a7b8c9d0e1f2a3b4c5d6e7f",
    "retell_llm_dynamic_variables": {
      "customer_name": "Sam"
    },
    "metadata": {
      "ticket": "T-881"
    }
  }),
});
const data = await res.json();

import os, requests

res = requests.post(
    "https://api.tried.com.au/create-chat",
    headers={"Authorization": f"Bearer {os.environ['TRIED_API_KEY']}"},
    json={
        "chat_agent_id": "chat_agent_6a7b8c9d0e1f2a3b4c5d6e7f",
        "retell_llm_dynamic_variables": {
            "customer_name": "Sam",
        },
        "metadata": {
            "ticket": "T-881",
        },
    },
)
data = res.json()

Response#

201 Created with the chat object.

{
  "chat_id": "chat_0a1b2c3d4e5f6a7b8c9d0e1f",
  "chat_agent_id": "chat_agent_6a7b8c9d0e1f2a3b4c5d6e7f",
  "agent_name": null,
  "chat_type": "api_chat",
  "channel": "api",
  "chat_status": "ongoing",
  "retell_llm_dynamic_variables": { "customer_name": "Sam" },
  "metadata": { "ticket": "T-881" },
  "start_timestamp": 1792310400000,
  "end_timestamp": null,
  "transcript": "Agent: Hi Sam, how can I help?",
  "message_with_tool_calls": [
    { "role": "agent", "content": "Hi Sam, how can I help?", "created_timestamp": 1792310400350 }
  ],
  "chat_analysis": null,
  "chat_cost": { "combined_cost": 0.002 }
}

Chat object fields#

Field	Type	Description
`chat_id`	string	`chat_` plus 24 hex characters.
`chat_agent_id`	string	Chat agent that runs the chat.
`agent_name`	string or null	Chat agent name. Filled by get and list; `null` on create, completion, update, end and rerun analysis responses.
`chat_type`	string	`api_chat`.
`channel`	string	`api` (this endpoint) or `widget` (website widget).
`chat_status`	string	`ongoing` or `ended`.
`retell_llm_dynamic_variables`	object	Variables for the chat.
`metadata`	object	Your metadata.
`start_timestamp`	integer	Start time, epoch ms.
`end_timestamp`	integer or null	End time, epoch ms.
`transcript`	string	`Agent: ...` and `User: ...` lines.
`message_with_tool_calls`	array	Messages and events, each with `created_timestamp`. See Message items.
`chat_analysis`	object or null	Set after the chat ends. See chat_analysis.
`chat_cost`	object	`combined_cost` in AUD. An opening agent message adds 0.003 and each completion adds 0.006.

Message items#

`role`	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`

chat_analysis#

Field	Type	Description
`chat_summary`	string	Summary of the chat.
`chat_successful`	boolean	Whether the agent completed the task.
`user_sentiment`	string	`Positive`, `Negative`, `Neutral` or `Unknown`.
`custom_analysis_data`	object	Values for the chat agent's `post_chat_analysis_data` fields.

Errors#

Status	When
`400`	Validation failed, neither `chat_agent_id` nor `chat_agents` was given, or no entry in `chat_agents` has a positive weight.
`401`	Missing or invalid API key, or a public key sent from an Origin not in its allowed domains.
`402`	Credit exhausted, budget reached or invoice overdue (`error_code` in the body).
`403`	The key's IP allowlist or scopes reject the request. This route needs the `calls` scope. With a public key: blocked country, reCAPTCHA failed, the key has no chat agent, or `chat_agent_id` is not one of the key's agents.
`404`	The chat agent, or its LLM or flow, does not exist.
`429`	Rate limit exceeded (with a public key, also its per-IP or per-key limit). See Rate limits.

See Errors for the body format.