Create SMS chat

Start an outbound SMS conversation driven by an agent.

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

Creates an SMS conversation from one of your numbers and sends the opening text. Replies from the recipient are answered by the agent. A reply of a STOP keyword ends the chat and flags the contact do-not-call.

The opening text is initial_message if you give one; otherwise the agent's LLM begin_message; otherwise one reply generated by the agent. {{variables}} in it are filled from retell_llm_dynamic_variables.

Sending real SMS needs a Telnyx key; without one, messages are stored with the mock provider. Needs keys

Request#

Body#

Field	Type	Required	Description
`from_number`	string	Yes	A number in this workspace.
`to_number`	string	Yes	Recipient, in E.164 format.
`override_agent_id`	string	No	Agent that writes the replies. Default: a weighted pick from the number's `outbound_agents`.
`retell_llm_dynamic_variables`	object	No	Variables for the agent. Non-string values are stored as JSON strings. Default `{}`.
`metadata`	object	No	Any JSON stored on the chat. Default `{}`.
`initial_message`	string	No	First message to send. Required when no agent can be found.

Example request#

curl -X POST "https://api.tried.com.au/create-sms-chat" \
  -H "Authorization: Bearer $TRIED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "from_number": "+61291234567",
  "to_number": "+61412345678",
  "override_agent_id": "agent_3f9a1c0b2d4e5f6a7b8c9d0e",
  "retell_llm_dynamic_variables": {
    "customer_name": "Sam"
  },
  "initial_message": "Hi {{customer_name}}, it'\''s Bright Dental. Reply here to reschedule your visit."
}'

const res = await fetch("https://api.tried.com.au/create-sms-chat", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TRIED_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "from_number": "+61291234567",
    "to_number": "+61412345678",
    "override_agent_id": "agent_3f9a1c0b2d4e5f6a7b8c9d0e",
    "retell_llm_dynamic_variables": {
      "customer_name": "Sam"
    },
    "initial_message": "Hi {{customer_name}}, it's Bright Dental. Reply here to reschedule your visit."
  }),
});
const data = await res.json();

import os, requests

res = requests.post(
    "https://api.tried.com.au/create-sms-chat",
    headers={"Authorization": f"Bearer {os.environ['TRIED_API_KEY']}"},
    json={
        "from_number": "+61291234567",
        "to_number": "+61412345678",
        "override_agent_id": "agent_3f9a1c0b2d4e5f6a7b8c9d0e",
        "retell_llm_dynamic_variables": {
            "customer_name": "Sam",
        },
        "initial_message": "Hi {{customer_name}}, it's Bright Dental. Reply here to reschedule your visit.",
    },
)
data = res.json()

Response#

201 Created with the SMS chat object.

{
  "chat_id": "chat_7e8f9a0b1c2d3e4f5a6b7c8d",
  "chat_type": "sms",
  "agent_id": "agent_3f9a1c0b2d4e5f6a7b8c9d0e",
  "chat_status": "ongoing",
  "from_number": "+61291234567",
  "to_number": "+61412345678",
  "retell_llm_dynamic_variables": { "customer_name": "Sam" },
  "metadata": {},
  "start_timestamp": 1792310400000,
  "end_timestamp": null,
  "messages": [
    {
      "message_id": "sms_1f2e3d4c5b6a7f8e9d0c1b2a",
      "chat_id": "chat_7e8f9a0b1c2d3e4f5a6b7c8d",
      "call_id": null,
      "direction": "outbound",
      "from_number": "+61291234567",
      "to_number": "+61412345678",
      "content": "Hi Sam, it's Bright Dental. Reply here to reschedule your visit.",
      "status": "queued",
      "provider_message_id": "40318f6c-8a2b-4d7e-b951-2e6c0a3f7d14",
      "error": null,
      "created_timestamp": 1792310400200
    }
  ]
}

SMS chat fields#

Field	Type	Description
`chat_id`	string	SMS chat ID.
`chat_type`	string	Always `sms`.
`agent_id`	string or null	Voice agent whose engine writes the replies.
`chat_status`	string	`ongoing` or `ended`.
`messages`	array	Messages, oldest first. See below.

Message fields#

Field	Type	Description
`message_id`	string	`sms_` plus 24 hex characters.
`chat_id`, `call_id`	string or null	The SMS chat, or the call that sent it (`send_sms` tool).
`direction`	string	`inbound` or `outbound`.
`content`	string	Text, up to 1600 characters.
`status`	string	`queued`, `sent`, `delivered`, `failed` or `received`.
`provider_message_id`	string or null	Carrier message ID.
`error`	string or null	Delivery error.
`media_urls`	string[]	MMS attachments, when present.
`created_timestamp`	integer	Epoch ms.

Errors#

Status	When
`400`	Validation failed, no agent and no `initial_message`, `to_number` is not E.164, or the message is empty.
`401`	Missing or invalid API key.
`402`	Credit exhausted, budget reached or invoice overdue.
`403`	The key's IP allowlist or scopes reject the request. This route needs the `calls` scope. Business verification (KYC) is not approved.
`404`	`from_number` is not a number in this workspace, or the agent does not exist.
`429`	Rate limit exceeded. See Rate limits.

See Errors for the body format.