{ "openapi": "3.1.0", "info": { "title": "Data Export API", "version": "2" }, "servers": [ { "url": "https://example.ada.support/api" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "x-fern-bearer": { "name": "apiKey", "env": "ADA_API_KEY" } } }, "schemas": { "Conversation": { "type": "object", "properties": { "_id": { "type": "string", "description": "Unique ID for the conversation record", "examples": [ "5d8a7d080afd19b55945c8ab" ] }, "agent_id": { "description": "The list of unique IDs for agents involved in the conversation", "examples": [ [ "619d95c0c063a5bf2b1efb7c" ] ], "items": { "type": "string" }, "type": "array" }, "agent_handle_time": { "type": "number", "description": "Time taken for a human agent to handle a conversation in seconds", "examples": [ 4 ] }, "agent_name": { "description": "A list of names of the agents involved the conversation, corresponding to the agent IDs", "examples": [ [ "Ada Lovelace" ] ], "items": { "type": "string" }, "type": "array" }, "automated_resolution_classification": { "description": "Classification of either Resolved or Not Resolved for the conversation", "examples": [ "Resolved" ], "type": "string" }, "automated_resolution_classification_reason": { "description": "Explanation of the reason for the assigned automated_resolution_classification", "examples": [ "The bot provided a detailed step-by-step guide on how to disable auto deposits, both on the mobile app and the web version." ], "type": "string" }, "bot_handle_time": { "type": "number", "description": "Time taken for the AI agent to handle a conversation in seconds", "examples": [ 4 ] }, "browser": { "description": "The browser used by the chatter", "examples": [ "chrome" ], "type": "string" }, "browser_version": { "description": "The version of the browser used by the chatter", "examples": [ "95.0.4638.69" ], "type": "string" }, "chatter_id": { "type": "string", "description": "Ada ID of the chatter having this conversation", "examples": [ "5dbaef7283d791f585563d84" ] }, "classifications": { "type": "array", "description": "Topic and Intent classifications for this conversation. Returns an empty array when the conversation has no classifications.", "items": { "type": "object", "properties": { "topic_id": { "type": "string", "description": "Ada ID of the classified Topic" }, "topic_name": { "type": "string", "description": "Name of the classified Topic" }, "intents": { "type": "array", "description": "Intents classified within this Topic", "items": { "type": "object", "properties": { "intent_id": { "type": "string", "description": "Ada ID of the classified Intent" }, "intent_name": { "type": "string", "description": "Name of the classified Intent" }, "status": { "type": "string", "description": "Status of the Intent (for example, active)" } } } } } }, "examples": [ [ { "topic_id": "654952d3e90767ff49713fb1", "topic_name": "Billing", "intents": [ { "intent_id": "654952d3e90767ff49713fc2", "intent_name": "Dispute a charge", "status": "active" } ] } ] ] }, "csat": { "type": "object", "description": "Object of customer satisfaction survey data for this conversation", "examples": [ { "comment": null, "feedback": null, "is_positive": false, "resolved": null, "score": 3, "style": "EMOJI", "survey_type": "end_chat", "customer_effort_score": 4, "ces_max": 5, "net_promoter_score": 8 } ] }, "date_created": { "type": "string", "format": "date-time", "description": "Date and time the record was created (UTC)", "examples": [ "2019-10-31T14:28:02" ] }, "date_updated": { "type": "string", "format": "date-time", "description": "Last date and time the record was updated (UTC)", "examples": [ "2019-10-31T14:28:02" ] }, "device": { "description": "The device the chatter used, such as iphone, android, etc.", "examples": [ "macos" ], "type": "string" }, "end_user_id": { "description": "The End User ID used to identify the chatter profile in the conversation", "examples": [ "619d95c0c063a5bf2b1efb64e" ], "type": [ "string", "null" ] }, "generated_topic_id": { "description": "The unique ID Ada associated with the generated conversation topic", "examples": [ "654952d3e90767ff49713fbf" ], "type": "string" }, "generated_topic_label": { "description": "The title of the generated conversation topic", "examples": [ "Billing Inquiries" ], "type": [ "string", "null" ] }, "generated_topic_v2_id": { "description": "The unique ID Ada associated with the generated conversation topic using Topics V2", "examples": [ "654952d3e90767ff49713fb1" ], "type": [ "string", "null" ] }, "generated_topic_v2_title": { "description": "The title of the generated conversation topic using Topics V2", "examples": [ "Password Reset Inquiries" ], "type": [ "string", "null" ] }, "generated_topic_v2_desc": { "description": "The descrtiption of the generated conversation topic using Topics V2", "examples": [ "All conversations regarding resetting passwords" ], "type": [ "string", "null" ] }, "generated_topic_v2_parent_id": { "description": "The unique ID Ada associated with the generated conversation topic's parent category topic. Null if topic has no parent category topic.", "examples": [ "654952d3e90767ff49713fb2" ], "type": [ "string", "null" ] }, "inquiry_summary": { "description": "An automatically generated summary of the customer's inquiry", "examples": [ "The customer wanted to know how to temporarily disable auto deposits." ], "type": "string" }, "is_engaged": { "type": "boolean", "description": "Whether the chatter engaged with the bot during this conversation", "examples": [ true ] }, "is_escalated": { "type": "boolean", "description": "Whether the chatter escalated to a live agent during this conversation", "examples": [ false ] }, "is_test_user": { "description": "Whether the conversation was started by a test user", "examples": [ false ], "type": "boolean" }, "language": { "description": "The language the chatter used", "examples": [ "en" ], "type": "string" }, "metavariables": { "type": "object", "description": "Object of metavariables and their values active during this conversations", "examples": [ { "browser": "chrome", "language": "en" } ] }, "oauth_channel": { "description": "The channel used by Oauth", "examples": [ "sms" ], "type": "string" }, "platform": { "description": "Ada platform through which this conversation occurred", "examples": [ "chat" ], "type": "string" }, "record_last_updated": { "type": [ "string", "null" ], "format": "date-time", "description": "Date and time the record was uploaded to the API", "examples": [ "2019-10-31T14:28:02.865000+00:00" ] }, "variables": { "type": "object", "description": "Object of autocapture and global variables and their values last active during this conversations", "examples": [ { "account_number": "1234" } ] } } }, "ConversationsResponse": { "type": "object", "properties": { "items": { "description": "Records returned from the query", "type": "array", "items": { "$ref": "#/components/schemas/Conversation" }, "examples": [ { "_id": "5d8a7d080afd19b55945c8ab", "agent_id": [ "619d95c0c063a5bf2b1efb7c" ], "agent_name": [ "Ada Lovelace" ], "agent_handle_time": 4, "automated_resolution_classification": "Resolved", "automated_resolution_classification_reason": "The bot provided a detailed step-by-step guide on how to disable auto deposits", "bot_handle_time": 4, "browser": "chrome", "browser_version": "95.0.4638.69", "chatter_id": "5dbaef7283d791f585563d84", "classifications": [ { "topic_id": "654952d3e90767ff49713fb1", "topic_name": "Billing", "intents": [ { "intent_id": "654952d3e90767ff49713fc2", "intent_name": "Dispute a charge", "status": "active" } ] } ], "csat": { "comment": null, "feedback": null, "is_positive": false, "resolved": null, "score": 3, "style": "EMOJI", "survey_type": "end_chat", "customer_effort_score": 4, "ces_max": 5, "net_promoter_score": 8 }, "date_created": "2019-10-31T14:28:02", "date_updated": "2019-10-31T14:29:02", "device": "macos", "end_user_id": "619d95c0c063a5bf2b1efb64e", "generated_topic_id": "654952d3e90767ff49713fbf", "generated_topic_label": "Billing Inquiries", "generated_topic_v2_id": "654952d3e90767ff49713fb1", "generated_topic_v2_title": "Password Reset Inquiries", "generated_topic_v2_desc": "All conversations regarding resetting passwords", "generated_topic_v2_parent_id": "654952d3e90767ff49713fb2", "inquiry_summary": "The customer wanted to know how to temporarily disable auto deposits", "is_engaged": true, "is_escalated": false, "is_test_user": false, "language": "en", "metavariables": { "browser": "chrome", "language": "en" }, "oauth_channel": "sms", "platform": "chat", "record_last_updated": null, "variables": { "account_number": "1234" } } ] }, "meta": { "type": "object", "properties": { "next_page_uri": { "type": [ "string", "null" ], "description": "Link to the next page of results matching the query", "examples": [ "https://example.ada.support/api/v2/export/conversations?created_since=2023-07-08T06%3A01%3A39%2B00%3A00&created_to=2023-07-22T00%3A00%3A00%2B00%3A00" ] } }, "examples": [ { "next_page_uri": "https://example.ada.support/api/v2/export/conversations?created_since=2023-07-08T06%3A01%3A39%2B00%3A00&created_to=2023-07-22T00%3A00%3A00%2B00%3A00" } ] } } }, "Message": { "type": "object", "properties": { "_id": { "type": "string", "description": "Unique ID for the message record", "examples": [ "5d8a7d080afd19b55945c8ab" ] }, "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.", "examples": [ "6392e0f865ba38041ddd5966" ] }, "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.", "examples": [ "Greeting" ] }, "chatter_id": { "type": [ "string", "null" ], "description": "Internal ID of the chatter who sent this message. Corresponds to the `_id` field of Chatter objects.", "examples": [ "6009dd3c81dfae3a4e990acb" ] }, "conversation_id": { "type": "string", "description": "Internal ID of the conversation in which this message was sent. Corresponds to the `_id` field of Conversation objects.", "examples": [ "5dba43ebedb828146bc871b6" ] }, "date_created": { "type": "string", "format": "date-time", "description": "Time the record was created (UTC)", "examples": [ "2019-10-31T14:28:02.865000+00:00" ] }, "link_was_clicked": { "type": [ "boolean", "null" ], "description": "Indicates if the link in the answer (response) was clicked", "examples": [ false ] }, "message_data": { "type": "object", "description": "Data associated with this message", "examples": [ { "_type": "greeting", "external_chat_id": "", "reviewable_message": false } ] }, "recipient": { "type": "string", "description": "Recipient of this message", "examples": [ "ada" ] }, "record_last_updated": { "type": "string", "format": "date-time", "description": "Date and time the record was uploaded to the API (UTC)", "examples": [ "2019-10-31T14:28:02.865000+00:00" ] }, "review": { "type": "integer", "format": "int32", "description": "Rating given to this answer by the chatter", "minimum": 0, "maximum": 5, "examples": [ 0 ] }, "sender": { "type": "string", "description": "Sender of this message", "examples": [ "b9e51eae-5449-4a46-b6ce-aef2dcb4e067" ] }, "in_response_to": { "description": "Internal ID of the message that this message is in response to. None if the message is not in response to another message.", "type": "string", "examples": [ "6392e0f865ba38041ddd5966" ] } } }, "MessagesResponse": { "type": "object", "properties": { "items": { "description": "Records returned from the query", "type": "array", "items": { "$ref": "#/components/schemas/Message" }, "examples": [ { "_id": "5d8a7d080afd19b55945c8ab", "answer_id": "6392e0f865ba38041ddd5966", "answer_title": "Greeting", "chatter_id": "6009dd3c81dfae3a4e990acb", "conversation_id": "5dba43ebedb828146bc871b6", "date_created": "2019-10-31T14:28:02.865000+00:00", "link_was_clicked": false, "message_data": { "_type": "greeting", "external_chat_id": "", "reviewable_message": false }, "recipient": "ada", "record_last_updated": "2019-10-31T14:28:02.865000+00:00", "review": 0, "sender": "b9e51eae-5449-4a46-b6ce-aef2dcb4e067", "in_response_to": "6392e0f865ba38041ddd5966" } ] }, "meta": { "type": "object", "properties": { "next_page_uri": { "type": [ "string", "null" ], "description": "Link to the next page of results matching the query", "examples": [ "https://example.ada.support/api/v2/export/messages?created_since=2023-07-01T14%3A01%3A16.257000%2B00%3A00&created_to=2023-07-22T00%3A00%3A00%2B00%3A00" ] } }, "examples": [ { "next_page_uri": "https://example.ada.support/api/v2/export/messages?created_since=2023-07-01T14%3A01%3A16.257000%2B00%3A00&created_to=2023-07-22T00%3A00%3A00%2B00%3A00" } ] } } }, "Errors": { "type": "object", "properties": { "errors": { "description": "A list of errors", "type": [ "array" ], "items": { "type": "object", "properties": { "type": { "description": "The error type", "type": [ "string" ], "examples": [ "unauthorized" ] }, "message": { "description": "The error message", "type": [ "string" ], "examples": [ { "401 Unauthorized": "The server could not verify that you are authorized to access the URL requested" } ] }, "details": { "description": "Extra information about the error", "type": [ "string", "null" ], "examples": [ "The requested resource with id was not found" ] } }, "examples": [ { "type": "resource_not_found", "message": "The requested resource was not found", "details": "The requested resource with id 123456abcdef was not found" } ], "required": [ "type", "message" ] }, "examples": [ { "errors": [ { "type": "resource_not_found", "message": "The requested resource was not found", "details": "The requested resource with id 123456abcdef was not found" } ] } ] } }, "required": [ "errors" ] } }, "examples": { "AuthorizationError": { "value": { "errors": [ { "type": "authorization_error", "message": "You are not authorized to access this resource", "details": "You are not authorized to access this resource" } ] } }, "BadRequestError": { "value": { "errors": [ { "type": "bad_request", "message": "Invalid request", "details": "{'profile': {'system_properties': ['Unknown field.']}}" } ] } }, "DuplicateResourceError": { "value": { "errors": [ { "type": "duplicate_resource", "message": "Duplicate resource", "details": "A resource with the same id already exists." } ] } }, "NotFoundError": { "value": { "errors": [ { "type": "resource_not_found", "message": "Resource not found", "details": "The requested resource with id 5f7e0e2c1e7c7e000f0f9c3a was not found" } ] } }, "ClientNotFoundError": { "value": { "errors": [ { "type": "resource_not_found", "message": "Sorry, no client 'client_name' exists", "details": null } ] } }, "UnauthorizedError": { "value": { "errors": [ { "type": "unauthorized", "message": "You are not authorized to access this resource", "details": "You are not authorized to access this resource" } ] } }, "ContentTooLargeError": { "value": { "errors": [ { "type": "content_too_large", "message": "Content too large", "details": "Maximum request size of 4.0 MB exceeded. Content length: 5.0 MB" } ] } }, "UnprocessableContentError": { "value": { "errors": [ { "type": "unprocessable_content", "message": "Unprocessable content", "details": "The request was well-formed but was unable to be followed due to semantic errors" } ] } }, "TooManyRequestsError": { "value": { "errors": [ { "type": "rate_limit_exceeded", "message": "Rate limit exceeded", "details": "50 requests allowed per second" } ] } }, "InternalServerError": { "value": { "errors": [ { "type": "internal_server_error", "message": "An unknown error occurred", "details": "An unknown error occurred. error_id: 91d435a7-e0b4-4c56-a097-8907e9ed851e" } ] } } } }, "paths": { "/v2/export/conversations": { "get": { "operationId": "getConversations", "summary": "Return conversations matching the parameters", "description": "Returns a list of `conversation` objects along with a `next_page_uri` if applicable", "tags": [ "Conversations" ], "parameters": [ { "in": "query", "name": "created_since", "required": false, "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.", "schema": { "type": "string", "format": "date-time", "examples": [ "2023-07-03T00:00:00Z" ] } }, { "in": "query", "name": "updated_since", "required": false, "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.", "schema": { "type": "string", "format": "date-time", "examples": [ "2023-07-03T00:00:00Z" ] } }, { "in": "query", "name": "page_size", "required": false, "description": "Number of records to return in response. The maximum and default is 10000, the minimum is 100.", "schema": { "type": "integer", "format": "int32", "default": 10000, "minimum": 100, "maximum": 10000, "examples": [ 10000 ] } }, { "in": "query", "name": "created_to", "required": false, "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.", "schema": { "type": [ "string", "null" ], "format": "date-time", "examples": [ "2023-07-18T00:00:00Z" ] } }, { "in": "query", "name": "updated_to", "required": false, "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.", "schema": { "type": [ "string", "null" ], "format": "date-time", "examples": [ "2023-07-18T00:00:00Z" ] } } ], "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" }, "examples": { "BadRequestError": { "$ref": "#/components/examples/BadRequestError" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" }, "examples": { "UnauthorizedError": { "$ref": "#/components/examples/UnauthorizedError" } } } } }, "403": { "description": "Authorization Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" }, "examples": { "UnauthorizedError": { "$ref": "#/components/examples/AuthorizationError" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" }, "examples": { "BadRequestError": { "$ref": "#/components/examples/ClientNotFoundError" } } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" }, "examples": { "TooManyRequestsError": { "$ref": "#/components/examples/TooManyRequestsError" } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" }, "examples": { "InternalServerError": { "$ref": "#/components/examples/InternalServerError" } } } } } } } }, "/v2/export/messages": { "get": { "operationId": "getMessages", "summary": "Return messages matching the parameters", "description": "Returns a list of `message` objects along with a `next_page_uri` if applicable", "tags": [ "Messages" ], "parameters": [ { "in": "query", "name": "created_since", "required": true, "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.", "schema": { "type": "string", "format": "date-time", "examples": [ "2023-07-03T00:00:00Z" ] } }, { "in": "query", "name": "conversation_id", "required": false, "description": "Return records with a `conversation_id` that matches this id", "schema": { "type": [ "string", "null" ], "format": "id", "examples": [ "60bd36dc8f17071b5c5bec12" ] } }, { "in": "query", "name": "page_size", "required": false, "description": "Number of records to return in response. The maximum and default is 10000, the minimum is 100.", "schema": { "type": "integer", "format": "int32", "default": 10000, "minimum": 100, "maximum": 10000, "examples": [ 10000 ] } }, { "in": "query", "name": "created_to", "required": false, "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.", "schema": { "type": [ "string", "null" ], "format": "date-time", "examples": [ "2023-07-03T00:00:00Z" ] } } ], "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" }, "examples": { "BadRequestError": { "$ref": "#/components/examples/BadRequestError" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" }, "examples": { "UnauthorizedError": { "$ref": "#/components/examples/UnauthorizedError" } } } } }, "403": { "description": "Authorization Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" }, "examples": { "UnauthorizedError": { "$ref": "#/components/examples/AuthorizationError" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" }, "examples": { "BadRequestError": { "$ref": "#/components/examples/ClientNotFoundError" } } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" }, "examples": { "TooManyRequestsError": { "$ref": "#/components/examples/TooManyRequestsError" } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" }, "examples": { "InternalServerError": { "$ref": "#/components/examples/InternalServerError" } } } } } } } } }, "tags": [ { "name": "data_export_conversations", "description": "" }, { "name": "data_export_messages", "description": "" } ] }