POST
/
create-sms-chat
JavaScript
import Retell from 'retell-sdk';

const client = new Retell({
  apiKey: 'YOUR_RETELL_API_KEY',
});

const chatResponse = await client.chat.createSMSChat({
  from_number: '+12137771234',
  to_number: '+14155551234',
});

console.log(chatResponse.agent_id);
{
  "chat_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
  "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "retell_llm_dynamic_variables": {
    "customer_name": "John Doe"
  },
  "collected_dynamic_variables": {
    "last_node_name": "Test node"
  },
  "chat_status": "ongoing",
  "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
    }
  ],
  "metadata": {},
  "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,
    "custom_analysis_data": {}
  }
}

Authorizations

​
Authorization
string
header
required

Authentication header containing API key (find it in dashboard). The format is "Bearer YOUR_API_KEY"

Body

application/json
​
from_number
string
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.

Example:

"+12137771234"

​
to_number
string
required

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

Example:

"+14155551234"

​
override_agent_id
string

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.

Example:

"oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD"

​
override_agent_version
integer

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

Example:

1

​
metadata
object

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_variables
object

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:
{ "customer_name": "John Doe" }

Response

SMS chat created and initial message sent successfully

​
chat_id
string
required

Unique id of the chat.

Example:

"Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6"

​
agent_id
string
required

Corresponding chat agent id of this chat.

Example:

"oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD"

​
chat_status
enum<string>
required

Status of chat.

  • ongoing: Chat session is ongoing, chat agent can receive new message and generate response.

  • ended: Chat session has ended can not generate new response.

  • error: Chat encountered error.

Available options:
ongoing,
ended,
error
Example:

"ongoing"

​
retell_llm_dynamic_variables
object

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:
{ "customer_name": "John Doe" }
​
collected_dynamic_variables
object

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

Example:
{ "last_node_name": "Test node" }
​
start_timestamp
integer

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

Example:

1703302407333

​
end_timestamp
integer

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

Example:

1703302428855

​
transcript
string

Transcription of the chat.

Example:

"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
object[]

Transcript of the chat weaved with tool call invocation and results.

​
metadata
object

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.

​
chat_cost
object
​
chat_analysis
object

Post chat analysis that includes information such as sentiment, status, summary, and custom defined data to extract. Available after chat ends. Subscribe to chat_analyzed webhook event type to receive it once ready.