Ada Conversations API

openapi: 3.2.0
info:
  title: Ada Conversations API
  version: 1.0.0
  description: 'Operations tagged conversations across 3 of this provider''s published API definitions: ada-data-export-openapi.yml, ada-data-export-v1-4-openapi.yml, ada-knowledge-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://example.ada.support/api
  description: https://example.ada.support/api
- url: https://example.ada.support
  description: https://example.ada.support/
tags:
- name: conversations
paths:
  /v2/export/conversations:
    get:
      operationId: get-conversations
      summary: Return conversations matching the parameters
      description: Returns a list of `conversation` objects along with a `next_page_uri` if applicable
      tags:
      - conversations
      parameters:
      - name: created_since
        in: query
        description: Return records that were created after this date. If `created_to` is not specified, only records within 7 days of this timestamp are returned. To retrieve data beyond that window, set `created_to` explicitly. Note that `updated_since` and `created_since` are mutually exclusive, so you must only use one in a request. Must be an ISO 8601 UTC timestamp ending with 'Z' (e.g., `2024-07-01T00:00:00Z`); required for valid API requests.
        required: false
        schema:
          type: string
          format: date-time
      - name: updated_since
        in: query
        description: Return records that were updated after this date. Note that `updated_since` and `created_since` are mutually exclusive, so you must only use one in a request. Must be an ISO 8601 UTC timestamp ending with 'Z' (e.g., `2024-07-01T00:00:00Z`); required for valid API requests.
        required: false
        schema:
          type: string
          format: date-time
      - name: page_size
        in: query
        description: Number of records to return in response. The maximum and default is 10000, the minimum is 100.
        required: false
        schema:
          type: integer
          default: 10000
      - name: created_to
        in: query
        description: Return records that were created earlier than this date. If `created_since` is used and this parameter is not specified, this value defaults to 7 days after `created_since`. Must be an ISO 8601 UTC timestamp ending with 'Z' (e.g., `2024-07-01T00:00:00Z`); required for valid API requests.
        required: false
        schema:
          type:
          - string
          - 'null'
          format: date-time
      - name: updated_to
        in: query
        description: Return records that were updated earlier than this date. If `updated_since` is used and this parameter is not specified, this value defaults to 7 days after `updated_since`. Must be an ISO 8601 UTC timestamp ending with 'Z' (e.g., `2024-07-01T00:00:00Z`); required for valid API requests.
        required: false
        schema:
          type:
          - string
          - 'null'
          format: date-time
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Ada successfully processed the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationsResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '403':
          description: Authorization Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    servers:
    - url: https://example.ada.support/api
      description: https://example.ada.support/api
  /data_api/v1.4/conversations:
    get:
      operationId: return-conversations-matching-the-parameters
      summary: Return conversations matching the parameters
      description: Returns a list of `conversation` objects along with a status message and `next_page_uri` if applicable.
      tags:
      - conversations
      parameters:
      - name: created_since
        in: query
        description: Return records that were created after this date.  Note that `updated_since` and `created_since` are mutually exclusive, so you must only use one in a request. Must be an ISO 8601 UTC timestamp ending with 'Z' (e.g., `2024-07-01T00:00:00Z`); required for valid API requests.
        required: false
        schema:
          type: string
          format: date-time
      - name: updated_since
        in: query
        description: Return records that were updated after this date. Note that `updated_since` and `created_since` are mutually exclusive, so you must only use one in a request. Must be an ISO 8601 UTC timestamp ending with 'Z' (e.g., `2024-07-01T00:00:00Z`); required for valid API requests.
        required: false
        schema:
          type: string
          format: date-time
      - name: page_size
        in: query
        description: Number of records to return in response. The maximum and default is 10000, the minimum is 100.
        required: false
        schema:
          type: integer
          default: 10000
      - name: created_to
        in: query
        description: Return records that were created earlier than this date. If `created_since` is used and this parameter is not specified, this value defaults to 7 days after `created_since`.
        required: false
        schema:
          type:
          - string
          - 'null'
          format: date-time
      - name: updated_to
        in: query
        description: Return records that were updated earlier than this date. If `updated_since` is used and this parameter is not specified, this value defaults to 7 days after `updated_since`.
        required: false
        schema:
          type:
          - string
          - 'null'
          format: date-time
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Ada successfully processed the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationsResponse_2'
        '400':
          description: Incorrect query.
          content:
            application/json:
              schema:
                description: Any type
        '408':
          description: Database query timed out.
          content:
            application/json:
              schema:
                description: Any type
        '422':
          description: Invalid arguments or missing data for a required field.
          content:
            application/json:
              schema:
                description: Any type
        '429':
          description: Requests are within 1 s of each other.
          content:
            application/json:
              schema:
                description: Any type
        '500':
          description: Request timed out or there was a database error.
          content:
            application/json:
              schema:
                description: Any type
        '502':
          description: Nginx gateway issue on Ada's servers.
          content:
            application/json:
              schema:
                description: Any type
        '503':
          description: Server temporarily unable to handle the request.
          content:
            application/json:
              schema:
                description: Any type
        '504':
          description: Temporary infrastructure error on Ada's servers.
          content:
            application/json:
              schema:
                description: Any type
    servers:
    - url: https://example.ada.support
      description: https://example.ada.support/
  /v2/conversations/email/:
    post:
      operationId: create-email-conversation
      summary: Start a conversation over Ada's email channel
      description: Start a conversation with an end user over Ada's native Email channel, providing context for their inquiry. **This endpoint is exclusive to the native Email channel and cannot be used for custom channels.** Your AI Agent can start conversations only with the default Ada-provided email address, or with email addresses you’ve configured through Bring Your Own Domain (BYOD) settings.
      tags:
      - conversations
      parameters:
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Conversation Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailConversationCreateResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailConversationCreateRequest'
    servers:
    - url: https://example.ada.support/api
      description: Production
  /v2/conversations/:
    post:
      operationId: create-conversation
      summary: Create a new conversation
      description: Create a new conversation. If `end_user_id` is not provided, the system creates a new end user automatically. The maximum request size is 10MB, and metadata must not exceed 4KB.
      tags:
      - conversations
      parameters:
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Conversation created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation_3'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationCreateRequest'
    servers:
    - url: https://example.ada.support/api
      description: Production
  /v2/conversations/{conversation_id}/:
    get:
      operationId: get-conversation-by-id
      summary: Get a conversation
      description: Get a conversation by its ID
      tags:
      - conversations
      parameters:
      - name: conversation_id
        in: path
        description: The ID of the conversation to retrieve
        required: true
        schema:
          type: string
          format: id
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Conversation retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation_3'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    patch:
      operationId: patch-conversation-by-id
      summary: Update a conversation
      description: Update a conversation's metadata by its ID
      tags:
      - conversations
      parameters:
      - name: conversation_id
        in: path
        description: The ID of the conversation to update
        required: true
        schema:
          type: string
          format: id
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Conversation updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation_3'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationPatchRequest'
    servers:
    - url: https://example.ada.support/api
      description: Production
  /v2/conversations/{conversation_id}/messages/:
    get:
      operationId: fetch-conversation-messages-by-id
      summary: Get conversation messages
      description: Get messages (paginated) for a conversation by its ID
      tags:
      - conversations
      parameters:
      - name: conversation_id
        in: path
        description: The ID of the conversation
        required: true
        schema:
          type: string
          format: id
      - name: cursor
        in: query
        description: Cursor for pagination. Use the value from `meta.next_page_url` in the previous response.
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Maximum number of messages to return (default 100, max 100)
        required: false
        schema:
          type: integer
          default: 100
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: List of messages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageList'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    post:
      operationId: create-message
      summary: Create a new message
      description: Create a new message in a conversation. The maximum request size is 10MB.
      tags:
      - conversations
      parameters:
      - name: conversation_id
        in: path
        description: The ID of the conversation
        required: true
        schema:
          type: string
          format: id
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Message created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageCreateRequest'
    servers:
    - url: https://example.ada.support/api
      description: Production
  /v2/conversations/{conversation_id}/end/:
    post:
      operationId: end-conversation
      summary: End a conversation
      description: Ends the conversation specified by the `conversation_id`
      tags:
      - conversations
      parameters:
      - name: conversation_id
        in: path
        description: The ID of the conversation to end
        required: true
        schema:
          type: string
          format: id
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Conversation ended successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversations_endConversation_Response_200'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    servers:
    - url: https://example.ada.support/api
      description: Production
  /v2/conversations/{conversation_id}/end-handoff/:
    post:
      operationId: end-handoff
      summary: End Handoff
      description: Ends the handoff for the conversation specified by the `conversation_id`. This endpoint returns control to the AI Agent and does not end the conversation. It also triggers CSAT for human agent (where applicable), leftover blocks processing, and agent presence dismissal messages.
      tags:
      - conversations
      parameters:
      - name: conversation_id
        in: path
        description: The ID of the conversation to end handoff for
        required: true
        schema:
          type: string
          format: id
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Handoff ended successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversations_endHandoff_Response_200'
        '404':
          description: Conversation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '422':
          description: Conversation is not in an active handoff state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    servers:
    - url: https://example.ada.support/api
      description: Production
  /v2/conversations/{conversation_id}/attachments/:
    post:
      operationId: upload-attachment
      summary: Upload a file attachment
      description: 'Upload a temporary file attachment to a conversation. The file is stored on Ada-managed

        storage and a presigned URL is returned that is valid for up to 7 days. Use that URL to

        create a file message by calling the `/v2/conversations/{conversation_id}/messages/`

        endpoint with `content.type` set to `file`. The maximum file size is 50MB.


        This endpoint provides temporary media storage for use within a conversation. It is

        **not** equivalent to the native attachment experience in Ada''s widget handoff

        integrations (for example, the paperclip in Zendesk Messaging). With native widget

        attachments, files are uploaded directly into your agent platform (such as Sunshine

        Conversations / Zendesk) and hosted there. That native path is only available to Ada''s

        web channel and is not accessible through the Conversations API.


        If you are building a headless Conversations API integration and want to send an

        attachment from an end user to a human agent mid-conversation so that it appears natively

        in your agent platform, upload the file using your agent platform''s own attachment

        endpoints (for example, the Sunshine Conversations Attachments API for Zendesk) and

        consult that platform''s documentation.


        **Note:** Attachments can only be uploaded when the conversation is in a handoff state.


        **Allowed file types:** TXT, LOG, CSV, EML, PNG, SVG, JPEG, JPG, GIF, HEIF, HEIC, AVIF, WAV, M4A, MP3, MP4, M4V, MOV, MPEG, MPG, ZIP, PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, Keynote, Pages, Numbers

        '
      tags:
      - conversations
      parameters:
      - name: conversation_id
        in: path
        description: The ID of the conversation
        required: true
        schema:
          type: string
          format: id
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Attachment uploaded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttachmentUploadResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: The file to upload (max 50MB)
              required:
              - file
    servers:
    - url: https://example.ada.support/api
      description: Production
