The Create Chat Completion API from Retell AI — 1 operation(s) for create chat completion.
openapi: 3.0.3
info:
title: Retell SDK Add Community Voice Create Chat Completion API
version: 3.0.0
contact:
name: Retell Support
url: https://www.retellai.com/
email: support@retellai.com
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api.retellai.com
description: The production server.
security:
- api_key: []
tags:
- name: Create Chat Completion
paths:
/create-chat-completion:
post:
description: Create a chat completion message
operationId: createChatCompletion
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- chat_id
- content
properties:
chat_id:
type: string
example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
description: Unique id of the chat to create completion.
content:
type: string
example: hi how are you doing?
description: user message to generate agent chat completion.
responses:
'201':
description: Successfully created chat completion.
content:
application/json:
schema:
type: object
required:
- messages
properties:
messages:
type: array
items:
$ref: '#/components/schemas/MessageOrToolCall'
description: New messages generated by the agent during this completion, including any tool call invocations and their results. Does not include the original input messages.
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'422':
$ref: '#/components/responses/UnprocessableContent'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
tags:
- Create Chat Completion
components:
schemas:
MessageBase:
type: object
required:
- role
- content
properties:
message_id:
type: string
example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6
description: Unique id of the message
role:
type: string
enum:
- agent
- user
description: Documents whether this message is sent by agent or user.
example: agent
content:
type: string
description: Content of the message
example: hi how are you doing?
created_timestamp:
type: integer
description: Create timestamp of the message
example: 1703302428855
MessageOrToolCall:
oneOf:
- $ref: '#/components/schemas/Message'
- $ref: '#/components/schemas/ToolCallInvocationMessage'
- $ref: '#/components/schemas/ToolCallResultMessage'
- $ref: '#/components/schemas/NodeTransitionMessage'
- $ref: '#/components/schemas/StateTransitionMessage'
StateTransitionMessageBase:
type: object
required:
- role
properties:
message_id:
type: string
example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6
description: Unique id of the message
role:
type: string
enum:
- state_transition
description: This is a state transition.
former_state_name:
type: string
description: Former state name
new_state_name:
type: string
description: New state name
created_timestamp:
type: integer
description: Create timestamp of the message
example: 1703302428855
ToolCallInvocationMessageBase:
type: object
required:
- role
- tool_call_id
- name
- arguments
properties:
message_id:
type: string
example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6
description: Unique id of the message
role:
type: string
enum:
- tool_call_invocation
description: This is a tool call invocation.
tool_call_id:
type: string
description: Tool call id, globally unique.
name:
type: string
description: Name of the function in this tool call.
arguments:
type: string
description: Arguments for this tool call, it's a stringified JSON object.
thought_signature:
type: string
description: Optional thought signature from Google Gemini thinking models. This is used internally to maintain reasoning chain in multi-turn function calling.
created_timestamp:
type: integer
description: Create timestamp of the message
example: 1703302428855
NodeTransitionMessage:
allOf:
- $ref: '#/components/schemas/NodeTransitionMessageBase'
- required:
- message_id
- created_timestamp
NodeTransitionMessageBase:
type: object
required:
- role
properties:
message_id:
type: string
example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6
description: Unique id of the message
role:
type: string
enum:
- node_transition
description: This is a node transition.
former_node_id:
type: string
description: Former node id
former_node_name:
type: string
description: Former node name
new_node_id:
type: string
description: New node id
new_node_name:
type: string
description: New node name
transition_type:
type: string
enum:
- global
- global_go_back
- interrupt_go_back
- normal
description: How this node was reached. "global" means a global node transition, "global_go_back" means returning from a global node, "interrupt_go_back" means going back due to user interruption, and "normal" means a regular edge transition.
created_timestamp:
type: integer
description: Create timestamp of the message
example: 1703302428855
ToolCallInvocationMessage:
allOf:
- $ref: '#/components/schemas/ToolCallInvocationMessageBase'
- required:
- message_id
- created_timestamp
Message:
allOf:
- $ref: '#/components/schemas/MessageBase'
- required:
- message_id
- created_timestamp
ToolCallResultMessage:
allOf:
- $ref: '#/components/schemas/ToolCallResultMessageBase'
- required:
- message_id
- created_timestamp
StateTransitionMessage:
allOf:
- $ref: '#/components/schemas/StateTransitionMessageBase'
- required:
- message_id
- created_timestamp
ToolCallResultMessageBase:
type: object
required:
- role
- tool_call_id
- content
properties:
message_id:
type: string
example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6
description: Unique id of the message
role:
type: string
enum:
- tool_call_result
description: This is the result of a tool call.
tool_call_id:
type: string
description: Tool call id, globally unique.
content:
type: string
description: Result of the tool call, can be a string, a stringified json, etc.
successful:
type: boolean
description: Whether the tool call was successful.
created_timestamp:
type: integer
description: Create timestamp of the message
example: 1703302428855
responses:
TooManyRequests:
description: Too Many Requests
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- error
message:
type: string
example: Account rate limited, please throttle your requests.
Unauthorized:
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- error
message:
type: string
example: API key is missing or invalid.
PaymentRequired:
description: Payment Required
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- error
message:
type: string
example: Trial has ended, please add payment method.
BadRequest:
description: Bad Request
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- error
message:
type: string
example: Invalid request format, please check API reference.
UnprocessableContent:
description: Unprocessable Content
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- error
message:
type: string
example: Cannot find requested asset under given api key.
InternalServerError:
description: Internal Server Error
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- error
message:
type: string
example: An unexpected server error occurred.
securitySchemes:
api_key:
type: http
scheme: bearer
bearerFormat: string
description: Authentication header containing API key (find it in dashboard). The format is "Bearer YOUR_API_KEY"