Retell AI List Chat API

openapi: 3.0.3
info:
  title: Retell SDK Add Community Voice List Chat 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: List Chat
paths:
  /list-chat:
    get:
      description: List all chats
      operationId: listChat
      deprecated: true
      parameters:
      - in: query
        name: sort_order
        schema:
          type: string
          enum:
          - ascending
          - descending
          default: descending
        description: The chats will be sorted by `start_timestamp`, whether to return the chats in ascending or descending order.
      - in: query
        name: limit
        schema:
          type: integer
          default: 50
          maximum: 1000
        description: Limit the number of chats returned. Default 50, Max 1000. To retrieve more than 1000, use pagination_key to continue fetching the next page.
      - in: query
        name: pagination_key
        schema:
          type: string
        description: The pagination key to continue fetching the next page of chats. Pagination key is represented by a chat id here, and it's exclusive (not included in the fetched chats). The last chat id from the list chats is usually used as pagination key here. If not set, will start from the beginning.
      responses:
        '200':
          description: Successfully retrieved all chats.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ChatResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      tags:
      - List Chat
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'
    NodeTransitionMessage:
      allOf:
      - $ref: '#/components/schemas/NodeTransitionMessageBase'
      - required:
        - message_id
        - created_timestamp
    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
    ChatResponse:
      type: object
      required:
      - chat_id
      - agent_id
      - chat_status
      properties:
        chat_id:
          type: string
          example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6
          description: Unique id of the chat.
        agent_id:
          type: string
          example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
          description: Corresponding chat agent id of this chat.
        version:
          type: integer
          example: 1
          description: The version of the agent
          nullable: true
        retell_llm_dynamic_variables:
          type: object
          additionalProperties: {}
          example:
            customer_name: John Doe
          description: 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_variables:
          type: object
          additionalProperties: {}
          example:
            last_node_name: Test node
          description: Dynamic variables collected from the chat. Only available after the chat ends.
        chat_status:
          type: string
          enum:
          - ongoing
          - ended
          - error
          example: ongoing
          description: '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:
          type: string
          enum:
          - api_chat
          - sms_chat
          example: api_chat
          description: Type of the chat
        custom_attributes:
          type: object
          additionalProperties:
            oneOf:
            - type: string
            - type: number
            - type: boolean
          description: Custom attributes for the chat
        start_timestamp:
          type: integer
          example: 1703302407333
          description: Begin timestamp (milliseconds since epoch) of the chat. Available after chat starts.
        end_timestamp:
          type: integer
          example: 1703302428855
          description: End timestamp (milliseconds since epoch) of the chat. Available after chat ends.
          nullable: true
        transcript:
          type: string
          example: 'Agent: hi how are you doing?

            User: Doing pretty well. How are you?

            Agent: That''s great to hear! I''m doing well too, thanks! What''s up?

            User: I don''t have anything in particular.

            Agent: Got it, just checking in!

            User: Alright. See you.

            Agent: have a nice day

            '
          description: Transcription of the chat.
        message_with_tool_calls:
          type: array
          items:
            $ref: '#/components/schemas/MessageOrToolCall'
          description: Transcript of the chat weaved with tool call invocation and results.
        metadata:
          type: object
          description: 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:
          type: object
          properties:
            product_costs:
              type: array
              description: List of products with their unit prices and costs in cents
              items:
                $ref: '#/components/schemas/ProductCost'
            combined_cost:
              type: number
              description: Combined cost of all individual costs in cents
              example: 70
        chat_analysis:
          description: 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.
          $ref: '#/components/schemas/ChatAnalysis'
    ProductCost:
      type: object
      required:
      - product
      - cost
      properties:
        product:
          type: string
          description: Product name that has a cost associated with it.
          example: elevenlabs_tts
        unit_price:
          type: number
          description: Unit price of the product in cents per second.
          example: 1
        cost:
          type: number
          description: Cost for the product in cents for the duration of the call.
          example: 60
        is_transfer_leg_cost:
          type: boolean
          description: True if this cost item is for a transfer segment.
    ToolCallInvocationMessage:
      allOf:
      - $ref: '#/components/schemas/ToolCallInvocationMessageBase'
      - required:
        - message_id
        - created_timestamp
    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
    Message:
      allOf:
      - $ref: '#/components/schemas/MessageBase'
      - required:
        - message_id
        - created_timestamp
    StateTransitionMessage:
      allOf:
      - $ref: '#/components/schemas/StateTransitionMessageBase'
      - required:
        - message_id
        - created_timestamp
    ToolCallResultMessage:
      allOf:
      - $ref: '#/components/schemas/ToolCallResultMessageBase'
      - required:
        - message_id
        - created_timestamp
    ChatAnalysis:
      type: object
      properties:
        chat_summary:
          type: string
          example: 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.
          description: A high level summary of the chat.
        user_sentiment:
          type: string
          enum:
          - Negative
          - Positive
          - Neutral
          - Unknown
          example: Positive
          description: Sentiment of the user in the chat.
        chat_successful:
          type: boolean
          example: true
          description: Whether the agent seems to have a successful chat with the user, where the agent finishes the task, and the call was complete without being cutoff.
        custom_analysis_data:
          type: object
          description: Custom analysis data that was extracted based on the schema defined in chat agent post chat analysis data. Can be empty if nothing is specified.
    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
    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:
    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.
    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.
  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"