POST /create-chat

Changed on

Create a chat session

Request

  • Base URL
    https://api.retellai.com
  • Auth
    HTTP bearer

Request body

agent_idstring required

The chat agent to use for the chat.

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

{
  "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "agent_version": "latest_published",
  "retell_llm_dynamic_variables": {
    "customer_name": "John Doe"
  }
}

Response

Successfully created a chat.

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

agent_tagstring nullable

Tag pointing at the agent version used for this chat

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

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.

Example response

{
  "chat_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
  "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "version": 1,
  "agent_tag": "prod",
  "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
    }
  ],
  "pre_session_message_with_tool_calls": [
    {
      "message_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
      "role": "agent",
      "content": "hi how are you doing?",
      "created_timestamp": 1703302428855
    }
  ],
  "scrubbed_pre_session_message_with_tool_calls": [
    {
      "message_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
      "role": "agent",
      "content": "hi how are you doing?",
      "created_timestamp": 1703302428855
    }
  ],
  "post_session_message_with_tool_calls": [
    {
      "message_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
      "role": "agent",
      "content": "hi how are you doing?",
      "created_timestamp": 1703302428855
    }
  ],
  "scrubbed_post_session_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

    • breaking

      added to the / response property oneOf list for the response status

    • info

      added the optional property to the response with the status

    • info

      added the optional property ////////// to the response with the status

    • info

      added the optional property ////////// to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • warning

      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})$