Amigo Conversation API

openapi: 3.1.0
info:
  title: Amigo Account Conversation API
  version: 0.1.0
servers:
- url: https://api.amigo.ai
- url: https://internal-api.amigo.ai
- url: https://api-eu-central-1.amigo.ai
- url: https://api-ap-southeast-2.amigo.ai
- url: https://api-ca-central-1.amigo.ai
security:
- Bearer-Authorization: []
  Bearer-Authorization-Organization: []
  Basic: []
tags:
- name: Conversation
paths:
  /v1/{organization}/conversation/:
    post:
      tags:
      - Conversation
      summary: Create a conversation
      description: 'Create a new conversation and start it. The user must not have any unfinished conversations that belong to the same service.


        #### Permissions

        This endpoint requires the following permissions:

        * `Conversation:CreateConversation` for the new conversation.


        This endpoint may be impacted by the following permissions:

        * `CurrentAgentActionEvent`s are only emitted if the authenticated user has the `Conversation:GetInteractionInsights` permission.'
      operationId: create-conversation
      parameters:
      - name: organization
        in: path
        required: true
        schema:
          type: string
          title: Organization
      - name: response_format
        in: query
        required: true
        schema:
          enum:
          - text
          - voice
          type: string
          description: The format of the response that will be sent to the user.
          title: Response Format
        description: The format of the response that will be sent to the user.
      - name: current_agent_action_type
        in: query
        required: false
        schema:
          type: string
          description: A regex for filtering the type of the current agent action to return. By default, all are returned. If you don't want to receive any events, set this to a regex that matches nothing, for instance `^$`.
          default: ^.*$
          title: Current Agent Action Type
        description: A regex for filtering the type of the current agent action to return. By default, all are returned. If you don't want to receive any events, set this to a regex that matches nothing, for instance `^$`.
      - name: x-mongo-cluster-name
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.
          title: X-Mongo-Cluster-Name
        description: The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.
      - name: Sec-WebSocket-Protocol
        in: header
        required: false
        schema:
          type: array
          items:
            type: string
          default: []
          title: Sec-Websocket-Protocol
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/src__app__endpoints__conversation__create_conversation__Request'
      responses:
        '201':
          description: '

            Succeeded. The response will be a stream of events in JSON format separated by newlines. The server will transmit an event as soon as one is available,

            so the client should respond to the events as soon as one arrives, and keep listening until the server closes the connection.

            '
          content:
            application/x-ndjson:
              schema:
                type: object
                $ref: '#/components/schemas/src__app__endpoints__conversation__create_conversation__Response'
        '422':
          description: Invalid request path parameter or request body failed validation.
        '404':
          description: Specified organization, service, or version set is not found.
        '400':
          description: '

            This may occur for the following reasons:

            * Attempting to start a conversation when other unfinished conversations exist.

            * The preferred language does not support voice response.

            * The `response_audio_format` field is not set when voice output is requested.

            * The agent does not have voice config specified.'
        '409':
          description: A related operation is in progress.
        '401':
          description: Invalid authorization credentials.
        '403':
          description: Missing required permissions.
        '503':
          description: The service is going through temporary maintenance.
        '429':
          description: The user has exceeded the rate limit of 5 requests per minute for this endpoint.
    get:
      tags:
      - Conversation
      summary: Get conversations
      description: 'Retrieve conversations in an organization based on supplied filters.


        #### Permissions

        This endpoint may be impacted by the following permissions:

        * The `final_message` field in the response is only non-empty if the authenticated user has the `Conversation.GetMessage` permission on the final message.

        * The `version_set_info` field in the response is only non-empty if the authenticated user has the `Service.GetVersionSet` permission on the version set.

        * Only conversations for which the user has the `Conversation.GetConversation` permission are returned.'
      operationId: get-conversations
      parameters:
      - name: organization
        in: path
        required: true
        schema:
          type: string
          title: Organization
      - name: user_id
        in: query
        required: false
        schema:
          type: array
          uniqueItems: true
          items:
            type: string
          description: The identifier of the user whose conversations to retrieve.
          default: []
          title: User Id
        description: The identifier of the user whose conversations to retrieve.
      - name: service_id
        in: query
        required: false
        schema:
          type: array
          uniqueItems: true
          items:
            type: string
            pattern: ^[a-f0-9]{24}$
          description: The identifier of the service whose conversation to retrieve.
          default: []
          title: Service Id
        description: The identifier of the service whose conversation to retrieve.
      - name: is_finished
        in: query
        required: false
        schema:
          anyOf:
          - type: boolean
          - type: 'null'
          description: Whether the conversation is finished.
          title: Is Finished
        description: Whether the conversation is finished.
      - name: id
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
            pattern: ^[a-f0-9]{24}$
          description: The ID of the conversation to retrieve.
          default: []
          title: Id
        description: The ID of the conversation to retrieve.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 150
          exclusiveMinimum: 0
          description: The maximum number of conversations to retrieve.
          default: 150
          title: Limit
        description: The maximum number of conversations to retrieve.
      - name: continuation_token
        in: query
        required: false
        schema:
          type: integer
          description: The continuation token returned from the previous response to retrieve the next set of conversations.
          default: 0
          title: Continuation Token
        description: The continuation token returned from the previous response to retrieve the next set of conversations.
      - name: sort_by
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
          description: The field to sort the conversations by. Supported fields are `created_at`. Specify a `+` before the field name to indicate ascending sorting and `-` for descending sorting. Multiple fields can be specified to break ties.
          default: []
          title: Sort By
        description: The field to sort the conversations by. Supported fields are `created_at`. Specify a `+` before the field name to indicate ascending sorting and `-` for descending sorting. Multiple fields can be specified to break ties.
      - name: tag
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
          description: The tags of the dynamic behavior sets. Must be specified using the syntax `key:value`, which means to match all sets with the given `key` and `value` pair among its tags. If `value` is `*`, it means the `value` does not matter. If `value` is empty, it matches against when the value is `None`.
          default: []
          title: Tag
        description: The tags of the dynamic behavior sets. Must be specified using the syntax `key:value`, which means to match all sets with the given `key` and `value` pair among its tags. If `value` is `*`, it means the `value` does not matter. If `value` is empty, it matches against when the value is `None`.
      - name: x-mongo-cluster-name
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.
          title: X-Mongo-Cluster-Name
        description: The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.
      - name: Sec-WebSocket-Protocol
        in: header
        required: false
        schema:
          type: array
          items:
            type: string
          default: []
          title: Sec-Websocket-Protocol
      responses:
        '200':
          description: Succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/src__app__endpoints__conversation__get_conversations__Response'
        '422':
          description: Invalid request path parameter or query parameter failed validation.
        '401':
          description: Invalid authorization credentials.
        '403':
          description: Missing required permissions.
        '503':
          description: The service is going through temporary maintenance.
        '429':
          description: The user has exceeded the rate limit of 15 requests per minute for this endpoint.
  /v1/{organization}/conversation/{conversation_id}/messages/:
    get:
      tags:
      - Conversation
      summary: Get conversation messages
      description: 'Retrieve messages in a conversation, sorted in the specified order, up to the specified limit.


        #### Permissions

        This endpoint is impacted by the following permissions:

        * Only messages that the authenticated user has `Conversation.GetMessage` permission on will be returned.'
      operationId: get-conversation-messages
      parameters:
      - name: organization
        in: path
        required: true
        schema:
          type: string
          title: Organization
      - name: conversation_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-f0-9]{24}$
          description: The identifier of the conversation.
          title: Conversation Id
        description: The identifier of the conversation.
      - name: id
        in: query
        required: false
        schema:
          type: array
          uniqueItems: true
          items:
            type: string
            pattern: ^[a-f0-9]{24}$
          description: The IDs of the messages to retrieve.
          default: []
          title: Id
        description: The IDs of the messages to retrieve.
      - name: message_type
        in: query
        required: false
        schema:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/MessageType'
          description: The type of messages to retrieve.
          default:
          - user-message
          - agent-message
          - external-event
          title: Message Type
        description: The type of messages to retrieve.
      - name: interaction_id
        in: query
        required: false
        schema:
          type: array
          uniqueItems: true
          items:
            type: string
            pattern: ^[a-f0-9]{24}$
          description: The IDs of the interactions to retrieve messages for.
          default: []
          title: Interaction Id
        description: The IDs of the interactions to retrieve messages for.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 500
          exclusiveMinimum: 0
          description: The maximum number of messages to return. At most 500 messages can be returned in one request.
          default: 500
          title: Limit
        description: The maximum number of messages to return. At most 500 messages can be returned in one request.
      - name: continuation_token
        in: query
        required: false
        schema:
          type: integer
          description: The continuation token to use to retrieve the next set of messages.
          default: 0
          title: Continuation Token
        description: The continuation token to use to retrieve the next set of messages.
      - name: sort_by
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
          description: The field to sort the messages by. Supported fields are `interaction_id` and `created_at`. Specify a `+` before the field name to indicate ascending sorting and `-` for descending sorting. Multiple fields can be specified to break ties.
          default: []
          title: Sort By
        description: The field to sort the messages by. Supported fields are `interaction_id` and `created_at`. Specify a `+` before the field name to indicate ascending sorting and `-` for descending sorting. Multiple fields can be specified to break ties.
      - name: x-mongo-cluster-name
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.
          title: X-Mongo-Cluster-Name
        description: The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.
      - name: Sec-WebSocket-Protocol
        in: header
        required: false
        schema:
          type: array
          items:
            type: string
          default: []
          title: Sec-Websocket-Protocol
      responses:
        '200':
          description: Succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/src__app__endpoints__conversation__get_conversation_messages__Response'
        '422':
          description: Invalid request path parameter failed validation.
        '404':
          description: Specified organization or conversation is not found.
        '401':
          description: Invalid authorization credentials.
        '403':
          description: Missing required permissions.
        '503':
          description: The service is going through temporary maintenance.
        '429':
          description: The user has exceeded the rate limit of 20 requests per minute for this endpoint.
  /v1/{organization}/conversation/{conversation_id}/finish/:
    post:
      tags:
      - Conversation
      summary: Finish a conversation
      description: 'Conclude a conversation and asynchronously initiate post-conversation analysis.


        This endpoint should only be called on a started, non-finished conversation. It can only be called when the previous [`Start a conversation`](start-conversation) and

        [`Interact with a conversation`](interact-with-conversation) calls have finished.


        If the conversation has no messages, the conversation is deleted.


        It''s possible for some conversations to automatically finish during an [`Interact with a conversation`](interact-with-conversation) call (for instance, if the user explicitly sends a message

        indicating that they''re done with the conversation). In that case, this endpoint shouldn''t be called, as the [`Interact with a conversation`](interact-with-conversation) endpoint automatically

        wraps up the conversation.


        #### Permissions

        This endpoint requires the following permissions:

        * `User:UpdateUserInfo` on the user who started the conversation.

        * `Conversation:FinishConversation` on the conversation.'
      operationId: finish-conversation
      parameters:
      - name: conversation_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-f0-9]{24}$
          description: The identifier of the conversation to finish.
          title: Conversation Id
        description: The identifier of the conversation to finish.
      - name: organization
        in: path
        required: true
        schema:
          type: string
          title: Organization
      - name: x-mongo-cluster-name
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.
          title: X-Mongo-Cluster-Name
        description: The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.
      - name: Sec-WebSocket-Protocol
        in: header
        required: false
        schema:
          type: array
          items:
            type: string
          default: []
          title: Sec-Websocket-Protocol
      responses:
        '204':
          description: Succeeded.
        '404':
          description: Specified organization or conversation is not found.
        '422':
          description: Invalid request path parameter failed validation.
        '409':
          description: The specified conversation is already finished, or a related operation is in process.
        '400':
          description: The conversation has no interactions.
        '401':
          description: Invalid authorization credentials.
        '403':
          description: Missing required permissions.
        '503':
          description: The service is going through temporary maintenance.
        '429':
          description: The user has exceeded the rate limit of 5 requests per minute for this endpoint.
  /v1/{organization}/conversation/{conversation_id}/interaction/{interaction_id}/recommend_responses:
    post:
      tags:
      - Conversation
      summary: Recommend responses for interaction
      description: 'Generate a recommended response for the user to send based on the existing chat history. This should be called when the most recent interaction

        had concluded for a while but the user still hasn''t responded.


        #### Permissions:

        This endpoint requires the following permissions:

        * `Conversation:GetRecommendedResponses` on this conversation.'
      operationId: recommend-responses-for-interaction
      parameters:
      - name: conversation_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-f0-9]{24}$
          description: The identifier of the conversation.
          title: Conversation Id
        description: The identifier of the conversation.
      - name: interaction_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-f0-9]{24}$
          description: The identifier of the most recent interaction.
          title: Interaction Id
        description: The identifier of the most recent interaction.
      - name: organization
        in: path
        required: true
        schema:
          type: string
          title: Organization
      - name: x-mongo-cluster-name
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.
          title: X-Mongo-Cluster-Name
        description: The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.
      - name: Sec-WebSocket-Protocol
        in: header
        required: false
        schema:
          type: array
          items:
            type: string
          default: []
          title: Sec-Websocket-Protocol
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/src__app__endpoints__conversation__recommend_responses_for_interaction__Request'
              default:
                context: '

                  PERSONA:

                  Name: User

                  Background: A typical person seeking this service.

                  ---

                  SCENARIO:

                  Name: Complete Service

                  Objective: Successfully complete the service interaction.

                  Instructions: Engage naturally with the agent to achieve the service objective.

                  '
      responses:
        '200':
          description: Succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/src__app__endpoints__conversation__recommend_responses_for_interaction__Response'
        '422':
          description: Invalid request path parameter failed validation.
        '404':
          description: Specified organization or conversation is not found.
        '400':
          description: The conversation is finished, or the supplied interaction ID doesn't correspond to the latest, completed interaction.
        '401':
          description: Invalid authorization credentials.
        '403':
          description: Missing required permissions.
        '503':
          description: The service is going through temporary maintenance.
        '429':
          description: The user has exceeded the rate limit of 20 requests per minute for this endpoint.
  /v1/{organization}/conversation/{conversation_id}/interaction/{interaction_id}/insights:
    get:
      tags:
      - Conversation
      summary: Get interaction insights
      description: 'Retrieve insights about the agent''s message for a given interaction.


        #### Permissions:

        This endpoint requires the following permissions:

        * `Conversation:GetInteractionInsights` on the conversation.

        * `Organization:GetServiceHierarchicalStateMachine` on the state machine that the current interaction is in.


        This endpoint may be impacted by the following permissions:

        * Only reflection messages for which the authenticated user has the `Conversation:GetMessage` permission are included in the response.'
      operationId: get-interaction-insights
      parameters:
      - name: conversation_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-f0-9]{24}$
          description: The identifier of the conversation.
          title: Conversation Id
        description: The identifier of the conversation.
      - name: interaction_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-f0-9]{24}$
          description: The identifier of the interaction.
          title: Interaction Id
        description: The identifier of the interaction.
      - name: organization
        in: path
        required: true
        schema:
          type: string
          title: Organization
      - name: x-mongo-cluster-name
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.
          title: X-Mongo-Cluster-Name
        description: The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.
      - name: Sec-WebSocket-Protocol
        in: header
        required: false
        schema:
          type: array
          items:
            type: string
          default: []
          title: Sec-Websocket-Protocol
      responses:
        '200':
          description: Succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/src__app__endpoints__conversation__get_interaction_insights__Response'
        '404':
          description: Specified organization, conversation, or interaction is not found.
        '422':
          description: Invalid request path parameter failed validation.
        '401':
          description: Invalid authorization credentials.
        '403':
          description: Missing required permissions.
        '503':
          description: The service is going through temporary maintenance.
        '429':
          description: The user has exceeded the rate limit of 20 requests per minute for this endpoint.
  /v1/{organization}/conversation/{conversation_id}/interact:
    post:
      tags:
      - Conversation
      summary: Interact with a conversation
      description: 'Send a new user message to the conversation. The endpoint will perform analysis and generate an agent message in response.


        A `UserMessageAvailableEvent` will be the first event in the response, which includes the user message if it''s sent as text, or the transcribed message if it''s sent as voice.

        A series of `CurrentAgentActionEvent`s will follow, which indicates steps in the agent''s thinking process. Then the agent message is generated sequentially in pieces, with each piece

        being sent as a `NewMessageEvent` in the response. After all the pieces are sent, an `InteractionCompleteEvent` is sent. Depending on the `conversation_completed` property in this event, the conversation will be awaiting

        a new message from the user, or it might automatically end (for instance, because the user message indicates the user wants to end the session), while the conversation is marked as finished and the post-conversation

        analysis asynchronously initiated. The connection will then terminate.


        Any further action on the conversation is only allowed after the connection is terminated.


        A 200 status code doesn''t indicate the successful completion of this endpoint, because the status code is transmitted before the stream starts. At any point during the stream,

        an `ErrorEvent` might be sent, which indicates that an error has occurred. The connection will be immediately closed after.


        This endpoint can only be called on a conversation that has started but not finished.


        #### Permissions

        This endpoint requires the following permissions:

        * `User:UpdateUserInfo` on the user who started the conversation.

        * `Conversation:InteractWithConversation` on the conversation.


        This endpoint may be impacted by the following permissions:

        * `CurrentAgentActionEvent`s are only emitted if the authenticated user has the `Conversation:GetInteractionInsights` permission.'
      operationId: interact-with-conversation
      parameters:
      - name: conversation_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-f0-9]{24}$
          description: The identifier of the conversation to send a message to.
          title: Conversation Id
        description: The identifier of the conversation to send a message to.
      - name: organization
        in: path
        required: true
        schema:
          type: string
          title: Organization
      - name: request_format
        in: query
        required: true
        schema:
          enum:
          - text
          - voice
          type: string
          description: The format in which the user message is delivered to the server.
          title: Request Format
        description: The format in which the user message is delivered to the server.
      - name: response_format
        in: query
        required: true
        schema:
          enum:
          - text
          - voice
          type: string
          description: The format of the response that will be sent to the user.
          title: Response Format
        description: The format of the response that will be sent to the user.
      - name: current_agent_action_type
        in: query
        required: false
        schema:
          type: string
          description: A regex for filtering the type of the current agent action to return. By default, all are returned. If you don't want to receive any events, set this to a regex that matches nothing, for instance `^$`.
          default: ^.*$
          title: Current Agent Action Type
        description: A regex for filtering the type of the current agent action to return. By default, all are returned. If you don't want to receive any events, set this to a regex that matches nothing, for instance `^$`.
      - name: request_audio_config
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/UserMessageAudioConfig'
          - type: 'null'
          description: Configuration for the user message audio. This is only required if `request_format` is set to `voice`.
          title: Request Audio Config
        description: Configuration for the user message audio. This is only required if `request_format` is set to `voice`.
      - name: content-type
        in: header
        required: true
        schema:
          type: string
          pattern: ^multipart\/form-data; boundary=.+$
          description: The content type of the request body, which must be `multipart/form-data` followed by a boundary.
          title: Content-Type
        description: The content type of the request body, which must be `multipart/form-data` followed by a boundary.
      - name: x-mongo-cluster-name
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.
          title: X-Mongo-Cluster-Name
        description: The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.
      - name: Sec-WebSocket-Protocol
        in: header
        required: false
        schema:
          type: array
          items:
            type: string
          default: []
          title: Sec-Websocket-Protocol
      responses:
        '200':
          description: '

            Succeeded. The response will be a stream of events in JSON format separated by newlines. The server will transmit an event as soon as one is available,

            so the client should respond to the events as soon as one arrives, and keep listening until the server closes the connection.

            '
          content:
            applicat

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