{ "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" }, "last_agent_id": { "description": "The unique ID of the agent who most recently handled the conversation (latest activity timestamp). Null when no agent was assigned. Populated only for clients on the generative export path.", "examples": [ "619d95c0c063a5bf2b1efb7c" ], "type": "string" }, "last_agent_name": { "description": "The name of the agent who most recently handled the conversation, corresponding to last_agent_id. Null when no agent was assigned. Populated only for clients on the generative export path.", "examples": [ "Ada Lovelace" ], "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" ] }, "used_coaching": { "type": "array", "description": "Coaching events that were applied during the conversation. Each entry includes the coaching applied event id, entity_name, coaching_type, coaching_instructions, and coaching_intent. Returns an empty array when no coaching was applied.", "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "entity_name": { "type": [ "string", "null" ] }, "coaching_type": { "type": [ "string", "null" ] }, "coaching_instructions": { "type": [ "string", "null" ] }, "coaching_intent": { "type": [ "string", "null" ] } } } }, "used_articles": { "type": "array", "description": "Knowledge articles that were referenced during the conversation. Each entry includes the article id, name, url, and source. Returns an empty array when no articles were referenced.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] } } } }, "used_playbooks": { "type": "array", "description": "Playbooks that were invoked during the conversation. Each entry includes the playbook id, name, playbook_execution_id, and outcome_status. Returns an empty array when no Playbooks were invoked.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "playbook_execution_id": { "type": [ "string", "null" ] }, "outcome_status": { "type": [ "string", "null" ] } } } }, "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": { "data": { "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", "last_agent_id": "619d95c0c063a5bf2b1efb7c", "last_agent_name": "Ada Lovelace", "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": { "data": { "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": "10 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": "" } ] }