openapi: 3.1.0 info: title: Data Export version: 1.0.0 paths: /v2/export/conversations: get: operationId: get-conversations summary: Return conversations matching the parameters description: Returns a list of `conversation` objects along with a `next_page_uri` if applicable tags: - subpackage_conversations parameters: - name: created_since in: query description: >- Return records that were created after this date. If `created_to` is not specified, only records within 7 days of this timestamp are returned. To retrieve data beyond that window, set `created_to` explicitly. Note that `updated_since` and `created_since` are mutually exclusive, so you must only use one in a request. Must be an ISO 8601 UTC timestamp ending with 'Z' (e.g., `2024-07-01T00:00:00Z`); required for valid API requests. required: false schema: type: string format: date-time - name: updated_since in: query description: >- Return records that were updated after this date. Note that `updated_since` and `created_since` are mutually exclusive, so you must only use one in a request. Must be an ISO 8601 UTC timestamp ending with 'Z' (e.g., `2024-07-01T00:00:00Z`); required for valid API requests. required: false schema: type: string format: date-time - name: page_size in: query description: Number of records to return in response. The maximum and default is 10000, the minimum is 100. required: false schema: type: integer default: 10000 - name: created_to in: query description: >- Return records that were created earlier than this date. If `created_since` is used and this parameter is not specified, this value defaults to 7 days after `created_since`. Must be an ISO 8601 UTC timestamp ending with 'Z' (e.g., `2024-07-01T00:00:00Z`); required for valid API requests. required: false schema: type: - string - 'null' format: date-time - name: updated_to in: query description: >- Return records that were updated earlier than this date. If `updated_since` is used and this parameter is not specified, this value defaults to 7 days after `updated_since`. Must be an ISO 8601 UTC timestamp ending with 'Z' (e.g., `2024-07-01T00:00:00Z`); required for valid API requests. required: false schema: type: - string - 'null' format: date-time - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Ada successfully processed the request content: application/json: schema: $ref: '#/components/schemas/ConversationsResponse' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/Errors' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Errors' '403': description: Authorization Error content: application/json: schema: $ref: '#/components/schemas/Errors' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Errors' '429': description: Too Many Requests content: application/json: schema: $ref: '#/components/schemas/Errors' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Errors' /v2/export/messages: get: operationId: get-messages summary: Return messages matching the parameters description: Returns a list of `message` objects along with a `next_page_uri` if applicable tags: - subpackage_messages parameters: - name: created_since in: query description: >- Return records that were created after this date. If `created_to` is not specified, only records within 7 days of this timestamp are returned. To retrieve data beyond that window, set `created_to` explicitly. Must be an ISO 8601 UTC timestamp ending with 'Z' (e.g., `2024-07-01T00:00:00Z`); required for valid API requests. required: true schema: type: string format: date-time - name: conversation_id in: query description: Return records with a `conversation_id` that matches this id required: false schema: type: - string - 'null' format: id - name: page_size in: query description: Number of records to return in response. The maximum and default is 10000, the minimum is 100. required: false schema: type: integer default: 10000 - name: created_to in: query description: >- Return records that were created earlier than this date. If not specified, this value defaults to 7 days after `created_since`. Must be an ISO 8601 UTC timestamp ending with 'Z' (e.g., `2024-07-01T00:00:00Z`); required for valid API requests. required: false schema: type: - string - 'null' format: date-time - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Ada successfully processed the request content: application/json: schema: $ref: '#/components/schemas/MessagesResponse' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/Errors' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Errors' '403': description: Authorization Error content: application/json: schema: $ref: '#/components/schemas/Errors' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Errors' '429': description: Too Many Requests content: application/json: schema: $ref: '#/components/schemas/Errors' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Errors' servers: - url: https://example.ada.support/api description: https://example.ada.support/api components: schemas: ConversationCsat: type: object properties: {} description: Object of customer satisfaction survey data for this conversation title: ConversationCsat ConversationMetavariables: type: object properties: {} description: Object of metavariables and their values active during this conversations title: ConversationMetavariables ConversationVariables: type: object properties: {} description: Object of autocapture and global variables and their values last active during this conversations title: ConversationVariables Conversation: type: object properties: _id: type: string description: Unique ID for the conversation record agent_id: type: array items: type: string description: The list of unique IDs for agents involved in the conversation agent_handle_time: type: number format: double description: Time taken for a human agent to handle a conversation in seconds agent_name: type: array items: type: string description: A list of names of the agents involved the conversation, corresponding to the agent IDs automated_resolution_classification: type: string description: Classification of either Resolved or Not Resolved for the conversation automated_resolution_classification_reason: type: string description: Explanation of the reason for the assigned automated_resolution_classification bot_handle_time: type: number format: double description: Time taken for the AI agent to handle a conversation in seconds browser: type: string description: The browser used by the chatter browser_version: type: string description: The version of the browser used by the chatter chatter_id: type: string description: Ada ID of the chatter having this conversation csat: $ref: '#/components/schemas/ConversationCsat' description: Object of customer satisfaction survey data for this conversation date_created: type: string format: date-time description: Date and time the record was created (UTC) date_updated: type: string format: date-time description: Last date and time the record was updated (UTC) device: type: string description: The device the chatter used, such as iphone, android, etc. end_user_id: type: - string - 'null' description: The End User ID used to identify the chatter profile in the conversation generated_topic_id: type: string description: The unique ID Ada associated with the generated conversation topic generated_topic_label: type: - string - 'null' description: The title of the generated conversation topic generated_topic_v2_id: type: - string - 'null' description: The unique ID Ada associated with the generated conversation topic using Topics V2 generated_topic_v2_title: type: - string - 'null' description: The title of the generated conversation topic using Topics V2 generated_topic_v2_desc: type: - string - 'null' description: The descrtiption of the generated conversation topic using Topics V2 generated_topic_v2_parent_id: type: - string - 'null' description: >- The unique ID Ada associated with the generated conversation topic's parent category topic. Null if topic has no parent category topic. inquiry_summary: type: string description: An automatically generated summary of the customer's inquiry is_engaged: type: boolean description: Whether the chatter engaged with the bot during this conversation is_escalated: type: boolean description: Whether the chatter escalated to a live agent during this conversation is_test_user: type: boolean description: Whether the conversation was started by a test user language: type: string description: The language the chatter used metavariables: $ref: '#/components/schemas/ConversationMetavariables' description: Object of metavariables and their values active during this conversations oauth_channel: type: string description: The channel used by Oauth platform: type: string description: Ada platform through which this conversation occurred record_last_updated: type: - string - 'null' format: date-time description: Date and time the record was uploaded to the API variables: $ref: '#/components/schemas/ConversationVariables' description: Object of autocapture and global variables and their values last active during this conversations title: Conversation ConversationsResponseMeta: type: object properties: next_page_uri: type: - string - 'null' description: Link to the next page of results matching the query title: ConversationsResponseMeta ConversationsResponse: type: object properties: items: type: array items: $ref: '#/components/schemas/Conversation' description: Records returned from the query meta: $ref: '#/components/schemas/ConversationsResponseMeta' title: ConversationsResponse ErrorsErrorsItems: type: object properties: type: type: string description: The error type message: type: string description: The error message details: type: - string - 'null' description: Extra information about the error required: - type - message title: ErrorsErrorsItems Errors: type: object properties: errors: type: array items: $ref: '#/components/schemas/ErrorsErrorsItems' description: A list of errors required: - errors title: Errors MessageMessageData: type: object properties: {} description: Data associated with this message title: MessageMessageData Message: type: object properties: _id: type: string description: Unique ID for the message record answer_id: type: - string - 'null' description: >- Internal ID of the answer (response) that triggered this message. Null if the message was not sent by an Ada bot, and None if it was sent by a generative bot. answer_title: type: - string - 'null' description: >- Title of the answer (response) that triggered this message. Null if the message was not sent by an Ada bot, or if it was sent by a generative bot. chatter_id: type: - string - 'null' description: Internal ID of the chatter who sent this message. Corresponds to the `_id` field of Chatter objects. conversation_id: type: string description: >- Internal ID of the conversation in which this message was sent. Corresponds to the `_id` field of Conversation objects. date_created: type: string format: date-time description: Time the record was created (UTC) link_was_clicked: type: - boolean - 'null' description: Indicates if the link in the answer (response) was clicked message_data: $ref: '#/components/schemas/MessageMessageData' description: Data associated with this message recipient: type: string description: Recipient of this message record_last_updated: type: string format: date-time description: Date and time the record was uploaded to the API (UTC) review: type: integer description: Rating given to this answer by the chatter sender: type: string description: Sender of this message in_response_to: type: string description: >- Internal ID of the message that this message is in response to. None if the message is not in response to another message. title: Message MessagesResponseMeta: type: object properties: next_page_uri: type: - string - 'null' description: Link to the next page of results matching the query title: MessagesResponseMeta MessagesResponse: type: object properties: items: type: array items: $ref: '#/components/schemas/Message' description: Records returned from the query meta: $ref: '#/components/schemas/MessagesResponseMeta' title: MessagesResponse securitySchemes: bearerAuth: type: http scheme: bearer