components:
  schemas:
    ConversationsResponseMeta:
      type: object
      properties:
        next_page_uri:
          type:
          - string
          - 'null'
          description: Link to the next page of results matching the query
      title: ConversationsResponseMeta
    ConversationCsat:
      type: object
      properties: {}
      description: Object of customer satisfaction survey data for this conversation
      title: ConversationCsat
    ConversationUsedCoachingItems:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
        entity_name:
          type:
          - string
          - 'null'
        coaching_type:
          type:
          - string
          - 'null'
        coaching_instructions:
          type:
          - string
          - 'null'
        coaching_intent:
          type:
          - string
          - 'null'
      title: ConversationUsedCoachingItems
    ConversationClassificationsItems:
      type: object
      properties:
        topic_id:
          type: string
          description: Ada ID of the classified Topic
        topic_name:
          type: string
          description: Name of the classified Topic
        intents:
          type: array
          items:
            $ref: '#/components/schemas/ConversationClassificationsItemsIntentsItems'
          description: Intents classified within this Topic
      title: ConversationClassificationsItems
    ConversationMetavariables:
      type: object
      properties: {}
      description: Object of metavariables and their values active during this conversations
      title: ConversationMetavariables
    ConversationClassificationsItemsIntentsItems:
      type: object
      properties:
        intent_id:
          type: string
          description: Ada ID of the classified Intent
        intent_name:
          type: string
          description: Name of the classified Intent
        status:
          type: string
          description: Status of the Intent (for example, active)
      title: ConversationClassificationsItemsIntentsItems
    ErrorsErrorsItems:
      type: object
      properties:
        type:
          type: string
          description: The error type
        message:
          type: string
          description: The error message
        details:
          type:
          - string
          - 'null'
          description: Extra information about the error
      required:
      - type
      - message
      title: ErrorsErrorsItems
    Errors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorsErrorsItems'
          description: A list of errors
      required:
      - errors
      title: Errors
    ConversationsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Conversation'
          description: Records returned from the query
        meta:
          $ref: '#/components/schemas/ConversationsResponseMeta'
      title: ConversationsResponse
    ConversationUsedArticlesItems:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        url:
          type:
          - string
          - 'null'
        source:
          type:
          - string
          - 'null'
      title: ConversationUsedArticlesItems
    ConversationUsedPlaybooksItems:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        playbook_execution_id:
          type:
          - string
          - 'null'
        outcome_status:
          type:
          - string
          - 'null'
      title: ConversationUsedPlaybooksItems
    Conversation:
      type: object
      properties:
        _id:
          type: string
          description: Unique ID for the conversation record
        agent_id:
          type: array
          items:
            type: string
          description: The list of unique IDs for agents involved in the conversation
        agent_handle_time:
          type: number
          format: double
          description: Time taken for a human agent to handle a conversation in seconds
        agent_name:
          type: array
          items:
            type: string
          description: A list of names of the agents involved the conversation, corresponding to the agent IDs
        automated_resolution_classification:
          type: string
          description: Classification of either Resolved or Not Resolved for the conversation
        automated_resolution_classification_reason:
          type: string
          description: Explanation of the reason for the assigned automated_resolution_classification
        bot_handle_time:
          type: number
          format: double
          description: Time taken for the AI agent to handle a conversation in seconds
        browser:
          type: string
          description: The browser used by the chatter
        browser_version:
          type: string
          description: The version of the browser used by the chatter
        chatter_id:
          type: string
          description: Ada ID of the chatter having this conversation
        classifications:
      

# --- truncated at 32 KB (55 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ada/refs/heads/main/openapi/ada-conversations-api-openapi.yml