POST /create-sms-chat – Retell AI Retell SDK

Start an outbound SMS chat conversation with a phone number using the specified agent. The agent must be configured for chat mode. The initial SMS message will be automatically generated and sent based on the agent's configuration.

post/create-sms-chat

Request body

from_numberstring required

The phone number to send SMS from in E.164 format. Must be a number purchased from Retell or imported to Retell with SMS capability.

to_numberstring required

The phone number to send SMS to in E.164 format

override_agent_idstring

For this particular chat, override the agent used with this agent id. This does not bind the agent to this number, this is for one time override.

metadataobject

An arbitrary object for storage purpose only. You can put anything here like your internal customer id associated with the chat. Not used for processing. You can later get this field from the chat object.

retell_llm_dynamic_variablesobject

Add optional dynamic variables in key value pairs of string that injects into your Response Engine prompt and tool description. Only applicable for Response Engine.

Example request

{
  "from_number": "+12137771234",
  "to_number": "+14155551234",
  "override_agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "override_agent_version": 1,
  "retell_llm_dynamic_variables": {
    "customer_name": "John Doe"
  }
}

Response

SMS chat created and initial message sent successfully

chat_idstring required

Unique id of the chat.

agent_idstring required

Corresponding chat agent id of this chat.

versioninteger nullable

The version of the agent

retell_llm_dynamic_variablesobject

Add optional dynamic variables in key value pairs of string that injects into your Response Engine prompt and tool description. Only applicable for Response Engine.

collected_dynamic_variablesobject

Dynamic variables collected from the chat. Only available after the chat ends.

chat_status'ongoing' | 'ended' | 'error' required

Status of chat.

ongoing: Chat session is ongoing, chat agent can receive new message and generate response.
ended: Chat session has ended, and no longer can generate new response.
error: Chat encountered error.

chat_type'api_chat' | 'sms_chat'

Type of the chat

custom_attributesobject

Custom attributes for the chat

start_timestampinteger

Begin timestamp (milliseconds since epoch) of the chat. Available after chat starts.

end_timestampinteger nullable

End timestamp (milliseconds since epoch) of the chat. Available after chat ends.

transcriptstring

Transcription of the chat.

metadataobject

Example response

{
  "chat_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
  "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "version": 1,
  "retell_llm_dynamic_variables": {
    "customer_name": "John Doe"
  },
  "collected_dynamic_variables": {
    "last_node_name": "Test node"
  },
  "chat_status": "ongoing",
  "chat_type": "api_chat",
  "start_timestamp": 1703302407333,
  "end_timestamp": 1703302428855,
  "transcript": "Agent: hi how are you doing?\nUser: Doing pretty well. How are you?\nAgent: That's great to hear! I'm doing well too, thanks! What's up?\nUser: I don't have anything in particular.\nAgent: Got it, just checking in!\nUser: Alright. See you.\nAgent: have a nice day\n",
  "message_with_tool_calls": [
    {
      "message_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
      "role": "agent",
      "content": "hi how are you doing?",
      "created_timestamp": 1703302428855
    }
  ],
  "chat_cost": {
    "product_costs": [
      {
        "product": "elevenlabs_tts",
        "unit_price": 1,
        "cost": 60
      }
    ],
    "combined_cost": 70
  },
  "chat_analysis": {
    "chat_summary": "The agent messages user to ask question about his purchase inquiry. The agent asked several questions regarding his preference and asked if user would like to book an appointment. The user happily agreed and scheduled an appointment next Monday 10am.",
    "user_sentiment": "Positive",
    "chat_successful": true
  }
}

Changes

Changed in 8 of the 28 revisions of this API.31118

May 28, 202640402ca870b91See the full diff
- ●
  changed the pattern of the request property / from ^(latest|(?!(?:v\d+)$)[a-z][a-z0-9_-]{0,19})$ to ^(latest|latest_published|(?!(?:latest|latest_published|v\d+)$)[a-z][a-z0-9_-]{0,19})$
  request-property-pattern-changed
May 12, 20266dff2a12f8663See the full diff
- ▲
  the / request property type changed from no type to string
  request-property-type-changed
- ▲
  the / response's property type changed from no type to string for status
  response-property-type-changed
- ▲
  the / response's property type changed from no type to string for status
  response-property-type-changed
