openapi: 3.0.1 info: title: Conversations API description: Operations to manage ASAPP conversations contact: email: api-info@asapp.com license: name: ASAPP Software License url: https://api.asapp.com/LICENSE version: '0.1' servers: - url: https://api.sandbox.asapp.com tags: - name: Conversations description: Operations to send conversational inputs to ASAPP AI services security: - API-ID: [] API-Secret: [] paths: /conversation/v1/conversations: post: tags: - Conversations operationId: createOrUpdateConversation summary: Create or update a conversation description: > Creates a new conversation or updates an existing one based on the provided `externalId`. Use this endpoint when: - Starting a new conversation - Updating conversation details (e.g., reassigning to a different agent) If the `externalId` is not found, a new conversation will be created. Otherwise, the existing conversation will be updated. requestBody: required: true content: application/json: schema: description: >- Conversation between an agent and a customer that requires a timestamp of creation type: object properties: id: type: string description: The identifier of the conversation. externalId: type: string description: Your unique identifier for a conversation. agent: type: object description: >- Information about the agent participating in the conversation. properties: externalId: type: string description: >- The unique identifier for the agent in your external system. name: type: string description: The display name of the agent. required: - externalId customer: type: object description: >- Information about the customer participating in the conversation. properties: externalId: type: string description: >- The unique identifier for the customer in your external system. name: type: string description: The display name of the customer. required: - externalId metadata: type: object additionalProperties: type: string description: >- Additional key-value pairs to store custom metadata about the conversation. Use this for filtering or categorization purposes. timestamp: type: string format: date-time description: >- The time when the conversation was created. Include the timezone, otherwise UTC will be assumed. required: - externalId - customer - timestamp example: externalId: id-111 agent: externalId: agent-111 name: agent-x customer: externalId: customer-x name: customer-name-x metadata: organizationalGroup: some-group subdivision: some-division queue: some-queue timestamp: '2021-11-23T12:13:14.555Z' responses: '200': description: Successfully created or updated conversation content: application/json: schema: description: Response for conversation type: object properties: id: type: string description: The identifier of the conversation. example: id: 01BX5ZZKBKACTAV9WEVGEMMVRZ '400': description: 400 - Bad request content: application/json: schema: description: Bad request response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 400-01 message: Bad request description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '401': description: 401 - Unauthorized content: application/json: schema: description: Unauthorized response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 401-01 message: Unauthorized description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '403': description: 403 - Forbidden content: application/json: schema: description: Forbidden response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 403-01 message: Forbidden Response description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '404': description: 404 - Not Found content: application/json: schema: description: Not Found response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 404-01 message: Not Found description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '409': description: 409 - Conflict content: application/json: schema: description: Conflict response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 409-01 message: Conflict description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '413': description: 413 - Request Entity Too Large content: application/json: schema: description: Request Entity Too Large response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 413-01 message: Request Entity Too Large description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '422': description: 422 - Unprocessable Entity content: application/json: schema: description: Unprocessable Entity response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 422-01 message: Unprocessable Entity description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '429': description: 429 - Too Many Requests content: application/json: schema: description: Too Many Requests response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 429-01 message: Too Many Requests description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '503': description: 503 - Service Unavailable content: application/json: schema: description: Service Unavailable response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 503-01 message: Service Unavailable description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message default: description: 500 - Internal Server Error content: application/json: schema: description: Default error response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 500-01 message: Internal server error description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message get: tags: - Conversations operationId: getConversations summary: List conversations description: > Retrieves a list of conversation resources that match the specified criteria. You must provide at least one search criterion in the query parameters. parameters: - name: externalId description: Your identifier for a conversation. in: query required: true schema: type: string example: externalId: id-111 responses: '200': description: Successfully fetched conversations content: application/json: schema: description: A list of conversations type: object properties: items: type: array items: description: >- Represents a conversation between an agent and a customer. type: object properties: id: type: string description: >- The unique identifier for the conversation within the ASAPP system. externalId: type: string description: >- The unique identifier for the conversation in your external chat or voice system. agent: type: object description: >- Information about the agent participating in the conversation. properties: externalId: type: string description: >- The unique identifier for the agent in your external system. name: type: string description: The display name of the agent. required: - externalId customer: type: object description: >- Information about the customer participating in the conversation. properties: externalId: type: string description: >- The unique identifier for the customer in your external system. name: type: string description: The display name of the customer. required: - externalId metadata: type: object additionalProperties: type: string description: >- Additional key-value pairs to store custom metadata about the conversation. Use this for filtering or categorization purposes. required: - externalId - customer example: id: 01BX5ZZKBKACTAV9WEVGEMMVRZ externalId: id-111 agent: externalId: agent-111 name: agent-x customer: externalId: customer-x name: customer-name-x metadata: organizationalGroup: some-group subdivision: some-division queue: some-queue '400': description: 400 - Bad request content: application/json: schema: description: Bad request response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 400-01 message: Bad request description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '401': description: 401 - Unauthorized content: application/json: schema: description: Unauthorized response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 401-01 message: Unauthorized description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '403': description: 403 - Forbidden content: application/json: schema: description: Forbidden response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 403-01 message: Forbidden Response description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '404': description: 404 - Not Found content: application/json: schema: description: Not Found response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 404-01 message: Not Found description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '422': description: 422 - Unprocessable Entity content: application/json: schema: description: Unprocessable Entity response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 422-01 message: Unprocessable Entity description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '429': description: 429 - Too Many Requests content: application/json: schema: description: Too Many Requests response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 429-01 message: Too Many Requests description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '503': description: 503 - Service Unavailable content: application/json: schema: description: Service Unavailable response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 503-01 message: Service Unavailable description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message default: description: 500 - Internal Server Error content: application/json: schema: description: Default error response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 500-01 message: Internal server error description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message /conversation/v1/conversations/{conversationId}: parameters: - name: conversationId description: The identifier for a conversation. in: path required: true schema: type: string pattern: ^[A-Z0-9]+$ get: tags: - Conversations operationId: getConversation summary: Retrieve a conversation description: > Retrieves the details of a specific conversation using its `conversationId`. This endpoint returns detailed information about the conversation, including participants and metadata. responses: '200': description: Successfully fetched conversation content: application/json: schema: description: Represents a conversation between an agent and a customer. type: object properties: id: type: string description: >- The unique identifier for the conversation within the ASAPP system. externalId: type: string description: >- The unique identifier for the conversation in your external chat or voice system. agent: type: object description: >- Information about the agent participating in the conversation. properties: externalId: type: string description: >- The unique identifier for the agent in your external system. name: type: string description: The display name of the agent. required: - externalId customer: type: object description: >- Information about the customer participating in the conversation. properties: externalId: type: string description: >- The unique identifier for the customer in your external system. name: type: string description: The display name of the customer. required: - externalId metadata: type: object additionalProperties: type: string description: >- Additional key-value pairs to store custom metadata about the conversation. Use this for filtering or categorization purposes. required: - externalId - customer example: id: 01BX5ZZKBKACTAV9WEVGEMMVRZ externalId: id-111 agent: externalId: agent-111 name: agent-x customer: externalId: customer-x name: customer-name-x metadata: organizationalGroup: some-group subdivision: some-division queue: some-queue '400': description: 400 - Bad request content: application/json: schema: description: Bad request response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 400-01 message: Bad request description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '401': description: 401 - Unauthorized content: application/json: schema: description: Unauthorized response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 401-01 message: Unauthorized description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '403': description: 403 - Forbidden content: application/json: schema: description: Forbidden response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 403-01 message: Forbidden Response description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '404': description: 404 - Not Found content: application/json: schema: description: Not Found response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 404-01 message: Not Found description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '422': description: 422 - Unprocessable Entity content: application/json: schema: description: Unprocessable Entity response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 422-01 message: Unprocessable Entity description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '429': description: 429 - Too Many Requests content: application/json: schema: description: Too Many Requests response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 429-01 message: Too Many Requests description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '503': description: 503 - Service Unavailable content: application/json: schema: description: Service Unavailable response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 503-01 message: Service Unavailable description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message default: description: 500 - Internal Server Error content: application/json: schema: description: Default error response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 500-01 message: Internal server error description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message /conversation/v1/conversations/{conversationId}/messages: parameters: - name: conversationId description: The identifier for a conversation. in: path required: true schema: type: string pattern: ^[A-Z0-9]+$ post: tags: - Conversations operationId: createMessage summary: Create a message description: | Creates a message object, adding it to an existing conversation. Use this endpoint to record each new message in the conversation. requestBody: required: true content: application/json: schema: description: Represents a single message within a conversation. type: object properties: text: type: string minLength: 1 description: The content of the message. sender: description: Information about the participant who sent the message. type: object properties: role: description: The role of the participant in the conversation. type: string enum: - agent - customer - system externalId: type: string description: >- The unique identifier for the participant in your external system. This should be consistent across all interactions for the same individual. required: - role - externalId timestamp: type: string format: date-time description: >- The time when the message was sent. Include the timezone, otherwise UTC will be assumed. required: - text - sender - timestamp example: text: Hello, I would like to upgrade my internet plan to GOLD. sender: role: agent externalId: 123 timestamp: '2021-11-23T12:13:14.555Z' responses: '200': description: Successfully created message in conversation content: application/json: schema: description: Response for messages type: object properties: id: type: string description: Message ID to be used for analytics example: id: 01BX5ZZKBKACTAV9WEVGEMMVS1 '400': description: 400 - Bad request content: application/json: schema: description: Bad request response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 400-01 message: Bad request description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '401': description: 401 - Unauthorized content: application/json: schema: description: Unauthorized response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 401-01 message: Unauthorized description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '403': description: 403 - Forbidden content: application/json: schema: description: Forbidden response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 403-01 message: Forbidden Response description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '404': description: 404 - Not Found content: application/json: schema: description: Not Found response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 404-01 message: Not Found description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '409': description: 409 - Conflict content: application/json: schema: description: Conflict response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 409-01 message: Conflict description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '413': description: 413 - Request Entity Too Large content: application/json: schema: description: Request Entity Too Large response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 413-01 message: Request Entity Too Large description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '422': description: 422 - Unprocessable Entity content: application/json: schema: description: Unprocessable Entity response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 422-01 message: Unprocessable Entity description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '429': description: 429 - Too Many Requests content: application/json: schema: description: Too Many Requests response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 429-01 message: Too Many Requests description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '503': description: 503 - Service Unavailable content: application/json: schema: description: Service Unavailable response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 503-01 message: Service Unavailable description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message default: description: 500 - Internal Server Error content: application/json: schema: description: Default error response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 500-01 message: Internal server error description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message get: tags: - Conversations operationId: getMessages summary: List messages description: | Lists all messages within a conversation. This messages are returned in chronological order. responses: '200': description: Successfully fetched messages from a conversation content: application/json: schema: description: Response for GetMessages type: object properties: items: type: array items: description: A message sent by a participant of a conversation type: object properties: text: type: string minLength: 1 description: Text sent sender: description: A participant within a conversation type: object properties: role: description: > A participant role, usually the customer or an agent for human participants. System participant is also allowed but keep in mind that this role won't be considered a participant in a conversation, just a message sender. type: string enum: - agent - customer - system externalId: type: string nullable: true description: >- The unique identifier for the relevant participant role. required: - role messageId: type: string minLength: 1 description: The identifier of the message. createdTimestamp: type: string format: date-time description: >- The time when the message objectwas created in the ASAPP system. clientTimestamp: type: string format: date-time description: The timestamp of when the message was sent. required: - text - sender - messageId - createdTimestamp - clientTimestamp example: text: >- Hello, I would like to upgrade my internet plan to GOLD. sender: role: customer externalId: '123456' messageId: 01GMXE90AEV7H3J4DPBDKB1R79 createdTimestamp: '2021-11-23T12:13:16.853Z' clientTimestamp: '2021-11-23T12:13:14.555Z' '400': description: 400 - Bad request content: application/json: schema: description: Bad request response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 400-01 message: Bad request description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '401': description: 401 - Unauthorized content: application/json: schema: description: Unauthorized response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 401-01 message: Unauthorized description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '403': description: 403 - Forbidden content: application/json: schema: description: Forbidden response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 403-01 message: Forbidden Response description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '404': description: 404 - Not Found content: application/json: schema: description: Not Found response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 404-01 message: Not Found description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '409': description: 409 - Conflict content: application/json: schema: description: Conflict response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 409-01 message: Conflict description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '413': description: 413 - Request Entity Too Large content: application/json: schema: description: Request Entity Too Large response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 413-01 message: Request Entity Too Large description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '422': description: 422 - Unprocessable Entity content: application/json: schema: description: Unprocessable Entity response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 422-01 message: Unprocessable Entity description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '429': description: 429 - Too Many Requests content: application/json: schema: description: Too Many Requests response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 429-01 message: Too Many Requests description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '503': description: 503 - Service Unavailable content: application/json: schema: description: Service Unavailable response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 503-01 message: Service Unavailable description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message default: description: 500 - Internal Server Error content: application/json: schema: description: Default error response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 500-01 message: Internal server error description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message /conversation/v1/conversations/{conversationId}/messages/{messageId}: parameters: - name: conversationId description: The identifier for a conversation. in: path required: true schema: type: string pattern: ^[A-Z0-9]+$ - name: messageId description: Internal message identifier from ASAPP in: path required: true schema: type: string pattern: ^[A-Z0-9]+$ get: tags: - Conversations operationId: getMessage summary: Retrieve a message description: | Retrieve the details of a message from a conversation. responses: '200': description: Successfully fetched message from a conversation content: application/json: schema: description: Response for GetMessage type: object properties: text: type: string minLength: 1 description: Text sent sender: description: A participant within a conversation type: object properties: role: description: > A participant role, usually the customer or an agent for human participants. System participant is also allowed but keep in mind that this role won't be considered a participant in a conversation, just a message sender. type: string enum: - agent - customer - system externalId: type: string nullable: true description: >- The unique identifier for the relevant participant role. required: - role messageId: type: string minLength: 1 description: The identifier of the message. createdTimestamp: type: string format: date-time description: >- The time when the message object was created in the ASAPP system. clientTimestamp: type: string format: date-time description: The timestamp of when the message was sent. required: - text - sender - messageId - createdTimestamp - clientTimestamp example: text: Hello, I would like to upgrade my internet plan to GOLD. sender: role: customer externalId: '123456' messageId: 01GMXE90AEV7H3J4DPBDKB1R79 createdTimestamp: '2021-11-23T12:13:16.853Z' clientTimestamp: '2021-11-23T12:13:14.555Z' '400': description: 400 - Bad request content: application/json: schema: description: Bad request response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 400-01 message: Bad request description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '401': description: 401 - Unauthorized content: application/json: schema: description: Unauthorized response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 401-01 message: Unauthorized description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '403': description: 403 - Forbidden content: application/json: schema: description: Forbidden response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 403-01 message: Forbidden Response description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '404': description: 404 - Not Found content: application/json: schema: description: Not Found response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 404-01 message: Not Found description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '409': description: 409 - Conflict content: application/json: schema: description: Conflict response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 409-01 message: Conflict description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '413': description: 413 - Request Entity Too Large content: application/json: schema: description: Request Entity Too Large response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 413-01 message: Request Entity Too Large description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '422': description: 422 - Unprocessable Entity content: application/json: schema: description: Unprocessable Entity response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 422-01 message: Unprocessable Entity description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '429': description: 429 - Too Many Requests content: application/json: schema: description: Too Many Requests response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 429-01 message: Too Many Requests description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '503': description: 503 - Service Unavailable content: application/json: schema: description: Service Unavailable response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 503-01 message: Service Unavailable description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message default: description: 500 - Internal Server Error content: application/json: schema: description: Default error response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 500-01 message: Internal server error description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message /conversation/v1/conversations/{conversationId}/messages/batch: parameters: - name: conversationId description: The identifier for a conversation. in: path required: true schema: type: string pattern: ^[A-Z0-9]+$ post: tags: - Conversations operationId: createBatchMessages summary: Create multiple messages description: > This creates multiple message objects at once, adding them to an existing conversation. Use this endpoint when you need to add several messages at once, such as when importing historical conversation data. requestBody: required: true content: application/json: schema: description: A batch of messages for conversation type: object properties: messages: type: array items: description: Represents a single message within a conversation. type: object properties: text: type: string minLength: 1 description: The content of the message. sender: description: >- Information about the participant who sent the message. type: object properties: role: description: The role of the participant in the conversation. type: string enum: - agent - customer - system externalId: type: string description: >- The unique identifier for the participant in your external system. This should be consistent across all interactions for the same individual. required: - role - externalId timestamp: type: string format: date-time description: >- The time when the message was sent. Include the timezone, otherwise UTC will be assumed. required: - text - sender - timestamp example: text: Hello, I would like to upgrade my internet plan to GOLD. sender: role: agent externalId: 123 timestamp: '2021-11-23T12:13:14.555Z' minItems: 1 maxItems: 300 example: messages: - text: Hello, I would like to upgrade my internet plan to GOLD. sender: role: customer externalId: customer-xyz timestamp: '2021-11-23T12:13:14.555Z' - text: Let me help you with that sender: role: agent externalId: agent-111 timestamp: '2021-11-23T12:13:16.666Z' responses: '200': description: Successfully created messages in conversation content: application/json: schema: description: Response for batch messages type: object '400': description: 400 - Bad request content: application/json: schema: description: Bad request response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 400-01 message: Bad request description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '401': description: 401 - Unauthorized content: application/json: schema: description: Unauthorized response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 401-01 message: Unauthorized description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '403': description: 403 - Forbidden content: application/json: schema: description: Forbidden response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 403-01 message: Forbidden Response description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '404': description: 404 - Not Found content: application/json: schema: description: Not Found response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 404-01 message: Not Found description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '409': description: 409 - Conflict content: application/json: schema: description: Conflict response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 409-01 message: Conflict description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '413': description: 413 - Request Entity Too Large content: application/json: schema: description: Request Entity Too Large response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 413-01 message: Request Entity Too Large description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '422': description: 422 - Unprocessable Entity content: application/json: schema: description: Unprocessable Entity response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 422-01 message: Unprocessable Entity description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '429': description: 429 - Too Many Requests content: application/json: schema: description: Too Many Requests response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 429-01 message: Too Many Requests description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '503': description: 503 - Service Unavailable content: application/json: schema: description: Service Unavailable response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 503-01 message: Service Unavailable description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message default: description: 500 - Internal Server Error content: application/json: schema: description: Default error response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 500-01 message: Internal server error description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message /conversation/v1/conversation/messages: get: tags: - Conversations operationId: getMessagesByExternalId summary: List messages with an externalId description: | Get all messages from a conversation. parameters: - name: externalId description: Your identifier for a conversation. in: query required: true schema: type: string example: externalId: id-111 responses: '200': description: Successfully fetched messages from a conversation content: application/json: schema: description: Response for GetMessages type: object properties: items: type: array items: description: A message sent by a participant of a conversation type: object properties: text: type: string minLength: 1 description: Text sent sender: description: A participant within a conversation type: object properties: role: description: > A participant role, usually the customer or an agent for human participants. System participant is also allowed but keep in mind that this role won't be considered a participant in a conversation, just a message sender. type: string enum: - agent - customer - system externalId: type: string nullable: true description: >- The unique identifier for the relevant participant role. required: - role messageId: type: string minLength: 1 description: The identifier of the message. createdTimestamp: type: string format: date-time description: >- The time when the message objectwas created in the ASAPP system. clientTimestamp: type: string format: date-time description: The timestamp of when the message was sent. required: - text - sender - messageId - createdTimestamp - clientTimestamp example: text: >- Hello, I would like to upgrade my internet plan to GOLD. sender: role: customer externalId: '123456' messageId: 01GMXE90AEV7H3J4DPBDKB1R79 createdTimestamp: '2021-11-23T12:13:16.853Z' clientTimestamp: '2021-11-23T12:13:14.555Z' '400': description: 400 - Bad request content: application/json: schema: description: Bad request response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 400-01 message: Bad request description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '401': description: 401 - Unauthorized content: application/json: schema: description: Unauthorized response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 401-01 message: Unauthorized description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '403': description: 403 - Forbidden content: application/json: schema: description: Forbidden response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 403-01 message: Forbidden Response description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '404': description: 404 - Not Found content: application/json: schema: description: Not Found response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 404-01 message: Not Found description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '409': description: 409 - Conflict content: application/json: schema: description: Conflict response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 409-01 message: Conflict description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '413': description: 413 - Request Entity Too Large content: application/json: schema: description: Request Entity Too Large response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 413-01 message: Request Entity Too Large description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '422': description: 422 - Unprocessable Entity content: application/json: schema: description: Unprocessable Entity response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 422-01 message: Unprocessable Entity description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '429': description: 429 - Too Many Requests content: application/json: schema: description: Too Many Requests response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 429-01 message: Too Many Requests description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '503': description: 503 - Service Unavailable content: application/json: schema: description: Service Unavailable response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 503-01 message: Service Unavailable description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message default: description: 500 - Internal Server Error content: application/json: schema: description: Default error response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 500-01 message: Internal server error description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message /conversation/v1/conversations/{conversationId}/authenticate: post: tags: - Conversations summary: Authenticate a user in a conversation description: > Stores customer-specific authentication credentials for use in integrated flows. - Can be called at any point during a conversation - Commonly used at the start of a conversation or after mid-conversation authentication - May trigger additional actions, such as GenerativeAgent API signals to customer webhooks This API only accepts the customer-specific auth credentials; the customer is responsible for handling the specific authentication mechanism. operationId: postAuthenticate parameters: - name: conversationId description: The identifier for a conversation. in: path required: true schema: type: string pattern: ^[A-Z0-9]+$ requestBody: required: true content: application/json: schema: type: object description: >- Contains authentication information for a customer in a conversation. properties: streamId: type: string description: >- The unique identifier for the connection where responses should be sent. example: 97555020-0276-435f-8104-c378221ba292 customerExternalId: type: string description: >- The unique identifier for the customer in your external system. example: a03839d6-461c-479c-99db-8160174ef12d auth: type: object description: > An authentication payload that could contain different types of credentials, such as a token, used to authenticate an end user. All of the fields are optional, but at least one will be required minProperties: 1 properties: body: type: object description: >- Any authentication data to be sent in the request body, if applicable. cookies: type: object description: >- Any authentication data to be sent as cookies, if applicable. headers: type: object description: >- Any authentication data to be sent in the request headers, if applicable. token: type: string description: An authentication token for the user, if applicable. required: - customerExternalId - auth example: customerExternalId: customer-xyz token: cGFzc3dvcmQ= responses: '204': description: 204 - No Content '400': description: 400 - Bad request content: application/json: schema: description: Bad request response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 400-01 message: Bad request description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '401': description: 401 - Unauthorized content: application/json: schema: description: Unauthorized response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 401-01 message: Unauthorized description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '403': description: 403 - Forbidden content: application/json: schema: description: Forbidden response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 403-01 message: Forbidden Response description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '404': description: 404 - Not Found content: application/json: schema: description: Not Found response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 404-01 message: Not Found description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '422': description: 422 - Unprocessable Entity content: application/json: schema: description: Unprocessable Entity response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 422-01 message: Unprocessable Entity description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '429': description: 429 - Too Many Requests content: application/json: schema: description: Too Many Requests response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 429-01 message: Too Many Requests description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message '503': description: 503 - Service Unavailable content: application/json: schema: description: Service Unavailable response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 503-01 message: Service Unavailable description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message default: description: 500 - Internal Server Error content: application/json: schema: description: Default error response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 500-01 message: Internal server error description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message components: securitySchemes: API-ID: type: apiKey in: header name: asapp-api-id API-Secret: type: apiKey in: header name: asapp-api-secret parameters: conversationId: name: conversationId description: The identifier for a conversation. in: path required: true schema: type: string pattern: ^[A-Z0-9]+$ externalId: name: externalId description: Your identifier for a conversation. in: query required: true schema: type: string example: externalId: id-111 messageId: name: messageId description: Internal message identifier from ASAPP in: path required: true schema: type: string pattern: ^[A-Z0-9]+$ responses: BadRequest: description: 400 - Bad request content: application/json: schema: description: Bad request response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 400-01 message: Bad request description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message DefaultError: description: 500 - Internal Server Error content: application/json: schema: description: Default error response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 500-01 message: Internal server error description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message Unauthorized: description: 401 - Unauthorized content: application/json: schema: description: Unauthorized response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 401-01 message: Unauthorized description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message Forbidden: description: 403 - Forbidden content: application/json: schema: description: Forbidden response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 403-01 message: Forbidden Response description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message NotFound: description: 404 - Not Found content: application/json: schema: description: Not Found response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 404-01 message: Not Found description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message Conflict: description: 409 - Conflict content: application/json: schema: description: Conflict response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 409-01 message: Conflict description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message RequestEntityTooLarge: description: 413 - Request Entity Too Large content: application/json: schema: description: Request Entity Too Large response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 413-01 message: Request Entity Too Large description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message UnprocessableEntity: description: 422 - Unprocessable Entity content: application/json: schema: description: Unprocessable Entity response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 422-01 message: Unprocessable Entity description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message TooManyRequests: description: 429 - Too Many Requests content: application/json: schema: description: Too Many Requests response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 429-01 message: Too Many Requests description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message ServiceUnavailable: description: 503 - Service Unavailable content: application/json: schema: description: Service Unavailable response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 503-01 message: Service Unavailable description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message schemas: Conversation: description: Represents a conversation between an agent and a customer. type: object properties: id: type: string description: The unique identifier for the conversation within the ASAPP system. externalId: type: string description: >- The unique identifier for the conversation in your external chat or voice system. agent: type: object description: Information about the agent participating in the conversation. properties: externalId: type: string description: The unique identifier for the agent in your external system. name: type: string description: The display name of the agent. required: - externalId customer: type: object description: Information about the customer participating in the conversation. properties: externalId: type: string description: The unique identifier for the customer in your external system. name: type: string description: The display name of the customer. required: - externalId metadata: type: object additionalProperties: type: string description: >- Additional key-value pairs to store custom metadata about the conversation. Use this for filtering or categorization purposes. required: - externalId - customer example: id: 01BX5ZZKBKACTAV9WEVGEMMVRZ externalId: id-111 agent: externalId: agent-111 name: agent-x customer: externalId: customer-x name: customer-name-x metadata: organizationalGroup: some-group subdivision: some-division queue: some-queue TimeBasedConversation: description: >- Conversation between an agent and a customer that requires a timestamp of creation type: object properties: id: type: string description: The identifier of the conversation. externalId: type: string description: Your unique identifier for a conversation. agent: type: object description: Information about the agent participating in the conversation. properties: externalId: type: string description: The unique identifier for the agent in your external system. name: type: string description: The display name of the agent. required: - externalId customer: type: object description: Information about the customer participating in the conversation. properties: externalId: type: string description: The unique identifier for the customer in your external system. name: type: string description: The display name of the customer. required: - externalId metadata: type: object additionalProperties: type: string description: >- Additional key-value pairs to store custom metadata about the conversation. Use this for filtering or categorization purposes. timestamp: type: string format: date-time description: >- The time when the conversation was created. Include the timezone, otherwise UTC will be assumed. required: - externalId - customer - timestamp example: externalId: id-111 agent: externalId: agent-111 name: agent-x customer: externalId: customer-x name: customer-name-x metadata: organizationalGroup: some-group subdivision: some-division queue: some-queue timestamp: '2021-11-23T12:13:14.555Z' ParticipantRole: description: > A participant role, usually the customer or an agent for human participants. System participant is also allowed but keep in mind that this role won't be considered a participant in a conversation, just a message sender. type: string enum: - agent - customer - system Participant: description: Represents a participant in the conversation. type: object properties: role: description: The role of the participant in the conversation. type: string enum: - agent - customer - system externalId: type: string description: >- The unique identifier for the participant in your external system. This should be consistent across all interactions for the same individual. required: - role - externalId Message: description: Represents a single message within a conversation. type: object properties: text: type: string minLength: 1 description: The content of the message. sender: description: Information about the participant who sent the message. type: object properties: role: description: The role of the participant in the conversation. type: string enum: - agent - customer - system externalId: type: string description: >- The unique identifier for the participant in your external system. This should be consistent across all interactions for the same individual. required: - role - externalId timestamp: type: string format: date-time description: >- The time when the message was sent. Include the timezone, otherwise UTC will be assumed. required: - text - sender - timestamp example: text: Hello, I would like to upgrade my internet plan to GOLD. sender: role: agent externalId: 123 timestamp: '2021-11-23T12:13:14.555Z' BatchMessages: description: A batch of messages for conversation type: object properties: messages: type: array items: description: Represents a single message within a conversation. type: object properties: text: type: string minLength: 1 description: The content of the message. sender: description: Information about the participant who sent the message. type: object properties: role: description: The role of the participant in the conversation. type: string enum: - agent - customer - system externalId: type: string description: >- The unique identifier for the participant in your external system. This should be consistent across all interactions for the same individual. required: - role - externalId timestamp: type: string format: date-time description: >- The time when the message was sent. Include the timezone, otherwise UTC will be assumed. required: - text - sender - timestamp example: text: Hello, I would like to upgrade my internet plan to GOLD. sender: role: agent externalId: 123 timestamp: '2021-11-23T12:13:14.555Z' minItems: 1 maxItems: 300 example: messages: - text: Hello, I would like to upgrade my internet plan to GOLD. sender: role: customer externalId: customer-xyz timestamp: '2021-11-23T12:13:14.555Z' - text: Let me help you with that sender: role: agent externalId: agent-111 timestamp: '2021-11-23T12:13:16.666Z' ConversationResponse: description: Response for conversation type: object properties: id: type: string description: The identifier of the conversation. example: id: 01BX5ZZKBKACTAV9WEVGEMMVRZ Conversations: description: A list of conversations type: object properties: items: type: array items: description: Represents a conversation between an agent and a customer. type: object properties: id: type: string description: >- The unique identifier for the conversation within the ASAPP system. externalId: type: string description: >- The unique identifier for the conversation in your external chat or voice system. agent: type: object description: Information about the agent participating in the conversation. properties: externalId: type: string description: >- The unique identifier for the agent in your external system. name: type: string description: The display name of the agent. required: - externalId customer: type: object description: >- Information about the customer participating in the conversation. properties: externalId: type: string description: >- The unique identifier for the customer in your external system. name: type: string description: The display name of the customer. required: - externalId metadata: type: object additionalProperties: type: string description: >- Additional key-value pairs to store custom metadata about the conversation. Use this for filtering or categorization purposes. required: - externalId - customer example: id: 01BX5ZZKBKACTAV9WEVGEMMVRZ externalId: id-111 agent: externalId: agent-111 name: agent-x customer: externalId: customer-x name: customer-name-x metadata: organizationalGroup: some-group subdivision: some-division queue: some-queue MessagesResponse: description: Response for messages type: object properties: id: type: string description: Message ID to be used for analytics example: id: 01BX5ZZKBKACTAV9WEVGEMMVS1 BatchMessagesResponse: description: Response for batch messages type: object GetMessagesResponse: description: Response for GetMessages type: object properties: items: type: array items: description: A message sent by a participant of a conversation type: object properties: text: type: string minLength: 1 description: Text sent sender: description: A participant within a conversation type: object properties: role: description: > A participant role, usually the customer or an agent for human participants. System participant is also allowed but keep in mind that this role won't be considered a participant in a conversation, just a message sender. type: string enum: - agent - customer - system externalId: type: string nullable: true description: The unique identifier for the relevant participant role. required: - role messageId: type: string minLength: 1 description: The identifier of the message. createdTimestamp: type: string format: date-time description: >- The time when the message objectwas created in the ASAPP system. clientTimestamp: type: string format: date-time description: The timestamp of when the message was sent. required: - text - sender - messageId - createdTimestamp - clientTimestamp example: text: Hello, I would like to upgrade my internet plan to GOLD. sender: role: customer externalId: '123456' messageId: 01GMXE90AEV7H3J4DPBDKB1R79 createdTimestamp: '2021-11-23T12:13:16.853Z' clientTimestamp: '2021-11-23T12:13:14.555Z' GetMessageResponse: description: Response for GetMessage type: object properties: text: type: string minLength: 1 description: Text sent sender: description: A participant within a conversation type: object properties: role: description: > A participant role, usually the customer or an agent for human participants. System participant is also allowed but keep in mind that this role won't be considered a participant in a conversation, just a message sender. type: string enum: - agent - customer - system externalId: type: string nullable: true description: The unique identifier for the relevant participant role. required: - role messageId: type: string minLength: 1 description: The identifier of the message. createdTimestamp: type: string format: date-time description: The time when the message object was created in the ASAPP system. clientTimestamp: type: string format: date-time description: The timestamp of when the message was sent. required: - text - sender - messageId - createdTimestamp - clientTimestamp example: text: Hello, I would like to upgrade my internet plan to GOLD. sender: role: customer externalId: '123456' messageId: 01GMXE90AEV7H3J4DPBDKB1R79 createdTimestamp: '2021-11-23T12:13:16.853Z' clientTimestamp: '2021-11-23T12:13:14.555Z' AuthObject: type: object description: Contains authentication information for a customer in a conversation. properties: streamId: type: string description: >- The unique identifier for the connection where responses should be sent. example: 97555020-0276-435f-8104-c378221ba292 customerExternalId: type: string description: The unique identifier for the customer in your external system. example: a03839d6-461c-479c-99db-8160174ef12d auth: type: object description: > An authentication payload that could contain different types of credentials, such as a token, used to authenticate an end user. All of the fields are optional, but at least one will be required minProperties: 1 properties: body: type: object description: >- Any authentication data to be sent in the request body, if applicable. cookies: type: object description: Any authentication data to be sent as cookies, if applicable. headers: type: object description: >- Any authentication data to be sent in the request headers, if applicable. token: type: string description: An authentication token for the user, if applicable. required: - customerExternalId - auth example: customerExternalId: customer-xyz token: cGFzc3dvcmQ=