openapi: 3.1.0 info: title: Data Export (v1.4) version: 1.0.0 paths: /data_api/v1.4/conversations: get: operationId: return-conversations-matching-the-parameters summary: Return conversations matching the parameters description: Returns a list of `conversation` objects along with a status message and `next_page_uri` if applicable. tags: - subpackage_conversations parameters: - name: created_since in: query description: >- Return records that were created after this date. Note that `updated_since` and `created_since` are mutually exclusive, so you must only use one in a request. Must be an ISO 8601 UTC timestamp ending with 'Z' (e.g., `2024-07-01T00:00:00Z`); required for valid API requests. required: false schema: type: string format: date-time - name: updated_since in: query description: >- Return records that were updated after this date. Note that `updated_since` and `created_since` are mutually exclusive, so you must only use one in a request. Must be an ISO 8601 UTC timestamp ending with 'Z' (e.g., `2024-07-01T00:00:00Z`); required for valid API requests. required: false schema: type: string format: date-time - name: page_size in: query description: Number of records to return in response. The maximum and default is 10000, the minimum is 100. required: false schema: type: integer default: 10000 - name: created_to in: query description: >- Return records that were created earlier than this date. If `created_since` is used and this parameter is not specified, this value defaults to 7 days after `created_since`. required: false schema: type: - string - 'null' format: date-time - name: updated_to in: query description: >- Return records that were updated earlier than this date. If `updated_since` is used and this parameter is not specified, this value defaults to 7 days after `updated_since`. required: false schema: type: - string - 'null' format: date-time - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Ada successfully processed the request. content: application/json: schema: $ref: '#/components/schemas/ConversationsResponse' '400': description: Incorrect query. content: application/json: schema: description: Any type '408': description: Database query timed out. content: application/json: schema: description: Any type '422': description: Invalid arguments or missing data for a required field. content: application/json: schema: description: Any type '429': description: Requests are within 1 s of each other. content: application/json: schema: description: Any type '500': description: Request timed out or there was a database error. content: application/json: schema: description: Any type '502': description: Nginx gateway issue on Ada's servers. content: application/json: schema: description: Any type '503': description: Server temporarily unable to handle the request. content: application/json: schema: description: Any type '504': description: Temporary infrastructure error on Ada's servers. content: application/json: schema: description: Any type /data_api/v1.4/messages: get: operationId: return-messages-matching-the-parameters summary: Return messages matching the parameters description: Returns a list of `message` objects along with a status message and `next_page_uri` if applicable. tags: - subpackage_messages parameters: - name: created_since in: query description: >- Return records that were created after this date. 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' - 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: Incorrect query. content: application/json: schema: description: Any type '408': description: Database query timed out. content: application/json: schema: description: Any type '422': description: Invalid arguments or missing data for a required field. content: application/json: schema: description: Any type '429': description: Requests are within 1 s of each other. content: application/json: schema: description: Any type '500': description: Request timed out or there was a database error. content: application/json: schema: description: Any type '502': description: Nginx gateway issue on Ada's servers. content: application/json: schema: description: Any type '503': description: Server temporarily unable to handle the request. content: application/json: schema: description: Any type '504': description: Temporary infrastructure error on Ada's servers. content: application/json: schema: description: Any type servers: - url: https://example.ada.support description: https://example.ada.support/ 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_name: type: array items: type: string description: A list of names of the agents involved the conversation, corresponding to the agent IDs agent_handle_time: type: number format: double description: Time taken for a human agent to handle a conversation in seconds 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 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 description: The title of the generated conversation topic generated_topic_v2_id: type: string description: The unique ID Ada associated with the generated conversation topic using Topics V2 generated_topic_v2_title: type: string description: The title of the generated conversation topic using Topics V2 generated_topic_v2_desc: type: string description: The descrtiption of the generated conversation topic using Topics V2 generated_topic_v2_parent_id: type: string 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 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 ConversationsResponse: type: object properties: message: type: string description: Request status message data: type: array items: $ref: '#/components/schemas/Conversation' description: Records returned from the query next_page_uri: type: string description: Relative link to the next page of results matching the query title: ConversationsResponse 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 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 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 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 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 MessagesResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/Message' description: Records returned from the query message: type: string description: Request status message next_page_uri: type: string description: Relative link to the next page of results matching the query title: MessagesResponse securitySchemes: bearerAuth: type: http scheme: bearer