May 8, 20267dd16ddf69d81See the full diff
- ●
  changed the pattern of the request property / from ^[a-z0-9_-]+$ to ^(latest|(?!(?:v\d+)$)[a-z][a-z0-9_-]{0,19})$
  request-property-pattern-changed
May 7, 2026f1a0d7c1e36c1See the full diff
- ○
  request property list-of-types was widened by adding types string to media type application/json
  request-property-list-of-types-widened
Apr 20, 20268ee53928bf312595See the full diff
- ▲
  the ///// response's property type changed from object to no type for status
  response-property-type-changed
- ▲
  the ///// response's property type changed from object to no type for status
  response-property-type-changed
- ▲
  the ///// response's property type changed from object to no type for status
  response-property-type-changed
- ▲
  the ///// response's property type changed from object to no type for status
  response-property-type-changed
- ▲
  the ///// response's property type changed from object to no type for status
  response-property-type-changed
- ▲
  removed the required property ////// from the response with the status
  response-required-property-removed
- ▲
  removed the required property ////// from the response with the status
  response-required-property-removed
- ▲
  removed the required property ////// from the response with the status
  response-required-property-removed
- ▲
  removed the required property ////// from the response with the status
  response-required-property-removed
- ▲
  removed the required property ////// from the response with the status
  response-required-property-removed
- ▲
  removed the required property ////// from the response with the status
  response-required-property-removed
- ▲
  removed the required property ////// from the response with the status
  response-required-property-removed
- ▲
  removed the required property ////// from the response with the status
  response-required-property-removed
- ▲
  removed the required property ////// from the response with the status
  response-required-property-removed
- ▲
  removed the required property ////// from the response with the status
  response-required-property-removed
- ▲
  removed the required property ////// from the response with the status
  response-required-property-removed
- ▲
  removed the required property ////// from the response with the status
  response-required-property-removed
- ▲
  removed the required property ////// from the response with the status
  response-required-property-removed
- ▲
  removed the required property ////// from the response with the status
  response-required-property-removed
- ▲
  removed the required property ////// from the response with the status
  response-required-property-removed
- ▲
  removed the required property ////// from the response with the status
  response-required-property-removed
- ▲
  removed the required property ////// from the response with the status
  response-required-property-removed
- ▲
  removed the required property ////// from the response with the status
  response-required-property-removed
- ▲
  removed the required property ////// from the response with the status
  response-required-property-removed
- ▲
  removed the required property ////// from the response with the status
  response-required-property-removed
- ●
  removed the optional property ////// from the response with the status
  response-optional-property-removed
- ●
  removed the optional property ////// from the response with the status
  response-optional-property-removed
- ●
  removed the optional property ////// from the response with the status
  response-optional-property-removed
- ●
  removed the optional property ////// from the response with the status
  response-optional-property-removed
- ●
  removed the optional property ////// from the response with the status
  response-optional-property-removed
- ●
  removed the optional property ////// from the response with the status
  response-optional-property-removed
- ●
  removed the optional property ////// from the response with the status
  response-optional-property-removed
- ●
  removed the optional property ////// from the response with the status
  response-optional-property-removed
- ●
  removed the optional property ////// from the response with the status
  response-optional-property-removed
- ○
  added subschema #2 to the ///// response property allOf list for the response status
  response-property-all-of-added
- ○
  added subschema #2 to the ///// response property allOf list for the response status
  response-property-all-of-added
- ○
  added subschema #2 to the ///// response property allOf list for the response status
  response-property-all-of-added
- ○
  added subschema #2 to the ///// response property allOf list for the response status
  response-property-all-of-added
- ○
  added subschema #2 to the ///// response property allOf list for the response status
  response-property-all-of-added
Mar 9, 20268fbf8c54a1423See the full diff
- ▲
  the request property's minLength was increased from 0 to 1
  request-property-min-length-increased
- ▲
  the request property's minLength was increased from 0 to 1
  request-property-min-length-increased
- ▲
  the request property's minLength was increased from 0 to 1
  request-property-min-length-increased
Feb 23, 2026bcff6899fa2a1See the full diff
- ○
  added the optional property ////// to the response with the status
  response-optional-property-added
Feb 10, 20260bf5cea5dfcc1See the full diff
- ○
  added the optional property /// to the response with the status
  response-optional-property-added

Full history