{"openapi":"3.1.0","info":{"title":"Chat Data API Schema Guide","description":" # Introduction\n\n Welcome to Chat Data Guide and API Reference, Version 2.0.0!\n\n Chat Data is a platform that allows you to create AI chatbots using your own data or data provided by the service.\n It offers the following features:\n\n **Integration**: You can integrate a chat widget or iframe on your website by providing your own documents (.pdf, .docx, .html, .txt), website links, plain text or Q&As.\n \n **Language Compatibility**: Chat Data is designed to work with multiple languages. You can use it with sources in any language and pose questions in any language as well.\n \n **User Analysis**: The owner of the chatbot has the ability to monitor user activities on the chatbot. They can analyze the geographic distribution of users and track user activity.\n \n **Customer Information Gathering**: When customers express interest in the owner's products or services, the chatbot can collect customer information. This allows the owner to gather valuable data for marketing and customer relationship management purposes.\n \n **Email Notifications**: Chatbot owners can receive daily email notifications containing all chatbot conversations and collected leads.\n\n This reference serves as a comprehensive guide to the [Chat Data](https://www.chat-data.com/) system and\n its Version 2.0.0 API. Here, you'll find detailed information on the objects and\n endpoints used in the API. We greatly value your feedback. If you notice any\n missing or inaccurate information, please don't hesitate to email us at admin@chat-data.com.\n\n > To leverage Chat Data's API capabilities, you'll need an API key. API keys can be\n   created by subscribing to an appropriate membership plan on [chat-data.com](https://www.chat-data.com/pricing).\n\n ## Conventions\n\n All API requests should be directed to the domain `api.chat-data.com`, and HTTPS is mandatory for all interactions.\n\n The Chat Data API adheres to RESTful conventions where applicable, utilizing standard HTTP methods such as GET, POST, PUT, and DELETE. Request and response payloads are encoded in JSON format.\n\n HTTP status codes are used in accordance with industry standards. Successful requests return a 200 OK response, while failed requests produce 4xx or 5xx error codes.\n\n If you have any questions or need further assistance, please don't hesitate to reach out to our [support team](mailto:admin@chat-data.com).\n\n ## JSON conventions\n\n * Response body of success requests is generally as follows:\n\n     ```json\n     {\n       \"status\": \"success\",\n       \"chatbotId\": \"6650f1c2a9e4b83d2c7a1f05\",\n       \"chatbotName\": \"Support Bot\",\n       ...\n     }\n     ```\n\n     * `status` is a common property.\n     * Depending on the API call, there may be other properties as well.\n * A failed response looks like this:\n\n     ```json\n     {\n         \"status\": \"error\",\n         \"message\": \"Error message\"\n     }\n     ```\n\n     * `status` and `message` are common properties.\n\n * Most property names are camelCase; webhook payloads and a few response fields are snake_case, as each operation documents.\n * Optional properties may be omitted or `null`; you can ignore them when they are not needed.\n\n ## Request limits\n\n To maintain a uniform developer experience for all API users, the Chat Data API enforces a rate limit of 600 requests per minute (RPM) per workspace. All API keys of the same workspace share that limit. When it is exceeded, the API responds with `429`, a `Retry-After` header and a message saying how many seconds to wait.\n\n ## Authentication\n\n Requests use the HTTP `Authorization` header to both authenticate and authorize operations. The Chat Data API accepts bearer tokens in this header. API keys can be managed on your [account](https://www.chat-data.com/account) page.\n\n ```curl\n curl https://api.chat-data.com/api/v2/get-chatbots -H \"Authorization: Bearer $CHAT_DATA_API_KEY\"\n ```\n\n There are two kinds of keys. Workspace keys can access every chatbot and resource in their workspace. Chatbot-scoped keys can access only the chatbot they were created for; operations that are not about a single chatbot (for example `create-chatbot` or `current-plan`) require a workspace key.\n\n **Please note**: keep your API keys confidential and never put them in client code, including browser HTML and mobile apps. Make API calls from your server.\n\n # Guides\n\n Setup guides (training data, Shopify, WordPress, WhatsApp, Slack, Discord, webhooks, white label and more) live in the [Chat Data cookbook](https://cookbook.chat-data.com/).\n\n # Chat Data RESTful API\n","version":"2.0.0","x-last-updated":"2026-10-14"},"servers":[{"url":"https://api.chat-data.com/api/v2"}],"paths":{"/create-chatbot":{"post":{"tags":["Chatbot Operations"],"summary":"Create and train a chatbot","description":"Create a chatbot using one of our medical chat models, your own uploaded data, or a custom model. `model` is required; a request without a valid `model` is rejected with a 400.\n\nAvailable models:\n- `custom-data-upload`: For training with your own data using OpenAI GPT models including `GPT 5.6 Sol`, `GPT 5.6 Terra`, and `GPT 5.6 Luna`; Anthropic Claude models including `Claude Opus 5` and `Claude Sonnet 5`; Google Gemini models including `Gemini 3.7 Flash` and `Gemini 3.5 Flash Lite`; plus earlier supported models.\n- `medical-chat-human`: For human medical questions\n- `medical-chat-vet`: For veterinary medical questions\n- `custom-model`: For using a custom model\n\nFor the `custom-data-upload` model, you can provide training data using `sourceText`, `urlsToScrape`, `products` or `qAndAs`. Other models do not use these fields, but `urlsToScrape` must still contain valid URLs and `products` must still be an array.\n\nFor the `custom-model` model, `customBackend` is required and `bearer` is optional. Chat Data sends a test request to the backend first and creates the chatbot only if the backend answers as expected.\n\nYou can poll the status of the training with `GET /chatbot/status/{chatbotId}` at an interval of 10 seconds. Training generally takes 1-2 minutes, depending on the length of the provided text or websites.\n\nNote: The training data is subject to character limits based on your plan.\n\nThis operation requires a workspace API key; chatbot-scoped keys get a 403.","operationId":"chatbotCreate","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatChatbotReq"}}},"required":true},"responses":{"200":{"description":"The chatbot was created. Training on the provided data runs in the background; poll `GET /chatbot/status/{chatbotId}` for progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrainChatbotSuccessRes"}}}},"400":{"description":"The chatbot could not be created. For example: the workspace has reached its chatbot limit, has no training characters left, `model` is missing or not one of the allowed values, a URL in `urlsToScrape` has no `http://` or `https://` scheme, `products` is not an array, the training data exceeds the per-chatbot character limit, or for `custom-model` the `customBackend` URL is missing or the backend did not respond as expected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Chatbots Limit is reached: 3/3 limit"}}}},"401":{"description":"Authentication failed (the `Authorization` header is missing or malformed, the API key does not exist, its workspace is unavailable or has no owner, or the plan does not include API access), or `model` is `custom-model` and the plan does not include custom models (`Custom model is unavailable in the current plan.`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"403":{"description":"The request used a chatbot-scoped API key. This operation needs a workspace key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"This operation requires a user-level API key, not a chatbot-specific key"}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}},"security":[{"HTTPBearer":[]}]}},"/retrain-chatbot":{"post":{"tags":["Chatbot Operations"],"summary":"Retrain an existing chatbot","description":"The Chatbot Retrain API enables you to retrain an existing chatbot. This API is applicable for chatbots with the `custom-data-upload` model. It allows you to update the chatbot's knowledge base with new information or remove existing data.\n\nYou can provide new training data through various methods:\n- Text data via `sourceText`\n- URLs to scrape via `urlsToScrape`\n- Product information via `products`\n- Q&A pairs via `qAndAs`\n\nYou can also remove specific knowledge chunks using the `deletes` array.\n\nNote: The amount of new data you can add is subject to character limits based on your plan.","operationId":"RetrainChatbot","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetrainChatbotReq"}}},"required":true},"responses":{"200":{"description":"The new data was accepted. Training runs in the background; poll `GET /chatbot/status/{chatbotId}` for progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrainChatbotSuccessRes"}}}},"400":{"description":"The chatbot could not be retrained. For example: `chatbotId` is missing, a URL in `urlsToScrape` has no `http://` or `https://` scheme, `products` or `deletes` is not an array, the chatbot does not use the `custom-data-upload` model, the training data exceeds the chatbot's character limit, or the workspace has no training characters left.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Please change the model of the current chatbot to custom-data-upload"}}}},"401":{"description":"Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"403":{"description":"The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Chatbot 6650f1c2a9e4b83d2c7a1f05 was not found in this API key's workspace. It may have been deleted or moved to another workspace."}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}},"security":[{"HTTPBearer":[]}]}},"/chatbot/status/{chatbotId}":{"get":{"tags":["Chatbot Operations"],"summary":"Get chatbot training status","description":"Get the current training progress of the chatbot.","operationId":"GetChatbotStatus","parameters":[{"required":true,"schema":{"title":"Chatbot ID","type":"string"},"name":"chatbotId","in":"path","description":"The unique identifier allocated to the chatbot."}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatbotStatusRes"}}}},"400":{"description":"An unexpected error occurred while processing the request; `message` contains the error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"}}}},"401":{"description":"Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"403":{"description":"The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Chatbot 6650f1c2a9e4b83d2c7a1f05 was not found in this API key's workspace. It may have been deleted or moved to another workspace."}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}},"security":[{"HTTPBearer":[]}]}},"/delete-chatbot/{chatbotId}":{"delete":{"tags":["Chatbot Operations"],"summary":"Delete a chatbot","description":"This API enables the deletion of a chatbot by specifying its ID. It removes the chatbot along with its associated data from the system, including training data, user monitoring data, conversations, leads information, etc. Exercise caution when using this deletion action, as all deleted sources are unrecoverable.","operationId":"chatbotDelete","parameters":[{"required":true,"schema":{"title":"Chatbot ID","type":"string"},"name":"chatbotId","in":"path","description":"The unique identifier allocated to the chatbot."}],"responses":{"200":{"description":"The deletion was processed. The response is `success` even when a deletion of the same chatbot is already in progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessStatus"}}}},"400":{"description":"An internal error occurred while checking the API key (for example its lookup or the rate limiter failed); `message` says why. A failed deletion itself is not reported: the response is still 200.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"}}}},"401":{"description":"Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"403":{"description":"The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Chatbot 6650f1c2a9e4b83d2c7a1f05 was not found in this API key's workspace. It may have been deleted or moved to another workspace."}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}},"security":[{"HTTPBearer":[]}]}},"/get-chatbots":{"get":{"tags":["Chatbot Operations"],"summary":"Get all chatbots","description":"Returns the chatbots the API key can reach, with related information: every chatbot in the workspace for a workspace key, or only its own chatbot for a chatbot-scoped key.","operationId":"GetAllChatbots","responses":{"200":{"description":"Successful response. With a chatbot-scoped key, `chatbots` contains only that key's chatbot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListOfChatbotsRes"}}}},"400":{"description":"An unexpected error occurred while processing the request; `message` contains the error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"}}}},"401":{"description":"Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"404":{"description":"The request used a chatbot-scoped key whose chatbot no longer exists in the key's workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Chatbot not found or access denied"}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}},"security":[{"HTTPBearer":[]}]}},"/get-chatbot/{chatbotId}":{"get":{"tags":["Chatbot Operations"],"summary":"Get a chatbot","description":"Returns the related information about a single chatbot. The returned chatbot schema is the same as in the `/get-chatbots` endpoint.","operationId":"GetChatbot","parameters":[{"required":true,"schema":{"title":"Chatbot ID","type":"string"},"name":"chatbotId","in":"path","description":"The unique identifier allocated to the chatbot."}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"title":"A single chatbot response","required":["status","chatbot"],"type":"object","properties":{"status":{"type":"string","enum":["success"]},"chatbot":{"$ref":"#/components/schemas/ChatbotObject","description":"A single chatbot with the related information."}}}}}},"400":{"description":"An unexpected error occurred while processing the request; `message` contains the error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"}}}},"401":{"description":"Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"403":{"description":"The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Chatbot 6650f1c2a9e4b83d2c7a1f05 was not found in this API key's workspace. It may have been deleted or moved to another workspace."}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}},"security":[{"HTTPBearer":[]}]}},"/update-chatbot-settings":{"post":{"tags":["Chatbot Operations"],"summary":"Update chatbot settings","description":"This API endpoint allows you to edit your chatbot. Only the fields you send are changed; fields set to `null` are ignored.","operationId":"UpdateChatbotSettings","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateChatbotSettingReq"}}},"required":true},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessStatus"}}}},"400":{"description":"The settings could not be saved. For example: `chatbotId` is missing, `visibility`, `baseModel` or `temperature` has an invalid value, `basePrompt` is empty or not a string, the base model is not allowed in a HIPAA workspace, or a value was rejected when saving.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"The temperature parameter should be in the range [0,1]."}}}},"401":{"description":"Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"403":{"description":"The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Chatbot 6650f1c2a9e4b83d2c7a1f05 was not found in this API key's workspace. It may have been deleted or moved to another workspace."}}}},"409":{"description":"Only when the request includes `baseModel`: the workspace is being reconfigured. Retry the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"This workspace is being reconfigured; please retry."}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}},"security":[{"HTTPBearer":[]}]}},"/update-white-label":{"post":{"tags":["Chatbot Operations"],"summary":"Update white-label settings","description":"This API endpoint allows you to update white label settings for your chatbot. Only the fields you send are changed.\n\n`showPowerby`, `powerbyText`, `company` and `companyUrl` require your [plan](/pricing) to include Remove Brand or Remove Label. `embeddingDomain` and `fromEmail` require Remove Brand. Sending a field your plan does not include returns a 403.","operationId":"UpdateWhiteLabel","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"chatbotId":{"type":"string","description":"The ID of the chatbot to update.","example":"6650f1c2a9e4b83d2c7a1f05"},"showPowerby":{"type":"boolean","description":"Whether to show the \"Powered by\" text.","example":false},"powerbyText":{"type":"string","description":"Custom \"Powered by\" text.","example":"Powered by Example Inc"},"company":{"type":"string","description":"Company name for white labeling.","example":"Example Inc"},"companyUrl":{"type":"string","description":"Company URL for white labeling.","example":"https://www.example.com"},"embeddingDomain":{"type":"string","description":"Custom domain for embedding the chatbot, with or without `https://`. Its DNS must be unused or already point to `www.chat-data.com`. The response lists the DNS records to add.","example":"chat.example.com"},"fromEmail":{"type":"string","description":"Custom sender address for emails to your users. The response lists the DNS records that verify its domain. Set it to `admin@chat-data.com` to go back to the default sender.","example":"support@example.com"}},"required":["chatbotId"]}}},"required":true},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","description":"Response status indicator.","example":"success"},"domainDnsRecords":{"type":"array","description":"DNS records required for custom domain setup. Only returned when `embeddingDomain` is provided.","items":{"type":"object","properties":{"type":{"type":"string","description":"Type of DNS record.","example":"cname"},"host":{"type":"string","description":"Hostname to configure.","example":"chat.example.com"},"data":{"type":"string","description":"Value for the DNS record.","example":"www.chat-data.com"},"status":{"type":"boolean","description":"Whether the DNS record is properly configured.","example":true}}},"example":[{"type":"cname","host":"_acme-challenge.chat.example.com","data":"chat.example.com.e7c5afd44f1a18fb.dcv.cloudflare.com","status":true},{"type":"cname","host":"chat.example.com","data":"www.chat-data.com","status":true}]},"emailDnsRecords":{"type":"array","description":"DNS records required for custom email setup. Only returned when `fromEmail` is provided.","items":{"type":"object","properties":{"type":{"type":"string","description":"Type of DNS record (for example CNAME or TXT).","example":"cname"},"host":{"type":"string","description":"Hostname to configure.","example":"k7q2m4._domainkey.example.com"},"data":{"type":"string","description":"Value for the DNS record.","example":"k7q2m4.dkim.amazonses.com"},"status":{"type":"boolean","description":"Whether the DNS record is properly configured.","example":true}}},"example":[{"type":"cname","host":"k7q2m4._domainkey.example.com","data":"k7q2m4.dkim.amazonses.com","status":true},{"type":"cname","host":"p3x8w1._domainkey.example.com","data":"p3x8w1.dkim.amazonses.com","status":true},{"type":"cname","host":"r9d5t6._domainkey.example.com","data":"r9d5t6.dkim.amazonses.com","status":true}]}}}}}},"400":{"description":"The settings could not be saved. For example: `embeddingDomain` starts with `http://` or `https://` but is not a valid URL, its DNS already points to another server, `fromEmail` is not a valid email address, or `fromEmail` uses a Chat Data domain.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Please provide a valid email address to send from."}}}},"401":{"description":"Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"403":{"description":"The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace. Also returned when the plan does not include the requested change: `You do not have permission to update white label settings. Please upgrade your plan to access these features.` for `showPowerby`, `powerbyText`, `company` or `companyUrl`, and `You do not have permission to customize domain or email settings. Please upgrade your plan to access these features.` for `embeddingDomain` or `fromEmail`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"You do not have permission to customize domain or email settings. Please upgrade your plan to access these features."}}}},"404":{"description":"`chatbotId` was not provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"No chatbot associated with the provided chatbotId=undefined was found for the user."}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute (wait the seconds in `Retry-After`), or it set up more than 20 new sender domains for `fromEmail` in the last hour. The sender-domain response also carries the wait in seconds as `retryAfter`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"500":{"description":"The sender-domain rate limiter for `fromEmail` is temporarily unavailable. This response is the server's default error page, not JSON."}},"security":[{"HTTPBearer":[]}]}},"/update-metrics-share":{"post":{"tags":["Chatbot Operations"],"summary":"Update analytics sharing","description":"This API endpoint allows you to configure analytics sharing settings for your chatbot. The response always contains the link of the public analytics dashboard. Setting `public` requires a [plan](/pricing) that includes sharing analytics. Only the fields you send are changed.","operationId":"UpdateMetricsShare","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"chatbotId":{"type":"string","description":"The ID of the chatbot to update.","example":"6650f1c2a9e4b83d2c7a1f05"},"public":{"type":"boolean","description":"Whether to make analytics publicly accessible.","example":true},"selected":{"type":"array","description":"List of graphs to display in the public analytics view.","items":{"type":"string","enum":["Overview","Credits Timeline","Messages Timeline","Live Chat Escalations Timeline","Email Consumption Timeline","SMS Consumption Timeline","Message Distribution by Hour","Topics","Chats","Conversations Ratings","Submitted Leads","Upvotes/DownVotes","Sentiments","Geographic Distribution"]},"example":["Overview","Messages Timeline","Topics"]}},"required":["chatbotId"]}}},"required":true},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","description":"Response status indicator.","example":"success"},"analyticsLink":{"type":"string","description":"URL of the public analytics dashboard.","example":"https://chat.example.com/analytics/n1GHt-Fw0EVmdEl73m1cWv2SLMnGZTSC1T3laTk_ce5sRBcMwr4ZOz8QEiXty82bCKdiXsP0oiYbf2m8-Qq3g2_uMaTcnFwpAvcOrVaCDl5lwsqdik6rZS3WJkbcxlrNRH7Br6TcoteQug28Jr5PpcjwMPgL6goV47eTgccupFAkDodqz4qTIlkqVlE"}}}}}},"400":{"description":"An item in `selected` is not one of the allowed graph names.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Invalid selection. All selected items must be from enums of Overview, Credits Timeline, Messages Timeline, Live Chat Escalations Timeline, Email Consumption Timeline, SMS Consumption Timeline, Message Distribution by Hour, Topics, Chats, Conversations Ratings, Submitted Leads, Upvotes/DownVotes, Sentiments, Geographic Distribution."}}}},"401":{"description":"Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"403":{"description":"The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace. Also returned when `public` is set and the plan does not include sharing analytics.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Your subscription plan does not support sharing analytics. Please upgrade to the Standard plan or above to enable this feature."}}}},"404":{"description":"`chatbotId` was not provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"No chatbot associated with the provided chatbotId=undefined was found for the user."}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}},"security":[{"HTTPBearer":[]}]}},"/add-webhook":{"post":{"tags":["Chatbot Operations"],"summary":"Add a webhook","description":"Add a webhook endpoint that receives real-time events from the chatbot: `chat`, `live-chat-escalation`, `lead-submission`, `user-online` or `user-offline`. Your plan must include webhooks. A chatbot can have up to 5 webhook endpoints; adding an event to an existing `url` subscribes that endpoint to one more event.\n\nThe [Webhooks](/api-reference/webhooks) page documents every event's body and how to verify deliveries. A `chat` event triggered by a `/chat` request with `skipCache: true` carries `regenerate: true` (the field is absent otherwise). A `live-chat-escalation` matches its `chat` event by `conversation_id`; a `lead-submission` has no `conversation_id`, so pass its `lead.uuid` as `leadId` to [Get conversations](/api-reference/get-conversations).","operationId":"AddWebhook","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddWebhookReq"}}},"required":true},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"title":"Success","required":["status"],"type":"object","properties":{"status":{"type":"string","enum":["success"]},"webhooks":{"type":"array","description":"The chatbot's webhooks after the change.","items":{"$ref":"#/components/schemas/WebhookPayload"}}}}}}},"400":{"description":"The webhook could not be added. For example: the plan does not include webhooks, `event` is not a supported event, `url` is not a valid http(s) URL or points to a placeholder or Chat Data host, `contentType` is not supported, `chatbotId` is missing, or the chatbot already has 5 webhook endpoints.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"The chatbot has already reached the webhook limit: 5 per chatbot."}}}},"401":{"description":"Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"403":{"description":"The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Chatbot 6650f1c2a9e4b83d2c7a1f05 was not found in this API key's workspace. It may have been deleted or moved to another workspace."}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}},"security":[{"HTTPBearer":[]}]}},"/delete-webhook":{"post":{"tags":["Chatbot Operations"],"summary":"Delete a webhook","description":"Delete the webhook registered with the given URL, together with all of its event subscriptions. The response lists the chatbot's remaining webhooks. If no webhook matches `url`, nothing is deleted and the response is still 200 with the unchanged list.","operationId":"DeleteWebhook","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/deleteWebhookReq"}}},"required":true},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"title":"Success","required":["status"],"type":"object","properties":{"status":{"type":"string","enum":["success"]},"webhooks":{"type":"array","description":"The chatbot's webhooks after the change.","items":{"$ref":"#/components/schemas/WebhookPayload"}}}}}}},"400":{"description":"`url` is missing or not a valid URL (`Please provide a valid url.`), `chatbotId` is missing, or an unexpected error occurred while saving.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Please provide a valid url."}}}},"401":{"description":"Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"403":{"description":"The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Chatbot 6650f1c2a9e4b83d2c7a1f05 was not found in this API key's workspace. It may have been deleted or moved to another workspace."}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}},"security":[{"HTTPBearer":[]}]}},"/upload-chatbot-profile-picture/{chatbotId}":{"post":{"tags":["Chatbot Operations"],"summary":"Upload a profile picture","description":"This API endpoint allows you to update the profile picture of your chatbot. The image is resized to 100×100 pixels.","operationId":"UpdateChatbotProfilePicture","parameters":[{"in":"path","name":"chatbotId","required":true,"schema":{"type":"string"},"description":"The unique identifier allocated to the chatbot."}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["image"],"properties":{"image":{"title":"Picture file","type":"string","format":"binary","description":"The profile picture to upload. It must be a square PNG, JPEG, GIF or WebP image of up to 1 MB.","example":"profile-picture.png"}}}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessStatus"}}}},"400":{"description":"The image was rejected: no `image` file was sent, it is not a PNG, JPEG, GIF or WebP image, it is not square, or it could not be processed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Uploaded image must be a square"}}}},"401":{"description":"Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"403":{"description":"The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Chatbot 6650f1c2a9e4b83d2c7a1f05 was not found in this API key's workspace. It may have been deleted or moved to another workspace."}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"500":{"description":"The image is larger than 1 MB, or it was sent under a field other than `image`. The upload is rejected before it reaches the handler, and the response is not JSON."}},"security":[{"HTTPBearer":[]}]}},"/delete-chatbot-profile-picture/{chatbotId}":{"delete":{"tags":["Chatbot Operations"],"summary":"Delete the profile picture","description":"Delete the chatbot's profile picture.","operationId":"DeleteChatbotProfilePicture","parameters":[{"required":true,"schema":{"title":"Chatbot ID","type":"string"},"name":"chatbotId","in":"path","description":"The unique identifier allocated to the chatbot."}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessStatus"}}}},"400":{"description":"An unexpected error occurred while processing the request; `message` contains the error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"}}}},"401":{"description":"Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"403":{"description":"The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Chatbot 6650f1c2a9e4b83d2c7a1f05 was not found in this API key's workspace. It may have been deleted or moved to another workspace."}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}},"security":[{"HTTPBearer":[]}]}},"/upload-chatbot-icon/{chatbotId}":{"post":{"tags":["Chatbot Operations"],"summary":"Upload a chat icon","description":"This API endpoint allows you to update the chat icon of your chatbot. The image is resized to 100×100 pixels.","operationId":"UpdateChatbotIconPicture","parameters":[{"in":"path","name":"chatbotId","required":true,"schema":{"type":"string"},"description":"The unique identifier allocated to the chatbot."}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["image"],"properties":{"image":{"title":"Picture file","type":"string","format":"binary","description":"The chat icon to upload. It must be a square PNG, JPEG, GIF or WebP image of up to 1 MB.","example":"chat-icon.png"}}}}}},"responses":{"200":{"description":"The request was processed. `status` is `success` when the icon was saved. If the image passed validation but could not be resized or saved, the response is still 200, with `status: error` and a `message`.","content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["success","error"]},"message":{"type":"string","description":"Why the icon could not be saved. Only present when `status` is `error`."}}},"example":{"status":"success"}}}},"400":{"description":"The image is not a PNG, JPEG, GIF or WebP image, or it is not square.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Unsupported image format. Use PNG, JPEG, GIF or WebP."}}}},"401":{"description":"Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"403":{"description":"The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Chatbot 6650f1c2a9e4b83d2c7a1f05 was not found in this API key's workspace. It may have been deleted or moved to another workspace."}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"500":{"description":"No `image` file was sent, the image is larger than 1 MB, or the file cannot be read as an image (corrupt or truncated). The response is not JSON."}},"security":[{"HTTPBearer":[]}]}},"/delete-chatbot-icon/{chatbotId}":{"delete":{"tags":["Chatbot Operations"],"summary":"Delete the chat icon","description":"Delete the chatbot's chat icon.","operationId":"DeleteChatbotIconPicture","parameters":[{"required":true,"schema":{"title":"Chatbot ID","type":"string"},"name":"chatbotId","in":"path","description":"The unique identifier allocated to the chatbot."}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessStatus"}}}},"400":{"description":"An unexpected error occurred while processing the request; `message` contains the error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"}}}},"401":{"description":"Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"403":{"description":"The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Chatbot 6650f1c2a9e4b83d2c7a1f05 was not found in this API key's workspace. It may have been deleted or moved to another workspace."}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}},"security":[{"HTTPBearer":[]}]}},"/get-confidence-score":{"post":{"tags":["Chatbot Operations"],"summary":"Get confidence scores","description":"This operation retrieves the confidence scores (defined as cosine similarity) of the related chunks used to generate answers. You can use it to obtain confidence scores before calling the `/chat` API endpoint, providing an estimate of the chatbot's ability to deliver high-quality answers based on the context. Chunks are cached based on the `messages` array, so subsequent calls to the `/chat` API with the same `messages` array will incur minimal latency in retrieving related vector embeddings from the database. Therefore, calling this API endpoint before `/chat` should not significantly impact overall chat performance.","operationId":"GetConfidenceScore","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendConfidenceScoreReq"}}},"required":true},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"title":"Confidence Score Information for Context Chunks","description":"When the chatbot uses `custom-model` or ignores its data source, the body is only `{ \"status\": \"success\", \"score\": 0 }`.","required":["status"],"type":"object","properties":{"status":{"type":"string","enum":["success"]},"score":{"type":"number","enum":[0],"description":"Only returned, instead of the other fields, when the chatbot uses `custom-model` or `ignoreDataSource` is on. Always 0."},"averageScore":{"type":"number","example":0.8,"minimum":0,"maximum":1,"description":"The average confidence score of all context chunks. Confidence score is defined as cosine similarity, and only context chunks with positive cosine similarities are included."},"scoresArray":{"type":"array","items":{"type":"number","minimum":0,"maximum":1,"description":"Confidence score (cosine similarity) of the associated context chunk."},"description":"The confidence score of each context chunk used to generate the answer.","example":[0.85,0.75]},"sources":{"type":"array","description":"The context chunks used to generate the answer, with their sources.","items":{"required":["score","type"],"type":"object","properties":{"score":{"type":"number","minimum":0,"maximum":1,"description":"Confidence score (cosine similarity) of the associated context chunk."},"question":{"type":"string","description":"The question text if this is a 'q&a' type source."},"answer":{"type":"string","description":"The answer text if this is a 'q&a' type source."},"url":{"type":"string","description":"The URL of the website if this is a 'website' type source."},"title":{"type":"string","description":"The title of the document or website."},"text":{"type":"string","description":"Original chunk text used to generate the answer in the `custom-data-upload` model chatbot. Text is not truncated for chatbots based on the `custom-data-upload` model."},"truncatedText":{"type":"string","description":"Truncated text from the `medical-chat-human` or `medical-chat-vet` model used to generate the answer. To protect the intellectual property of our database, only the first 100 characters are shown."},"table":{"type":"string","description":"Text representation of the table."},"topic":{"type":"string","description":"The topic of the medical chat model text."},"subtopic":{"type":"string","description":"The subtopic of the medical chat model text."},"type":{"type":"string","description":"The document type of the source."}}},"example":[{"score":0.85,"url":"https://www.chat-data.com/","title":"Chat Data | Build AI chatbots with your own data","text":"Chat Data lets you build an AI chatbot trained on your own documents, websites and Q&As, then embed it on your site or connect it to WhatsApp, Slack, Discord and more.","type":"website"},{"score":0.75,"question":"How do I train my chatbot?","answer":"Add documents, website links, plain text or Q&As as sources, then retrain the chatbot. Training usually finishes in 1-2 minutes.","type":"q&a"}]},"embeddingText":{"type":"string","example":"How does Chat Data work?","description":"The actual text used to generate the embedding. To take the chat history into account, more than the last query may be used to generate `embeddingText`, depending on the `messages` array."}}},"example":{"status":"success","averageScore":0.8,"scoresArray":[0.85,0.75],"sources":[{"score":0.85,"url":"https://www.chat-data.com/","title":"Chat Data | Build AI chatbots with your own data","text":"Chat Data lets you build an AI chatbot trained on your own documents, websites and Q&As, then embed it on your site or connect it to WhatsApp, Slack, Discord and more.","type":"website"},{"score":0.75,"question":"How do I train my chatbot?","answer":"Add documents, website links, plain text or Q&As as sources, then retrain the chatbot. Training usually finishes in 1-2 minutes.","type":"q&a"}],"embeddingText":"How does Chat Data work?"}}}},"400":{"description":"The scores could not be computed. For example: `chatbotId` is missing, `baseModel` is not an allowed value, `messages` is not an array, is empty, ends with an empty message, or its last message is too long.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Last message is empty"}}}},"401":{"description":"Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"403":{"description":"The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Chatbot 6650f1c2a9e4b83d2c7a1f05 was not found in this API key's workspace. It may have been deleted or moved to another workspace."}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}},"security":[{"HTTPBearer":[]}]}},"/query-knowledge-base/{chatbotId}":{"post":{"tags":["Chatbot Operations"],"summary":"Query the knowledge base","description":"This operation fetches segments pertinent to generating responses. Designed for seamless chatbot integration with the GPTs store, this API endpoint allows users to supply relevant document fragments to the GPTs. As with the `/get-confidence-score` endpoint, results are cached by query for efficiency.\n\n**Credit Cost:** Each query costs **0.5 message credits**. If reranking runs, the total cost is **1.0 message credit** (0.5 base + 0.5 reranking); a cached result costs 0.5 even with reranking enabled. Requests are rejected if the available credits are insufficient.","operationId":"QueryKnowledgeBase","parameters":[{"required":true,"schema":{"title":"Chatbot ID","type":"string"},"name":"chatbotId","in":"path","description":"The unique identifier allocated to the chatbot."}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendQueryKnowledgeBaseReq"}}},"required":true},"responses":{"200":{"description":"Successful response. The body is a JSON array of matching chunks, without a `status` field.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","description":"The name or URL of the source (document filename, website URL, etc.).","example":"https://www.example.com/support/opening-hours"},"type":{"type":"string","description":"The data source type of the chunk (e.g. `website`, `text/pdf`, `text/csv`, `product`, `video`, `notion`).","example":"website"},"snippet":{"type":"string","description":"The text content of the chunk.","example":"Our support team is available Monday to Friday, 9am to 6pm EST. Outside these hours you can email support@example.com."},"relavant_score":{"type":"string","description":"The similarity score of the chunk as a string with two decimal places (the field name is spelled `relavant_score`).","example":"0.87"}}},"required":["source","type","snippet","relavant_score"]}}}},"400":{"description":"The query could not be run. For example: the chatbot does not use the `custom-data-upload` model, `query` is missing or empty, the workspace has run out of message credits, or the chatbot has reached its credit limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Please provide a non-empty query."}}}},"401":{"description":"Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"403":{"description":"The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Chatbot 6650f1c2a9e4b83d2c7a1f05 was not found in this API key's workspace. It may have been deleted or moved to another workspace."}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}},"security":[{"HTTPBearer":[]}]}},"/upload-file/{chatbotId}":{"post":{"tags":["File Operations"],"summary":"Upload a file","description":"Upload a file to be used with a chatbot, for example as a `files` attachment in `/chat` or `/live-chat`. The file is stored in the chatbot's folder under its original name. If a file with that name already exists, it is not replaced: nothing is uploaded and the existing file's URL is returned. Uploads count toward the workspace's file storage limit.","operationId":"UploadFile","parameters":[{"name":"chatbotId","in":"path","required":true,"schema":{"type":"string"},"description":"The unique identifier allocated to the chatbot."}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"The file to upload.","example":"product-handbook.pdf"}},"required":["file"]}}},"required":true},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["success"]},"url":{"type":"string","description":"The URL where the uploaded file can be accessed, with a read-only SAS token.","example":"https://example.blob.core.windows.net/chatfiles/6650f1c2a9e4b83d2c7a1f05/product-handbook.pdf?sv=2024-11-04&se=2026-11-13T09%3A30%3A00Z&sr=b&sp=r&sig=Xq7mB2v9KpL4tR8wN1cZ5yF3hJ6dS0aE%2BuG7iO2kQ%3D"}},"required":["status","url"]}}}},"400":{"description":"No `file` was sent, or the workspace has reached its file storage limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"The workspace has reached the file storage limit."}}}},"401":{"description":"Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"403":{"description":"The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Chatbot 6650f1c2a9e4b83d2c7a1f05 was not found in this API key's workspace. It may have been deleted or moved to another workspace."}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"500":{"description":"The file could not be stored; the body also identifies the file. A file sent under a field other than `file` also gets a 500, whose body is not JSON.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"message":{"type":"string","description":"The storage error."},"file":{"type":"object","description":"The file that failed to upload.","properties":{"name":{"type":"string","description":"The file name."},"size":{"type":"number","description":"The file size in bytes."},"type":{"type":"string","description":"The MIME type of the file."}}}}}}}}},"security":[{"HTTPBearer":[]}]}},"/delete-file":{"post":{"tags":["File Operations"],"summary":"Delete an uploaded file","description":"This API endpoint allows you to delete a previously uploaded file associated with a chatbot.","operationId":"DeleteFile","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["chatbotId","fileUrl"],"properties":{"chatbotId":{"type":"string","description":"The unique identifier allocated to the chatbot."},"fileUrl":{"type":"string","description":"The URL of the file to be deleted.","example":"https://example.blob.core.windows.net/chatfiles/6650f1c2a9e4b83d2c7a1f05/product-handbook.pdf"}}}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["status","message"],"properties":{"status":{"type":"string","enum":["success"]},"message":{"type":"string","description":"A confirmation message.","example":"File deleted successfully."}}}}}},"400":{"description":"`chatbotId` or `fileUrl` is missing, `fileUrl` is not inside this chatbot's storage folder, no file exists at that URL, or storage returned an error (also reported as `File not found.`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"File not found."}}}},"401":{"description":"Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"403":{"description":"The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Chatbot 6650f1c2a9e4b83d2c7a1f05 was not found in this API key's workspace. It may have been deleted or moved to another workspace."}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"500":{"description":"The file was deleted but the workspace's storage usage could not be updated; `message` contains the error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"}}}}},"security":[{"HTTPBearer":[]}]}},"/get-sas-token":{"post":{"tags":["File Operations"],"summary":"Get a file access token","description":"Generate a read-only Shared Access Signature (SAS) token for accessing a specific uploaded file.","operationId":"GetSasToken","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["chatbotId","fileUrl"],"properties":{"chatbotId":{"type":"string","description":"The unique identifier allocated to the chatbot."},"fileUrl":{"type":"string","description":"The URL of the file to generate a SAS token for.","example":"https://example.blob.core.windows.net/chatfiles/6650f1c2a9e4b83d2c7a1f05/product-handbook.pdf"}}}}}},"responses":{"200":{"description":"Successful response. For a file that does not exist, `sasToken` is empty and `url` ends with `?`.","content":{"application/json":{"schema":{"type":"object","required":["status","url","sasToken"],"properties":{"status":{"type":"string","enum":["success"]},"url":{"type":"string","description":"The complete file URL with the new SAS token.","example":"https://example.blob.core.windows.net/chatfiles/6650f1c2a9e4b83d2c7a1f05/product-handbook.pdf?sv=2024-11-04&se=2026-11-13T09%3A30%3A00Z&sr=b&sp=r&sig=Xq7mB2v9KpL4tR8wN1cZ5yF3hJ6dS0aE%2BuG7iO2kQ%3D"},"sasToken":{"type":"string","description":"The generated read-only SAS token.","example":"sv=2024-11-04&se=2026-11-13T09%3A30%3A00Z&sr=b&sp=r&sig=Xq7mB2v9KpL4tR8wN1cZ5yF3hJ6dS0aE%2BuG7iO2kQ%3D"}}}}}},"400":{"description":"`fileUrl` is missing, or it is not inside this chatbot's storage folder.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Invalid file URL."}}}},"401":{"description":"Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"403":{"description":"The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Chatbot 6650f1c2a9e4b83d2c7a1f05 was not found in this API key's workspace. It may have been deleted or moved to another workspace."}}}},"404":{"description":"`chatbotId` was not provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"No chatbot associated with the provided chatbot ID was found for the user."}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}},"security":[{"HTTPBearer":[]}]}},"/chat":{"post":{"tags":["Chatbot Operations"],"summary":"Send a message","description":"Send messages to a chatbot and receive a response. The API supports both streaming and non-streaming modes,\nas well as OpenAI-compatible response formats.\n\nWhen `stream` is set to `true`, the response is a stream of text chunks that should be consumed with a\n`ReadableStream` reader and `TextDecoder`.\n\nWhen `openAIFormat` is set to `true`, responses match OpenAI's `/chat/completions` API format. For streaming\nresponses, this means Server-Sent Events (SSE) in OpenAI's chunk format. If the request fails after the stream has started, it ends with HTTP 200 and no `data: [DONE]`.\n\nWhen `skipCache` is set to `true`, the response cache is bypassed and the LLM is invoked even if a cached response\nexists for the same `messages` array. This is useful for regenerating answers. Credits, rate limits, AI actions, and the `chat` webhook\nall behave identically to a normal send — its payload for a `skipCache: true` request includes\n`regenerate: true`. The persisted conversation's trailing assistant message (if any) is replaced by the new response.","operationId":"SendMessage","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageReq"}}},"required":true},"responses":{"200":{"description":"The chatbot's answer as plain text, streamed in chunks when `stream` is true. With `openAIFormat` set, an OpenAI-compatible JSON object instead, or `text/event-stream` chunks when streaming.","content":{"text/plain":{"schema":{"type":"string","title":"Response Text"},"example":"We're open Monday to Friday, 9am to 6pm EST.\nOutside those hours you can email support@example.com and we'll reply the next business day."}}},"400":{"description":"The message could not be answered. For example: `chatbotId` is missing, `baseModel` is not an allowed value or is not allowed in a HIPAA workspace, `basePrompt` is empty, `messages` is not an array, is empty or ends with an empty message, a role is not `user` or `assistant`, `appendMessages` is true but `messages` is not a single user message, the content or an attached file is too long or could not be processed, the workspace has run out of message credits, or the chatbot has reached its credit limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Your workspace has run out of message credits. Buy more or upgrade at https://www.chat-data.com/pricing."}}}},"401":{"description":"Authentication failed (the `Authorization` header is missing or malformed, the API key does not exist, its workspace is unavailable or has no owner, or the plan does not include API access), or the chatbot uses `custom-model` and the plan does not include custom models (`Custom model is unavailable in the current plan.`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"403":{"description":"The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Chatbot 6650f1c2a9e4b83d2c7a1f05 was not found in this API key's workspace. It may have been deleted or moved to another workspace."}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"503":{"description":"The request waited about 130 seconds behind earlier requests for the same conversation (`Server busy, please retry.`). Retry the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Server busy, please retry."}}}}},"security":[{"HTTPBearer":[]}]}},"/get-conversations/{chatbotId}":{"get":{"tags":["Conversation Operations"],"summary":"Get conversations","description":"Get conversations from a chatbot, most recently active first. Only conversations with at least one user message are returned. Results are paginated.","operationId":"GetConversations","parameters":[{"required":true,"schema":{"title":"Chatbot ID","type":"string"},"name":"chatbotId","in":"path","description":"The unique identifier allocated to the chatbot."},{"schema":{"title":"Start Timestamp","type":"number","description":"Start of the time range (inclusive), in milliseconds since the Unix epoch. A conversation matches when it was created or last active within the range."},"name":"startTimestamp","in":"query"},{"schema":{"title":"End Timestamp","type":"number","description":"End of the time range (exclusive), in milliseconds since the Unix epoch."},"name":"endTimestamp","in":"query"},{"schema":{"title":"Start","type":"number","description":"The start position of the results, used for pagination.","default":0},"name":"start","in":"query"},{"schema":{"title":"Size","type":"number","description":"The maximum number of results returned after the start position, used for pagination. A negative value returns all remaining results.","default":100},"name":"size","in":"query"},{"schema":{"title":"Source","type":"array","items":{"type":"string","enum":["widget","iframe","site","api","Whatsapp","WhatsappWebAPI","Messenger","Instagram","Telegram","Line","Slack","Discord","Workflow Studio","cron-trigger"]},"description":"Filter conversations by source. Repeat the parameter to match several sources."},"name":"source","in":"query"},{"schema":{"title":"Lead ID","type":"string","description":"The UUID of the lead, which can be obtained from the `lead-submission` webhook event."},"name":"leadId","in":"query"},{"schema":{"title":"Requested Live Chat","type":"boolean","description":"`true` returns only conversations that requested live chat support, `false` only those that did not."},"name":"requestedLiveChat","in":"query"},{"schema":{"title":"Live Chat Ended","type":"boolean","description":"`true` returns only conversations whose live chat has ended, `false` only those whose live chat has not ended."},"name":"liveChatEnded","in":"query"},{"schema":{"title":"Overall Rating","type":"number","description":"Filter conversations by their overall rating (1-5).","minimum":1,"maximum":5},"name":"overalRating","in":"query"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationsRes"}}}},"400":{"description":"An unexpected error occurred while processing the request; `message` contains the error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"}}}},"401":{"description":"Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"403":{"description":"The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Chatbot 6650f1c2a9e4b83d2c7a1f05 was not found in this API key's workspace. It may have been deleted or moved to another workspace."}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}},"security":[{"HTTPBearer":[]}]}},"/get-conversation/{conversationId}":{"get":{"tags":["Conversation Operations"],"summary":"Get a conversation","description":"Get detailed information about a specific conversation, including messages, customer details if available, and metadata.\n\nIf `chatbotId` is provided, the conversation is retrieved from that chatbot.\nIf `chatbotId` is not provided, the conversation is retrieved from any chatbot in your workspace (or, with a chatbot-scoped key, from that key's chatbot).","operationId":"GetConversation","parameters":[{"required":true,"schema":{"title":"Conversation ID","type":"string"},"name":"conversationId","in":"path","description":"The unique identifier of the conversation."},{"required":false,"schema":{"title":"Chatbot ID","type":"string"},"name":"chatbotId","in":"query","description":"The unique identifier of the chatbot to retrieve the conversation from.\nIf not provided, the conversation is retrieved from any chatbot in your workspace."}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"title":"Conversation Response","type":"object","required":["status","conversation"],"properties":{"status":{"type":"string","enum":["success"]},"conversation":{"$ref":"#/components/schemas/Conversation","description":"The conversation."}}}}}},"400":{"description":"An unexpected error occurred while processing the request; `message` contains the error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"}}}},"401":{"description":"Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"403":{"description":"The API key cannot access this conversation. With a `chatbotId` query parameter, a chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`, and any key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when that chatbot does not exist or belongs to another workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Chatbot 6650f1c2a9e4b83d2c7a1f05 was not found in this API key's workspace. It may have been deleted or moved to another workspace."}}}},"404":{"description":"No conversation with this ID was found in the key's workspace (or in the given or key's chatbot), including one that belongs to another chatbot or workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Conversation not found"}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}},"security":[{"HTTPBearer":[]}]}},"/delete-conversation":{"delete":{"tags":["Conversation Operations"],"summary":"Delete a conversation","description":"Deletes a specific conversation associated with a chatbot. This operation requires both `chatbotId` and `conversationId`.","operationId":"DeleteConversation","parameters":[{"required":true,"schema":{"title":"Chatbot ID","type":"string"},"name":"chatbotId","in":"query","description":"The unique identifier of the chatbot."},{"required":true,"schema":{"title":"Conversation ID","type":"string"},"name":"conversationId","in":"query","description":"The unique identifier of the conversation to be deleted."}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"title":"Success","type":"object","properties":{"status":{"type":"string","enum":["success"]},"message":{"type":"string","description":"A confirmation message.","example":"Conversation deleted successfully."}}}}}},"400":{"description":"`chatbotId` or `conversationId` is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Please provide the conversationId and chatbotId."}}}},"401":{"description":"Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"403":{"description":"The API key cannot access the chatbot given in the `chatbotId` query parameter: a chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`, and any key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when that chatbot does not exist or belongs to another workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Chatbot 6650f1c2a9e4b83d2c7a1f05 was not found in this API key's workspace. It may have been deleted or moved to another workspace."}}}},"404":{"description":"The chatbot has no conversation with this ID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"No conversation found with the provided conversationId and chatbotId for the user."}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"500":{"description":"The conversation could not be deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"An error occurred while deleting the conversation."}}}}},"security":[{"HTTPBearer":[]}]}},"/attach-lead":{"post":{"tags":["Conversation Operations"],"summary":"Attach a lead to a conversation","description":"Attach or update a lead for a specific conversation. This endpoint allows you to associate customer information with a conversation.\n\n**UUID immutability:** Once a lead exists, its uuid can never be changed. Attempting to change an existing lead's uuid returns a 400 error.\n\n**Behavior:**\n- If the conversation already has a lead attached, that lead is updated with the provided fields (its uuid cannot be changed).\n- If no lead is attached, the system searches for an existing lead using ALL provided identifiers together in a single query (best-effort matching).\n- If an existing lead is found, it is updated and attached to the conversation (its uuid cannot be changed).\n- If no lead is found, a new lead is created with the provided information and attached to the conversation.\n\n**Search strategy:** Best-effort matching using all provided fields in a single query. For example, if you provide both email and phone, the system will search for a lead that matches BOTH values, not just email OR phone.\n\n**Name matching:** Names are compared with an exact, case-sensitive string match. If several leads match the provided fields (for example, two leads share the same name), one of them is used, and which one is not guaranteed. For deterministic matching, use unique identifiers (email, phone, `leadId`, etc.).\n\n**Creating new leads:** To create a new lead, provide at least one field besides `leadId` (name, email, phone, psid, ig_username, username, or info); `info` must come with another lead field. UUID alone is not sufficient for creation.\n\n**UUID handling:** Pass a lead's uuid as `leadId`. When creating a new lead, the provided `leadId` becomes its uuid; otherwise a new UUID is generated. A uuid must be unique within the chatbot; creating a lead with a uuid that is already in use returns a 400 error.\n\nExample body, updating an existing lead found by email:\n```json\n{\n  \"chatbotId\": \"6650f1c2a9e4b83d2c7a1f05\",\n  \"conversationId\": \"3f2b8c1e-9a4d-4e7b-8c2a-5d1e6f7a8b9c\",\n  \"email\": \"jane@chat-data.com\",\n  \"phone\": \"+14155550123\"\n}\n```\n\nExample body, creating a lead with a specific `leadId`:\n```json\n{\n  \"chatbotId\": \"6650f1c2a9e4b83d2c7a1f05\",\n  \"conversationId\": \"3f2b8c1e-9a4d-4e7b-8c2a-5d1e6f7a8b9c\",\n  \"leadId\": \"8d0c2b6e-4f1a-4b7c-9e3d-2a5f6b7c8d9e\",\n  \"name\": \"Jane Doe\",\n  \"email\": \"jane@chat-data.com\"\n}\n```","operationId":"AttachLead","requestBody":{"content":{"application/json":{"schema":{"type":"object","example":{"chatbotId":"6650f1c2a9e4b83d2c7a1f05","conversationId":"3f2b8c1e-9a4d-4e7b-8c2a-5d1e6f7a8b9c","name":"Jane Doe","email":"jane@chat-data.com","phone":"+14155550123","info":"Interested in the annual plan; asked about SSO."},"required":["chatbotId","conversationId"],"properties":{"chatbotId":{"type":"string","description":"The unique identifier of the chatbot.","example":"6650f1c2a9e4b83d2c7a1f05"},"conversationId":{"type":"string","description":"The unique identifier of the conversation.","example":"3f2b8c1e-9a4d-4e7b-8c2a-5d1e6f7a8b9c"},"leadId":{"type":"string","maxLength":100,"description":"Lead UUID. Can be used alone to find an existing lead, but is not sufficient for creating a new lead.\n**Important:** Once a lead exists, its uuid can never be changed. Attempting to change it returns a 400 error.\nWhen creating a new lead, this value becomes its uuid; otherwise a new UUID is generated.","example":"8d0c2b6e-4f1a-4b7c-9e3d-2a5f6b7c8d9e"},"name":{"type":"string","maxLength":100,"description":"Lead name. Can be used to find an existing lead with an exact, case-sensitive string match.\nIf several leads share the same name, one of them is used, and which one is not guaranteed. Use unique identifiers for deterministic matching.","example":"Jane Doe"},"email":{"type":"string","format":"email","maxLength":254,"description":"Lead email address. Must be a valid, deliverable email address of at most 254 characters (RFC 5321).","example":"jane@chat-data.com"},"phone":{"type":"string","maxLength":50,"description":"Lead phone number. It must be a valid phone number in international format, starting with `+`.","example":"+14155550123"},"psid":{"type":"string","maxLength":100,"description":"Page-scoped ID (typically for Facebook Messenger).","example":"6543210987654321"},"ig_username":{"type":"string","maxLength":100,"description":"Instagram username.","example":"jane.doe"},"username":{"type":"string","maxLength":100,"description":"Slack or Telegram username. A platform-specific identifier, distinct from `ig_username` (Instagram) and `psid` (Messenger).","example":"janedoe"},"info":{"type":"string","maxLength":1000000,"description":"Additional information about the lead, up to 1,000,000 characters. It may be truncated to 1,000 tokens if \"User Info Truncation\" is turned on in Settings > Limits Control.","example":"Interested in the annual plan; asked about SSO."}}}}},"required":true},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["status","lead"],"properties":{"status":{"type":"string","enum":["success"]},"lead":{"type":"object","description":"The lead attached to the conversation.","example":{"leadId":"8d0c2b6e-4f1a-4b7c-9e3d-2a5f6b7c8d9e","name":"Jane Doe","email":"jane@chat-data.com","phone":"+14155550123","info":"Interested in the annual plan; asked about SSO.","source":"api"},"properties":{"leadId":{"type":"string","description":"The unique identifier of the lead (UUID).","example":"8d0c2b6e-4f1a-4b7c-9e3d-2a5f6b7c8d9e"},"name":{"type":"string","description":"The name of the lead.","example":"Jane Doe"},"email":{"type":"string","description":"The email address of the lead.","example":"jane@chat-data.com"},"phone":{"type":"string","description":"The phone number of the lead.","example":"+14155550123"},"psid":{"type":"string","description":"The page-scoped ID (PSID) of the lead.","example":"6543210987654321"},"ig_username":{"type":"string","description":"The Instagram username of the lead.","example":"jane.doe"},"username":{"type":"string","description":"The Slack or Telegram username of the lead.","example":"janedoe"},"info":{"type":"string","description":"Additional information about the lead.","example":"Interested in the annual plan; asked about SSO."},"source":{"type":"string","description":"The source of the lead information (always `api` for this endpoint).","example":"api"}}}}}}}},"400":{"description":"Bad request (validation errors).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"examples":{"missingFields":{"value":{"status":"error","message":"Please provide at least one lead field: uuid, name, email, phone, psid, ig_username, or username."}},"uuidOnly":{"value":{"status":"error","message":"To create a new lead, you must provide at least one of: name, email, phone, psid, ig_username, or username."}},"uuidConflict":{"value":{"status":"error","message":"Cannot change uuid of existing lead. Current lead has uuid '8d0c2b6e-4f1a-4b7c-9e3d-2a5f6b7c8d9e', but you provided '1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d'. Please update the lead without changing the uuid."}},"invalidEmail":{"value":{"status":"error","message":"Invalid email format or domain."}},"fieldTooLong":{"value":{"status":"error","message":"email must not exceed 254 characters."}}}}}},"401":{"description":"Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"403":{"description":"The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Chatbot 6650f1c2a9e4b83d2c7a1f05 was not found in this API key's workspace. It may have been deleted or moved to another workspace."}}}},"404":{"description":"The chatbot has no conversation with this ID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"No conversation found for the provided conversationId."}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}},"security":[{"HTTPBearer":[]}]}},"/get-conversation-portal-link/{conversationId}":{"get":{"tags":["Conversation Operations"],"summary":"Get the conversation portal link","description":"Generate a shareable portal link for a specific conversation. The conversation portal must be enabled for the chatbot. The link is valid for 30 days.\n\nBoth `conversationId` (path parameter) and `chatbotId` (query parameter) are required. The conversation itself is not looked up, so a link is returned for any `conversationId`.","operationId":"GetConversationPortalLink","parameters":[{"in":"path","name":"conversationId","required":true,"schema":{"type":"string"},"description":"The UUID of the conversation.","example":"3f2b8c1e-9a4d-4e7b-8c2a-5d1e6f7a8b9c"},{"in":"query","name":"chatbotId","required":true,"schema":{"type":"string"},"description":"The unique identifier of the chatbot.","example":"6650f1c2a9e4b83d2c7a1f05"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["status","portalLink"],"properties":{"status":{"type":"string","enum":["success"]},"portalLink":{"type":"string","description":"The shareable portal link for the conversation.","example":"https://chat.example.com/conversation/uJrRMVTPS7u7x5heMahGLNCNK7a3iGAltpgT9As5fqTQBfYeRgc1yi6sAzuXgIbyexBrt2DDgV0yfBRXfbnhdsJMGX2sFpiJEK1wLHpHOPWrZso7V3IiwWF_OEXz8S_bMdRl9RCqHaI4NirOS2kKx5P5p-3SxIQFTxuPLeyzU6ShbHAlrJn0WduTS-KHKGbLlUqjI1-gQL6JcKs6YJaJyovXOhikGiDB_gd6Okmc_q9nZYfz"}}}}}},"401":{"description":"Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"403":{"description":"The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace. Also returned when the conversation portal is not enabled for the chatbot (`Conversation portal is not enabled for this chatbot`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Conversation portal is not enabled for this chatbot"}}}},"404":{"description":"The `chatbotId` query parameter was not provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Chatbot not found or insufficient permissions"}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"500":{"description":"An unexpected error occurred while processing the request; `message` contains the error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"}}}}},"security":[{"HTTPBearer":[]}]}},"/get-admin-live-chat-link/{conversationId}":{"get":{"tags":["Conversation Operations"],"summary":"Get the admin live chat link","description":"Generate an admin live chat portal link for a specific conversation. This endpoint allows authorized users to access the admin interface for managing live chat conversations.\n\nRequirements:\n- Your plan must include live chat.\n- Live chat must be enabled in the chatbot's settings.\n\nBoth `conversationId` (path parameter) and `chatbotId` (query parameter) are required.","operationId":"GetAdminLiveChatPortal","parameters":[{"in":"path","name":"conversationId","required":true,"schema":{"type":"string"},"description":"The UUID of the conversation.","example":"3f2b8c1e-9a4d-4e7b-8c2a-5d1e6f7a8b9c"},{"in":"query","name":"chatbotId","required":true,"schema":{"type":"string"},"description":"The unique identifier of the chatbot.","example":"6650f1c2a9e4b83d2c7a1f05"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["status","portalLink"],"properties":{"status":{"type":"string","enum":["success"]},"portalLink":{"type":"string","description":"The admin live chat portal link for the conversation.","example":"https://chat.example.com/chat-portal/admin/KfEoaT8Emf7tzKBm39l2ucHN1BHmyfy9F80A39HNLMeP-TisvnerMwFRzj3Xq9kwQXQTRrsGBKFfegZkb9ftNQFf9SgVXW1_P26QcfRNqVNsdpH164N2mA8g_YitaK6_qXWTC1sXghhkyACaGbjIN9cAkEZNacJni265Lea4qD0nbou6Mfp8qSjbuhXOttJZY7q7keMMcb1bRJPqqtWuUO1u2AOaeTbpSaIJ9y8PuQ"}}}}}},"400":{"description":"The `chatbotId` query parameter is missing, the plan does not include live chat, or live chat is not enabled for the chatbot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Live chat is ineligible for this user. Please upgrade your plan to enable live chat at https://www.chat-data.com/pricing"}}}},"401":{"description":"Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"403":{"description":"The API key cannot access the chatbot given in the `chatbotId` query parameter: a chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`, and any key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when that chatbot does not exist or belongs to another workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Chatbot 6650f1c2a9e4b83d2c7a1f05 was not found in this API key's workspace. It may have been deleted or moved to another workspace."}}}},"404":{"description":"The chatbot has no conversation (stored or in an active live session) with this ID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"No conversation found for the provided conversationId."}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"500":{"description":"An unexpected error occurred while processing the request; `message` contains the error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"}}}}},"security":[{"HTTPBearer":[]}]}},"/list-actions/{chatbotId}":{"get":{"tags":["Chatbot Operations"],"summary":"List actions","description":"Retrieves all configured actions for the specified chatbot.","operationId":"ListActions","parameters":[{"in":"path","name":"chatbotId","required":true,"schema":{"type":"string"},"description":"The unique identifier allocated to the chatbot."}],"responses":{"200":{"description":"Successfully retrieved actions.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["success"]},"actions":{"type":"array","description":"The chatbot's configured actions.","items":{"$ref":"#/components/schemas/Action"}}}}}}},"400":{"description":"An unexpected error occurred while processing the request; `message` contains the error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"}}}},"401":{"description":"Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"403":{"description":"The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Chatbot 6650f1c2a9e4b83d2c7a1f05 was not found in this API key's workspace. It may have been deleted or moved to another workspace."}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}},"security":[{"HTTPBearer":[]}]}},"/get-action/{chatbotId}":{"get":{"tags":["Chatbot Operations"],"summary":"Get an action","description":"Retrieves a specific action by name or index for the specified chatbot. Send exactly one of `name` or `index`.","operationId":"GetAction","parameters":[{"in":"path","name":"chatbotId","required":true,"schema":{"type":"string"},"description":"The unique identifier allocated to the chatbot."},{"in":"query","name":"name","required":false,"schema":{"type":"string","example":"stockPriceLookup"},"description":"The name of the action to retrieve (mutually exclusive with `index`)."},{"in":"query","name":"index","required":false,"schema":{"type":"integer","minimum":0,"example":0},"description":"The index of the action to retrieve (mutually exclusive with `name`).","example":0}],"responses":{"200":{"description":"Successfully retrieved action.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["success"]},"action":{"$ref":"#/components/schemas/Action","description":"The action."}}}}}},"400":{"description":"Neither or both of `name` and `index` were provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Either name or index must be provided, but not both."}}}},"401":{"description":"Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"403":{"description":"The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Chatbot 6650f1c2a9e4b83d2c7a1f05 was not found in this API key's workspace. It may have been deleted or moved to another workspace."}}}},"404":{"description":"The chatbot has no action with this name or index.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Action not found."}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}},"security":[{"HTTPBearer":[]}]}},"/add-action":{"post":{"tags":["Chatbot Operations"],"summary":"Add an action","operationId":"AddAction","description":"Adds a new action to the specified chatbot. Top-level fields are checked (see the 400 response); `headers`, `pathParams`, `queryParams` and `bodyParams` items are stored as sent, without schema checks. An `api` action is also tested before it is saved: Chat Data sends a request to its `url`, filling each parameter with its `example` value, and rejects the action if that request fails.\n\n`mcp` actions cannot be added with this endpoint. A new action is enabled unless `enabled` is `false`; enabled actions count toward your plan's action limit.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["chatbotId","action"],"properties":{"chatbotId":{"type":"string","description":"The ID of the chatbot to which the action will be added.","example":"6650f1c2a9e4b83d2c7a1f05"},"action":{"$ref":"#/components/schemas/ActionInput","description":"The action to add."}}}}}},"responses":{"200":{"description":"Action successfully added.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"success"},"action":{"$ref":"#/components/schemas/Action","description":"The action."}}}}}},"400":{"description":"The action was rejected. For example: `chatbotId` or `action` is missing, a required field is missing, a field is not allowed or has the wrong type, `name` contains characters other than letters, numbers, underscores and hyphens or is already used, `type` is `mcp` or not supported, a button action lacks `label` or `link`, `includedDomains` is not an array of valid URLs, the chatbot already has the maximum number of actions or the plan's action limit is reached, or the test request of an `api` action failed. A failed test request may return the test result object instead of `{ status, message }`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Missing required field: description"}}}},"401":{"description":"Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"403":{"description":"The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Chatbot 6650f1c2a9e4b83d2c7a1f05 was not found in this API key's workspace. It may have been deleted or moved to another workspace."}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}},"security":[{"HTTPBearer":[]}]}},"/delete-action/{chatbotId}":{"delete":{"tags":["Chatbot Operations"],"summary":"Delete an action","description":"Deletes a specific action from the chatbot by either name or index. Send exactly one of `name` or `index`.","operationId":"DeleteAction","parameters":[{"required":true,"schema":{"title":"Chatbot ID","type":"string"},"name":"chatbotId","in":"path","description":"The unique identifier of the chatbot."},{"in":"query","name":"name","required":false,"schema":{"type":"string","example":"stockPriceLookup"},"description":"The name of the action to delete (mutually exclusive with `index`)."},{"in":"query","name":"index","required":false,"schema":{"type":"integer","minimum":0,"example":0},"description":"The index of the action to delete (mutually exclusive with `name`).","example":0}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["status","deletedAction"],"properties":{"status":{"type":"string","enum":["success"]},"deletedAction":{"$ref":"#/components/schemas/Action","description":"The action that was deleted."}}}}}},"400":{"description":"Neither or both of `name` and `index` were provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Either name or index must be provided, but not both."}}}},"401":{"description":"Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"403":{"description":"The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Chatbot 6650f1c2a9e4b83d2c7a1f05 was not found in this API key's workspace. It may have been deleted or moved to another workspace."}}}},"404":{"description":"The chatbot has no action with this name or index.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Action not found."}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}},"security":[{"HTTPBearer":[]}]}},"/live-chat":{"post":{"tags":["Chatbot Operations"],"summary":"Send a live chat message","description":"Send a live chat message to an existing conversation of a chatbot. The message can be sent as a human agent (`role: 'human'`), as an assistant response (`role: 'assistant'`) or as a user message (`role: 'user'`).\n\n**Role behavior:**\n- **'human' (default)**: The message is sent as a human agent. This automatically stops the AI bot so that it does not interfere with human assistance. The `name` and `avatar` parameters are used for the human agent's identity.\n- **'assistant'**: The message is sent as an AI assistant response. The AI bot continues to operate normally. The `name` and `avatar` parameters are ignored.\n- **'user'**: The message is sent as a user message. The AI bot continues to operate normally. The `name` and `avatar` parameters are ignored.\n\nIf you want to take over the conversation as a human agent, use the default 'human' role. If you want to send assistant responses without stopping the AI bot, use the 'assistant' role.","operationId":"SendLiveChatMessage","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["chatbotId","message","conversationId"],"properties":{"chatbotId":{"type":"string","description":"The unique identifier of the chatbot.","example":"6650f1c2a9e4b83d2c7a1f05"},"message":{"type":"string","description":"The message text to be sent to the conversation. It must be a non-empty string (an empty string gets a 400); to send only `files`, send a blank string such as a single space.","example":"Hi Jane, I'm Alex from the support team. Let me check your order status for you."},"conversationId":{"type":"string","description":"The unique identifier of the conversation. It must be an existing conversation of the chatbot.","example":"3f2b8c1e-9a4d-4e7b-8c2a-5d1e6f7a8b9c"},"role":{"type":"string","enum":["human","assistant","user"],"default":"human","description":"The role of the message sender. Valid values: 'human' (human agent), 'assistant' (AI response) or 'user' (end user/customer). When the role is 'assistant' or 'user', the `name` and `avatar` parameters are ignored.\n"},"name":{"type":"string","description":"The name of the human agent sending the message. Only used when the role is 'human'. If unset, the workspace owner's name is used as the agent name.","example":"Alex Chen"},"avatar":{"type":"string","format":"uri","description":"The URL of the avatar image for the message sender. Only used when the role is 'human'. If unset, the workspace owner's avatar is used as the human agent's avatar.","example":"https://example.blob.core.windows.net/chatfiles/6650f1c2a9e4b83d2c7a1f05/agent-avatar.png"},"files":{"type":"array","description":"An optional array of file objects to be attached to the message, at most 3.","maxItems":3,"items":{"type":"object","required":["name","type","url"],"properties":{"name":{"type":"string","description":"The name of the file."},"type":{"type":"string","description":"The MIME type of the file (for example `image/png` or `application/pdf`)."},"url":{"type":"string","format":"uri","description":"The public URL of the file that is hosted by you."}}}}}}}},"required":true},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["success"]},"emailed_offline_message":{"type":"boolean","description":"Whether the message was also emailed to the user because they were offline. This only happens when the role is 'human' and the conversation's lead has an email address.","example":false},"is_user_online":{"type":"boolean","description":"Whether the user is currently online in the conversation.","example":true},"delivery":{"type":"object","description":"Only present when the conversation came from WhatsApp, WhatsApp Web, Instagram, Messenger, Telegram or LINE and `role` is `human` or `assistant`. The message is stored either way; this tells whether it was handed to the platform.","required":["channel","state"],"properties":{"channel":{"type":"string","description":"The platform of the conversation (its `source`).","example":"Whatsapp"},"state":{"type":"string","enum":["accepted","skipped","failed"],"description":"`accepted`: the message was handed to the platform (this does not confirm delivery). `skipped`: not sent because the user's last message is more than 24 hours old (send a template message instead). `failed`: the send failed."},"reason":{"type":"string","enum":["outside_24h_window","send_failed","send_error"],"description":"Why the message was skipped or failed. Absent when `state` is `accepted`."},"error":{"type":"string","nullable":true,"description":"The platform's error message, when there is one. Absent when `state` is `accepted`."}},"example":{"channel":"Whatsapp","state":"accepted"}}},"required":["status","emailed_offline_message","is_user_online"]}}}},"400":{"description":"The message could not be sent. For example: `chatbotId`, `conversationId` or `message` is missing or empty, `message` is not a string, `role` is not `human`, `assistant` or `user`, the plan does not include live chat, live chat is not enabled for the chatbot, the conversation does not exist, or `files` has more than 3 items or an invalid item.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"No conversation found for the provided conversationId=3f2b8c1e-9a4d-4e7b-8c2a-5d1e6f7a8b9c."}}}},"401":{"description":"Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"403":{"description":"The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Chatbot 6650f1c2a9e4b83d2c7a1f05 was not found in this API key's workspace. It may have been deleted or moved to another workspace."}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"503":{"description":"The request waited about 130 seconds behind earlier requests for the same conversation (`Server busy, please retry.`). Retry the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Server busy, please retry."}}}}},"security":[{"HTTPBearer":[]}]}},"/send-whatsapp-web-message-outbound":{"post":{"tags":["Chatbot Operations"],"summary":"Send an outbound WhatsApp Web message","description":"Send an outbound WhatsApp Web message to a phone number. The message is added to the conversation with that number, which is created if it does not exist yet, and a lead is created for the number if there is none.\nWhen the recipient replies, their message is threaded into the same conversation.\n\nAn identical request (same chatbot, recipient, text, files and format) within 5 minutes of an accepted one is rejected with a 409 and not sent again.\n\n---\n\n# 🚨 CRITICAL: WhatsApp Web Ban Prevention Guide\n\n**IMPORTANT:** This endpoint uses the unofficial WhatsApp Web protocol. **Account bans are common and permanent.** Follow these guidelines carefully to avoid losing your WhatsApp number.\n\n## ⚠️ Terms of Service Warning\n\n**Using WhatsApp Web for bulk messaging or automation violates WhatsApp's Terms of Service.**\n- Risk of permanent account ban with no appeal process\n- You could lose your personal WhatsApp number forever\n- WhatsApp does not officially support automation on personal accounts\n- **For compliant messaging, follow the \"[Sending WhatsApp template messages](https://cookbook.chat-data.com/docs/whatsapp-integration#sending-whats-app-template-messages)\" guide to send template messages via make.com or n8n using the WhatsApp Business API. When users reply, our workflow AI action can be configured to fetch the conversation context and use AI to respond automatically.**\n\n**Use this endpoint at your own risk. These guidelines help reduce ban risk but do not guarantee safety.**\n\n---\n\n## 📊 Daily Limits by Account Age\n\n| Account Age            | Max NEW Contacts/Day | Total Messages/Day |\n|------------------------|----------------------|--------------------|\n| First 10 days          | 20 contacts          | 40-50 messages     |\n| New (2-6 months)       | 100-150 contacts     | 100-200 messages   |\n| Established (6-12 mo)  | 200-300 contacts     | 200-300 messages   |\n| Mature (2+ years)      | Up to 500 contacts   | 400-500 messages   |\n\n**Note:** These are community-reported estimates, not official WhatsApp limits. Actual limits may vary by region, account history, and WhatsApp's detection algorithms.\n\n**Conservative recommendation:** Max 200 new contacts/day regardless of account age.\n\n---\n\n## 🌍 Additional Risk Factors\n\n### Regional Variations\n- **India & Brazil:** Significantly stricter enforcement due to high spam rates\n- Ban thresholds may be lower in these regions\n- Consider even more conservative limits if sending from/to these countries\n\n### Multi-Session Limitations\n- WhatsApp Web supports **4-5 concurrent linked devices maximum**\n- Connecting too many sessions simultaneously can trigger security flags\n- Avoid frequent session connects/disconnects\n- May need to re-authenticate after WhatsApp app updates\n\n---\n\n## ⚠️ Critical Ban Triggers (Avoid These!)\n\n### Instant Ban Scenarios:\n1. **Spam Reports:** 5-10 spam reports = permanent ban\n   - 10% spam rate (10 blocks out of 100 contacts) = high ban risk\n2. **Cold Messaging:** Sending without opt-in consent = guaranteed ban\n3. **Speed Violations:**\n   - Sending identical messages to 100+ contacts in <1 hour\n   - No delays between messages (instant sending)\n4. **Low Engagement:** Consistently low response/reply rates may flag account as spam\n5. **New Account Abuse:** New account sending 100+ messages on day 1\n\n---\n\n## 🎯 Recommended Implementation Strategies\n\n**Note:** No strategy guarantees ban prevention. WhatsApp's detection algorithms are proprietary and can change without notice. These are community best practices.\n\n### Conservative Approach (Safest - Recommended for New Accounts)\n\n**Limits:**\n- Max 50 NEW contacts per day (first month)\n- Max 100 total messages per day\n- 45-60 second delay between messages (randomized)\n- Recommended: Send during business hours (9 AM - 6 PM) for better engagement\n\n**Batch Strategy:**\n- 20 contacts per batch\n- 15-minute cooldown between batches\n- Stop immediately if response rate drops below 40%\n\n**Warm-up Schedule (First 30 Days):**\n- Days 1-10: Max 20 NEW contacts/day\n- Days 11-20: Max 50 NEW contacts/day\n- Days 21-30: Max 100 NEW contacts/day\n- After 30 days: Max 150-200 NEW contacts/day\n\n### Standard Approach (After 1-2 Months)\n\n**Limits:**\n- Max 150 NEW contacts per day\n- Max 200 total messages per day\n- 30-50 second delay between messages (randomized)\n\n**Batch Strategy:**\n- 30 contacts per batch\n- 10-minute cooldown between batches\n- Stop if response rate drops below 45%\n\n### Aggressive Approach (Mature Accounts Only - 2+ Years)\n\n**Limits:**\n- Max 300 NEW contacts per day\n- Max 400 total messages per day\n- 20-40 second delay between messages (randomized)\n\n**Batch Strategy:**\n- 50 contacts per batch\n- 10-minute cooldown between batches\n- Stop if response rate drops below 50%\n\n**⚠️ Warning:** Even mature accounts can be banned. Use with caution.\n\n---\n\n## ✅ Success Checklist\n\nBefore sending messages, ensure:\n- [ ] Messages are **personalized** (not identical mass messages)\n- [ ] Account has completed **warm-up period** (if new)\n- [ ] Consider sending during **business hours** (9 AM - 6 PM) for better engagement\n- [ ] Rate limiting is **implemented and tested**\n- [ ] Response rate monitoring is **active**\n- [ ] Daily quotas are **tracked per account**\n- [ ] Batch processing with **cooldowns is configured**\n\n---\n\n## 🛑 Failure Indicators - Stop Immediately If:\n\n- Response rate drops below 30%\n- You receive 2-3 spam reports\n- Messages fail to deliver\n- You receive a warning message from this API\n- Contacts start blocking you\n\n**Recovery:** If you see these signs, stop all outbound messaging for 24-48 hours and review your strategy.\n\n---\n\n## 🏢 For Business/High-Volume Use\n\nIf you need to send:\n- More than 200 messages per day\n- Marketing or promotional content\n- Business-critical communications\n\n**Use a workflow automation platform with WhatsApp Business API integration instead.** Follow the \"[Sending WhatsApp template messages](https://cookbook.chat-data.com/docs/whatsapp-integration#sending-whats-app-template-messages)\" guide to send messages via make.com or n8n with our provided access token.\nWhen the user replies, you can use our workflow AI action, triggered on the first user message, to fetch the conversation context and respond automatically with AI.\n\nThe unofficial WhatsApp Web protocol is not suitable for business operations and carries high ban risk.\n\n---\n\n**Audio messages:** To send audio messages, make sure your [plan](/pricing) includes audio messages and enable audio in Settings → Chat Interface.","operationId":"SendWhatsAppWebMessageOutbound","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["chatbotId","phone","message"],"properties":{"chatbotId":{"type":"string","description":"The unique identifier of the chatbot.","example":"6650f1c2a9e4b83d2c7a1f05"},"phone":{"type":"string","description":"Recipient phone number in E.164 format, with or without the leading '+' (for example 14155550123).","example":"14155550123"},"message":{"type":"string","description":"The message text to send. It must not be empty.","example":"Hi Jane, your order #10482 has shipped. Reply here if you have any questions."},"files":{"type":"array","description":"An optional array of file objects to be attached to the message, at most 3.","maxItems":3,"items":{"type":"object","required":["name","type","url"],"properties":{"name":{"type":"string","description":"The name of the file."},"type":{"type":"string","description":"The MIME type of the file (for example image/png or application/pdf)."},"url":{"type":"string","format":"uri","description":"The public http(s) URL of the file."}}}},"format":{"type":"string","enum":["text","audio"],"default":"text","description":"Format of the message. When set to 'audio', the message text is converted to audio using text-to-speech.\n\n**Audio requirements:**\n- Requires a [plan](/pricing) that includes audio messages.\n- Audio must be enabled in the chatbot settings: Settings → Chat Interface → Enable Audio.\n- **Note:** If audio is not enabled, the API falls back to text and sends the message as text instead.\n\nValid values: 'text' (default, sends a text message) or 'audio' (converts the text to audio using text-to-speech, or falls back to text if audio is not enabled).\n"}}}}},"required":true},"responses":{"200":{"description":"Message sent successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["success"]},"conversationId":{"type":"string","description":"The conversation ID, formed as `<bot phone number>:<recipient phone number>`.","example":"14155550100:14155550123"},"leadUUID":{"type":"string","description":"The UUID of the lead associated with the recipient. For WhatsApp Web leads it is the recipient's phone number, digits only.","example":"14155550123"},"actualFormat":{"type":"string","enum":["text","audio"],"description":"The format in which the message was actually sent. When audio is requested but unavailable (disabled or generation failed), this is 'text' to indicate that the fallback occurred.","example":"text"}},"required":["status","conversationId","leadUUID","actualFormat"]}}}},"400":{"description":"The message could not be sent. For example: `chatbotId`, `phone` or `message` is missing, the phone number is invalid, `format` is not `text` or `audio`, `files` is not an array or has an invalid item or more than 3 items, WhatsApp Web is not set up for the chatbot, or the WhatsApp Web session is offline, expired or has no phone number yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"WhatsApp Web bot is offline or disconnected."}}}},"401":{"description":"Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"403":{"description":"The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Chatbot 6650f1c2a9e4b83d2c7a1f05 was not found in this API key's workspace. It may have been deleted or moved to another workspace."}}}},"409":{"description":"An identical message (same chatbot, recipient, text, files and format) was already accepted in the last 5 minutes. It is not sent again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Duplicate request detected. This message was recently processed."}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"500":{"description":"The message could not be sent through WhatsApp Web; `message` contains the error (`fetch failed` when the WhatsApp Web relay cannot be reached). When the relay rejects the message, its HTTP status is returned instead of 500.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Failed to send WhatsApp Web message"}}}}},"security":[{"HTTPBearer":[]}]}},"/livechat-state":{"post":{"tags":["Chatbot Operations"],"summary":"Start or end live chat","description":"Toggle or set the state of a live chat session for a specific conversation. Your plan must include live chat, and live chat must be enabled in the chatbot's settings.","operationId":"ToggleLiveChatState","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"chatbotId":{"type":"string","description":"The unique identifier of the chatbot."},"conversationId":{"type":"string","description":"The unique identifier of the conversation."},"end":{"type":"boolean","description":"If provided, `true` ends the live chat session and `false` reopens it. If omitted, the current state is toggled."}},"required":["chatbotId","conversationId"]}}},"required":true},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["success"]},"liveChatEnded":{"type":"boolean","description":"Whether the live chat session has ended after this request."}},"required":["status","liveChatEnded"]}}}},"400":{"description":"The state could not be changed. For example: `chatbotId` or `conversationId` is missing, the plan does not include live chat, live chat is not enabled for the chatbot, or the conversation does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Live chat is not enabled for this chatbot. Please turn on it in the page: https://www.chat-data.com/chatbot/6650f1c2a9e4b83d2c7a1f05/settings/live-chat"}}}},"401":{"description":"Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"403":{"description":"The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Chatbot 6650f1c2a9e4b83d2c7a1f05 was not found in this API key's workspace. It may have been deleted or moved to another workspace."}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}},"security":[{"HTTPBearer":[]}]}},"/toggle-bot-activation":{"post":{"tags":["Chatbot Operations"],"summary":"Turn a messaging integration on or off","description":"Toggle or set the activation status of a WhatsApp, Messenger, Instagram or LINE integration for a specific chatbot. `Telegram` and `WhatsappWebAPI` cannot be toggled: the call returns `active: null` and changes nothing.","operationId":"ToggleBotActivation","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["chatbotId","type","id"],"properties":{"chatbotId":{"type":"string","description":"The unique identifier of the chatbot."},"type":{"type":"string","enum":["Whatsapp","WhatsappWebAPI","Telegram","Messenger","Instagram","Line"],"description":"The type of third-party messaging platform."},"id":{"type":"string","description":"The ID of the integration to toggle — the phone number ID for WhatsApp, the page ID for Messenger/Instagram, or the integration's own ID for LINE. For WhatsApp, Messenger and Instagram, you can find it in the ID column of the integration modal.","example":"109876543210987"},"active":{"type":"boolean","description":"If provided, sets the activation status to this value. If omitted, the current status is toggled."}}}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["status","active"],"properties":{"status":{"type":"string","enum":["success"]},"active":{"type":"boolean","nullable":true,"description":"The updated activation status. `null` when the chatbot's integration of this `type` has no phone number or page with this `id`; nothing is changed then."}}}}}},"400":{"description":"`chatbotId` or `id` is missing, `type` is not a supported platform, or `active` is not a boolean.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Invalid active value. Active must be a boolean."}}}},"401":{"description":"Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"403":{"description":"The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Chatbot 6650f1c2a9e4b83d2c7a1f05 was not found in this API key's workspace. It may have been deleted or moved to another workspace."}}}},"404":{"description":"The chatbot has no integration of this `type` (for `Line`, no LINE integration with this `id`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"No third party bot associated with the provided chatbotId=6650f1c2a9e4b83d2c7a1f05 and type=Telegram was found."}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}},"security":[{"HTTPBearer":[]}]}},"/bot-control":{"post":{"tags":["Chatbot Operations"],"summary":"Pause or resume the bot in a conversation","description":"Toggle or set the bot control state for a conversation. When bot control is -1, the bot does not respond to user messages. When bot control is 1, the bot responds to user messages. This endpoint only works for conversations originating from WhatsApp, Instagram, Messenger, WhatsApp Web API, Telegram or LINE.","operationId":"ToggleBotControl","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"chatbotId":{"type":"string","description":"The unique identifier of the chatbot."},"conversationId":{"type":"string","description":"The unique identifier of the conversation."},"botControl":{"type":"integer","enum":[1,-1],"description":"If provided, sets the bot control state to this value (1 for on, -1 for off). If omitted, the current state is toggled.","example":-1},"botOffMins":{"type":"integer","minimum":0,"description":"How many minutes the bot should remain off; 0 keeps it off until the next bot control call. Only applies when `botControl` is set to -1; in every other case the stored value is reset to 0.","example":30}},"required":["chatbotId","conversationId"]}}},"required":true},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["success"]},"payload":{"type":"object","description":"The conversation's updated bot control state.","properties":{"botControl":{"type":"integer","enum":[1,-1],"description":"The updated bot control state for the conversation. 1 means the bot is active and responding; -1 means the bot is inactive and not responding.","example":-1},"botOffMins":{"type":"integer","description":"Minutes the bot will remain off. 0 means the bot remains off until the next bot control call.","example":30},"botOffTime":{"type":"string","format":"date-time","description":"When the bot was turned off. `null` unless the bot was turned off with `botOffMins`."}},"required":["botControl","botOffMins","botOffTime"]}},"required":["status"]}}}},"400":{"description":"The state could not be changed. For example: `botControl` is not 1 or -1, `botOffMins` is not a non-negative integer, `chatbotId` or `conversationId` is missing, the conversation does not exist, or it did not come from WhatsApp, Instagram, Messenger, WhatsApp Web, Telegram or LINE.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"botControl must be either 1 or -1"}}}},"401":{"description":"Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"403":{"description":"The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Chatbot 6650f1c2a9e4b83d2c7a1f05 was not found in this API key's workspace. It may have been deleted or moved to another workspace."}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}},"security":[{"HTTPBearer":[]}]}},"/get-customers/{chatbotId}":{"get":{"tags":["Chatbot Analytics"],"summary":"Get customers","description":"Get the customers (leads) collected by a chatbot, newest first. Results are paginated.","operationId":"GetCustomers","parameters":[{"required":true,"schema":{"title":"Chatbot ID","type":"string"},"name":"chatbotId","in":"path","description":"The unique identifier allocated to the chatbot."},{"schema":{"title":"Start Timestamp","type":"number","description":"Start of the time range (inclusive) for when customers were collected, in milliseconds since the Unix epoch."},"name":"startTimestamp","in":"query"},{"schema":{"title":"End Timestamp","type":"number","description":"End of the time range (exclusive), in milliseconds since the Unix epoch."},"name":"endTimestamp","in":"query"},{"schema":{"title":"Start","type":"number","description":"The start position of the results, used for pagination.","default":0},"name":"start","in":"query"},{"schema":{"title":"Size","type":"number","description":"The maximum number of results returned after the start position, used for pagination. A negative value returns all remaining results; `0` returns a 400 error.","default":100},"name":"size","in":"query"},{"schema":{"title":"Source","type":"array","items":{"type":"string","enum":["widget","iframe","site","api","Whatsapp","WhatsappWebAPI","Messenger","Instagram","Telegram","Line","Slack","Discord","Workflow Studio","cron-trigger"]},"description":"Filter customers by the source they were acquired from. Repeat the parameter to match several sources."},"name":"source","in":"query"},{"schema":{"title":"Lead ID","type":"string","description":"Filter by the lead's UUID (`leadId`).","example":"8d0c2b6e-4f1a-4b7c-9e3d-2a5f6b7c8d9e"},"name":"leadId","in":"query"},{"schema":{"title":"Page Scoped User ID","type":"string","description":"Filter by the page-scoped user ID (Messenger).","example":"6543210987654321"},"name":"psid","in":"query"},{"schema":{"title":"Instagram Username","type":"string","description":"Filter by the Instagram username.","example":"jane.doe"},"name":"ig_username","in":"query"},{"schema":{"title":"Username","type":"string","description":"Filter by the Slack or Telegram username.","example":"janedoe"},"name":"username","in":"query"},{"schema":{"title":"Name","type":"string","description":"Filter by the customer name (exact match).","example":"Jane Doe"},"name":"name","in":"query"},{"schema":{"title":"Email","type":"string","description":"Filter by the customer email address (exact match).","example":"jane@chat-data.com"},"name":"email","in":"query"},{"schema":{"title":"Phone","type":"string","description":"Filter by the customer phone number (exact match of the stored value).","example":"+14155550123"},"name":"phone","in":"query"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadsRes"}}}},"400":{"description":"An unexpected error occurred while processing the request; `message` contains the error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"}}}},"401":{"description":"Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"403":{"description":"The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Chatbot 6650f1c2a9e4b83d2c7a1f05 was not found in this API key's workspace. It may have been deleted or moved to another workspace."}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}},"security":[{"HTTPBearer":[]}]}},"/get-analysis/{chatbotId}":{"get":{"tags":["Chatbot Analytics"],"summary":"Get analytics","description":"Get the aggregated statistics of a chatbot.","operationId":"GetAnalysis","parameters":[{"required":true,"schema":{"title":"Chatbot ID","type":"string"},"name":"chatbotId","in":"path","description":"The unique identifier allocated to the chatbot."},{"schema":{"title":"Start Timestamp","type":"number","description":"Start of the time range (inclusive), in milliseconds since the Unix epoch. Statistics are stored per UTC day, each dated at 00:00 UTC."},"name":"startTimestamp","in":"query"},{"schema":{"title":"End Timestamp","type":"number","description":"End of the time range (inclusive), in milliseconds since the Unix epoch."},"name":"endTimestamp","in":"query"},{"schema":{"title":"Source","type":"array","items":{"type":"string","enum":["widget","iframe","site","api","Whatsapp","WhatsappWebAPI","Messenger","Instagram","Telegram","Line","Slack","Discord","Workflow Studio","cron-trigger","youtube-transcription","image-description-test","metering"]},"description":"Filter analytics by source. Repeat the parameter to match several sources."},"name":"source","in":"query"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/analysisRes"}}}},"400":{"description":"An unexpected error occurred while processing the request; `message` contains the error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"}}}},"401":{"description":"Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"403":{"description":"The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"Chatbot 6650f1c2a9e4b83d2c7a1f05 was not found in this API key's workspace. It may have been deleted or moved to another workspace."}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}},"security":[{"HTTPBearer":[]}]}},"/current-plan":{"get":{"tags":["User Account"],"summary":"Get the current plan","description":"Get a summary of the workspace's current subscriptions and privileges.\n\nThis operation requires a workspace API key; chatbot-scoped keys get a 403.","operationId":"getCurrentPlan","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/currentPlanRes"}}}},"400":{"description":"An unexpected error occurred while processing the request; `message` contains the error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"}}}},"401":{"description":"Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"403":{"description":"The request used a chatbot-scoped API key. This operation needs a workspace key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStatus"},"example":{"status":"error","message":"This operation requires a user-level API key, not a chatbot-specific key"}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}},"security":[{"HTTPBearer":[]}]}},"/sub-users":{"post":{"tags":["Sub-User Management"],"summary":"Create a sub-user","description":"Create a new sub-user for your company. Sub-users can log in to a branded portal on your custom domain and access their assigned chatbots.\n\nRequires the SSO Login add-on (see [plans](/pricing)) and a workspace API key; without the add-on, or with a chatbot-scoped key, the request gets a 403.\n\nYour workspace's SSO company must exist and have a login domain before you can create sub-users. The sub-user's email must be unique within the company. Creating a sub-user sends no email.","operationId":"CreateSubUser","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","chatbotIds"],"properties":{"email":{"type":"string","format":"email","description":"The sub-user's email address, stored in lowercase. It must be unique within the company, and for a sub-user without a password (who signs in by magic link) the mailbox must accept mail.","example":"jane@chat-data.com"},"name":{"type":"string","maxLength":100,"description":"The sub-user's display name. HTML tags are stripped.","example":"Jane Doe"},"password":{"type":"string","description":"Optional password for email/password login. It must satisfy at least three of the following - at least 8 characters, an uppercase letter, a lowercase letter, a number, a special character. Without a password the sub-user signs in by magic link (or Google, when enabled).","example":"Maple-Harbor-42"},"chatbotIds":{"type":"array","items":{"type":"string"},"minItems":1,"description":"Array of chatbot IDs to assign to this sub-user. All IDs must belong to chatbots in your workspace. Duplicates are automatically removed.","example":["6650f1c2a9e4b83d2c7a1f05","6650f1c2a9e4b83d2c7a1f06"]},"permissions":{"type":"array","items":{"type":"string","enum":["read","train","full","admin"]},"description":"Permissions granted to the sub-user. Defaults to the company's default permission if not provided. Invalid values are silently removed; if none of the provided values is valid, the request fails.","example":["read","train"]},"analyticsDashboardSections":{"type":"array","description":"Analytics dashboard sections visible to the sub-user. Defaults to the company's configured sections if not provided. Unknown section names are ignored.","items":{"type":"string","enum":["Overview","Credits Timeline","Messages Timeline","Live Chat Escalations Timeline","Message Distribution by Hour","Topics","Sentiments","Conversations Ratings","Chats","Submitted Leads","Upvotes/DownVotes","Geographic Distribution","Email Consumption Timeline","SMS Consumption Timeline"]},"example":["Overview","Messages Timeline","Chats"]},"googleEnabled":{"type":"boolean","description":"Whether to enable Google sign-in for this sub-user. It is enabled automatically if the company has Google sign-in configured."}}}}}},"responses":{"201":{"description":"Sub-user created successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubUserObject"},"example":{"_id":"6650f1c2a9e4b83d2c7a1f9a","company":"6650f1c2a9e4b83d2c7a1f3c","email":"jane@chat-data.com","name":"Jane Doe","avatar":"","chatbotIds":[{"_id":"6650f1c2a9e4b83d2c7a1f05","name":"Support Bot"},{"_id":"6650f1c2a9e4b83d2c7a1f06","name":"Sales Assistant"}],"permissions":["read","train"],"analyticsDashboardSections":["Overview","Messages Timeline","Chats"],"hasPassword":true,"hasGoogle":false,"createdAt":"2026-10-14T09:30:00.000Z"}}}},"400":{"description":"The sub-user could not be created. For example: `email` is missing, invalid or (for a sub-user without a password) not deliverable, `chatbotIds` is empty or contains an ID that is not a chatbot in your workspace, the workspace has no SSO company or the company has no login domain, `name` is not a string or is longer than 100 characters, none of the given `permissions` is valid, the password is too weak, or a sub-user with this email already exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubUserErrorObject"},"example":{"message":"A user with this email already exists for this company"}}}},"401":{"description":"Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"403":{"description":"The request used a chatbot-scoped API key (`This operation requires a user-level API key, not a chatbot-specific key`, with `status: error`), or the workspace does not have the SSO Login add-on (`SSO Login is unavailable with your current plan`, with no `status` field).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubUserErrorObject"},"example":{"message":"SSO Login is unavailable with your current plan"}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"500":{"description":"An unexpected error occurred while processing the request; `message` contains the error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubUserErrorObject"},"example":{"message":"Internal error message"}}}}},"security":[{"HTTPBearer":[]}]},"get":{"tags":["Sub-User Management"],"summary":"List sub-users","description":"Returns a list of all sub-users of your workspace's company. Each sub-user includes its assigned chatbots' names, not just their IDs. The response is an empty array when the workspace has no SSO company.\n\nRequires the SSO Login add-on (see [plans](/pricing)) and a workspace API key; without the add-on, or with a chatbot-scoped key, the request gets a 403.","operationId":"ListSubUsers","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SubUserObject"}}}}},"401":{"description":"Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"403":{"description":"The request used a chatbot-scoped API key (`This operation requires a user-level API key, not a chatbot-specific key`, with `status: error`), or the workspace does not have the SSO Login add-on (`SSO Login is unavailable with your current plan`, with no `status` field).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubUserErrorObject"},"example":{"message":"SSO Login is unavailable with your current plan"}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"500":{"description":"An unexpected error occurred while processing the request; `message` contains the error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubUserErrorObject"},"example":{"message":"Internal error message"}}}}},"security":[{"HTTPBearer":[]}]}},"/sub-users/{subUserId}":{"put":{"tags":["Sub-User Management"],"summary":"Update a sub-user","description":"Update an existing sub-user's name, password, chatbot assignments, permissions or analytics dashboard sections. Only provided fields are updated; omitted fields remain unchanged.\n\nRequires the SSO Login add-on (see [plans](/pricing)) and a workspace API key; without the add-on, or with a chatbot-scoped key, the request gets a 403.\n\nTo remove a sub-user's password (disabling password login), send:\n```json\n{\n  \"removePassword\": true\n}\n```","operationId":"UpdateSubUser","parameters":[{"in":"path","name":"subUserId","required":true,"schema":{"type":"string"},"description":"The unique identifier of the sub-user to update."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":100,"description":"Updated display name. HTML tags are stripped.","example":"Jane Doe"},"password":{"type":"string","description":"New password. It must meet the same complexity requirements as on creation. If both `password` and `removePassword` are sent, `password` wins and the new password is set."},"removePassword":{"type":"boolean","description":"Set to `true` to remove the sub-user's password, disabling password login. Ignored when `password` is also sent."},"chatbotIds":{"type":"array","items":{"type":"string"},"minItems":1,"description":"Updated chatbot assignments; replaces the current list. All IDs must belong to chatbots in your workspace. Duplicates are automatically removed.","example":["6650f1c2a9e4b83d2c7a1f05"]},"permissions":{"type":"array","items":{"type":"string","enum":["read","train","full","admin"]},"minItems":1,"description":"Updated permissions; replaces the current list. Invalid values are removed, and at least one valid permission is required.","example":["full"]},"analyticsDashboardSections":{"type":"array","items":{"type":"string"},"description":"Updated analytics dashboard sections; replaces the current list. Unknown section names are ignored.","example":["Overview","Chats"]}},"example":{"name":"Jane Doe","chatbotIds":["6650f1c2a9e4b83d2c7a1f05"],"permissions":["full"],"analyticsDashboardSections":["Overview","Chats"]}}}}},"responses":{"200":{"description":"Sub-user updated successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubUserObject"},"example":{"_id":"6650f1c2a9e4b83d2c7a1f9a","company":"6650f1c2a9e4b83d2c7a1f3c","email":"jane@chat-data.com","name":"Jane Doe","chatbotIds":[{"_id":"6650f1c2a9e4b83d2c7a1f05","name":"Support Bot"}],"permissions":["full"],"analyticsDashboardSections":["Overview","Chats"],"avatar":"","hasPassword":true,"hasGoogle":false,"createdAt":"2026-10-14T09:30:00.000Z"}}}},"400":{"description":"The sub-user could not be updated. For example: the workspace has no SSO company, `chatbotIds` is empty or contains an ID that is not a chatbot in your workspace, `name` is not a string or is longer than 100 characters, the password is too weak, `permissions` is empty or contains no valid permission, or `analyticsDashboardSections` is not an array.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubUserErrorObject"},"example":{"message":"At least one chatbot must be assigned"}}}},"401":{"description":"Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"403":{"description":"The request used a chatbot-scoped API key (`This operation requires a user-level API key, not a chatbot-specific key`, with `status: error`), or the workspace does not have the SSO Login add-on (`SSO Login is unavailable with your current plan`, with no `status` field).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubUserErrorObject"},"example":{"message":"SSO Login is unavailable with your current plan"}}}},"404":{"description":"`subUserId` is not a valid ID, or the company has no sub-user with this ID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubUserErrorObject"},"example":{"message":"Sub-user not found"}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"500":{"description":"An unexpected error occurred while processing the request; `message` contains the error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubUserErrorObject"},"example":{"message":"Internal error message"}}}}},"security":[{"HTTPBearer":[]}]},"delete":{"tags":["Sub-User Management"],"summary":"Delete a sub-user","description":"Delete a sub-user from the company. This also revokes any outstanding magic link or password setup tokens for the sub-user.\n\nRequires the SSO Login add-on (see [plans](/pricing)) and a workspace API key; without the add-on, or with a chatbot-scoped key, the request gets a 403.","operationId":"DeleteSubUser","parameters":[{"in":"path","name":"subUserId","required":true,"schema":{"type":"string"},"description":"The unique identifier of the sub-user to delete."}],"responses":{"200":{"description":"Sub-user deleted successfully.","content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["ok"]}}},"example":{"status":"ok"}}}},"400":{"description":"The workspace has no SSO company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubUserErrorObject"},"example":{"message":"No company found"}}}},"401":{"description":"Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationErrorObject"}}}},"403":{"description":"The request used a chatbot-scoped API key (`This operation requires a user-level API key, not a chatbot-specific key`, with `status: error`), or the workspace does not have the SSO Login add-on (`SSO Login is unavailable with your current plan`, with no `status` field).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubUserErrorObject"},"example":{"message":"SSO Login is unavailable with your current plan"}}}},"404":{"description":"`subUserId` is not a valid ID, or the company has no sub-user with this ID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubUserErrorObject"},"example":{"message":"Sub-user not found"}}}},"429":{"description":"The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"500":{"description":"An unexpected error occurred while processing the request; `message` contains the error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubUserErrorObject"},"example":{"message":"Internal error message"}}}}},"security":[{"HTTPBearer":[]}]}}},"components":{"schemas":{"SubUserObject":{"title":"Sub-User Object","type":"object","properties":{"_id":{"type":"string","description":"The unique identifier of the sub-user.","example":"6650f1c2a9e4b83d2c7a1f9a"},"company":{"type":"string","description":"The ID of the company this sub-user belongs to.","example":"6650f1c2a9e4b83d2c7a1f3c"},"email":{"type":"string","format":"email","description":"The sub-user's email address.","example":"jane@chat-data.com"},"name":{"type":"string","description":"The sub-user's display name.","example":"Jane Doe"},"avatar":{"type":"string","description":"URL of the sub-user's avatar image, or an empty string if none is set.","example":"https://example.blob.core.windows.net/chatfiles/6650f1c2a9e4b83d2c7a1f9a/avatar.png"},"chatbotIds":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"The chatbot ID.","example":"6650f1c2a9e4b83d2c7a1f05"},"name":{"type":"string","description":"The chatbot name.","example":"Support Bot"}}},"description":"The assigned chatbots, each with its `_id` and `name`.","example":[{"_id":"6650f1c2a9e4b83d2c7a1f05","name":"Support Bot"},{"_id":"6650f1c2a9e4b83d2c7a1f06","name":"Sales Assistant"}]},"permissions":{"type":"array","items":{"type":"string","enum":["read","train","full","admin"]},"description":"Permissions granted to this sub-user.","example":["read","train"]},"analyticsDashboardSections":{"type":"array","items":{"type":"string"},"description":"Analytics dashboard sections visible to this sub-user.","example":["Overview","Messages Timeline","Chats"]},"hasPassword":{"type":"boolean","description":"Whether the sub-user has a password configured (the actual password is never returned).","example":true},"hasGoogle":{"type":"boolean","description":"Whether the sub-user has signed in with a linked Google account (the Google ID is never returned). It stays `false` when Google sign-in is only enabled.","example":false},"createdAt":{"type":"string","format":"date-time","description":"Timestamp when the sub-user was created.","example":"2026-10-14T09:30:00.000Z"},"lastLoginAt":{"type":"string","format":"date-time","description":"Timestamp of the sub-user's last sign-in. Absent until they first sign in.","example":"2026-10-14T10:15:00.000Z"}},"required":["_id","company","email","chatbotIds","permissions","hasPassword","hasGoogle"]},"TrainChatbotSuccessRes":{"title":"Train Chatbot Success Response","required":["chatbotId","consumedCharacters","remainingCharacters","dataSources","status"],"type":"object","properties":{"chatbotId":{"title":"Chatbot ID","type":"string","description":"The unique identifier allocated to the chatbot. Use this ID in API calls about this chatbot.","example":"6650f1c2a9e4b83d2c7a1f05"},"consumedCharacters":{"title":"Consumed Training Characters","type":"number","example":156,"description":"The number of training characters charged by this call. Websites are not counted here; they are charged when they are crawled."},"remainingCharacters":{"title":"Remaining Training Characters","type":"number","example":999844,"description":"The number of training characters that remain available in your account. As long as the balance is positive, even by a single character, a training run proceeds and is limited only by the per-chatbot training character limit."},"dataSources":{"title":"List of data sources","type":"array","items":{"$ref":"#/components/schemas/ChatbotDataSource"},"description":"All data sources of the chatbot after this call. Newly added websites show 0 characters until they have been crawled. In the retrain-chatbot response, Q&A sources are listed with their `question`, `answer` and `folder` instead of a character count.","example":[{"characters":156,"type":"text"},{"name":"https://www.example.com/help/shipping","characters":0,"type":"website"}]},"status":{"type":"string","enum":["success"]}}},"CreatChatbotReq":{"title":"Create Chatbot Request","required":["model"],"type":"object","properties":{"chatbotName":{"title":"Chatbot Name","type":"string","description":"The name of the chatbot to be created. Defaults to an empty name.","example":"Support Bot"},"sourceText":{"title":"Source Text","type":"string","description":"Text data for the chatbot, subject to character limits based on your plan.\nRelevant only if the model is `custom-data-upload`.\n","example":"Our support team is available Monday to Friday, 9am to 6pm EST. Outside these hours you can email support@example.com and we'll reply the next business day."},"urlsToScrape":{"title":"URLs to Scrape","type":"array","items":{"type":"string"},"description":"A list of URLs from which Chat Data extracts text content. Because the amount of text on a website cannot be known in advance, crawling stops when either the list of URLs is exhausted or the chatbot's character limit is reached. URLs must start with `http://` or `https://`, for example `https://www.chat-data.com`.\nRelevant only if the model is `custom-data-upload`.\n","example":["https://www.example.com/help/shipping","https://www.example.com/help/returns"]},"products":{"title":"Products for Training","type":"array","items":{"type":"object","required":["id","information"],"properties":{"id":{"type":"string","description":"Unique ID for tracking the product in the knowledge base. Existing products with the same ID will be overwritten."},"information":{"type":"object","description":"Structured data of the product in a key-value format. Optimal performance is achieved with one or two levels of depth."}}},"description":"A list of products for training the chatbot.","example":[{"id":"shopify_1234567","information":{"id":"shopify_1234567","name":"Fleece Drawstring Joggers","color":"white"}}]},"qAndAs":{"title":"Q&As for Training","type":"array","items":{"type":"object","required":["question","answer"],"properties":{"question":{"type":"string","description":"The question on a specific topic."},"answer":{"type":"string","description":"The answer to the question."}}},"description":"A list of Q&As for the chatbot to learn specific topic answers. Items without both a question and an answer are skipped.","example":[{"question":"Do you ship internationally?","answer":"Yes, we ship to over 40 countries. International orders usually arrive within 7-14 business days."}]},"customBackend":{"title":"Custom Backend","type":"string","example":"https://bot.example.com/v1/chat","description":"The URL of your own backend, starting with `http://` or `https://`. Required when `model` is `custom-model`; ignored for other models."},"bearer":{"title":"Bearer","type":"string","description":"The bearer token sent to your custom backend. Only used when `model` is `custom-model`.","example":"cb_7d3f9a2e5c81b4f0"},"model":{"title":"Chatbot Model","type":"string","enum":["custom-data-upload","medical-chat-human","medical-chat-vet","custom-model"],"example":"custom-data-upload","description":"The model the chatbot uses:\n- For training with your own data: `custom-data-upload`\n- For human medical questions: `medical-chat-human`\n- For veterinary medical questions: `medical-chat-vet`\n- For a custom model: `custom-model`\n\nThere is no default; a missing or unknown value is rejected with a 400.\nFor the medical models and the custom model, `sourceText`, `urlsToScrape`, `products` and `qAndAs` are not used, though `urlsToScrape` must still contain valid URLs and `products` must still be an array.\n"}}},"RetrainChatbotReq":{"title":"Retrain Chatbot Request","required":["chatbotId"],"type":"object","properties":{"chatbotId":{"title":"Chatbot ID","type":"string","description":"The unique identifier allocated to the chatbot."},"sourceText":{"title":"Source Text","type":"string","description":"Text data intended for chatbot training, subject to character limits based on your plan. A chatbot has one text source: this value replaces the current text. Send an empty string to remove the text; omit the field to keep the current text.\n","example":"Holiday hours: our support team is closed on December 25 and January 1. Orders placed on those days ship the next business day."},"urlsToScrape":{"title":"URLs to Scrape","type":"array","items":{"type":"string"},"description":"A list of URLs provided for text content extraction. The web crawling process concludes once the list of URLs is fully processed or the chatbot's character limit is reached. URLs must begin with 'http://' or 'https://'. Applicable only to chatbots using the `custom-data-upload` model. A website that already exists with the same URL is recrawled to get the latest content.\n","example":["https://www.example.com/help/warranty","https://www.example.com/help/size-guide"]},"options":{"title":"Page Options","type":"object","description":"Configuration options that control how websites are scraped from the URLs provided in the `urlsToScrape` parameter. These options affect the content extraction process for each URL being crawled.\n","properties":{"Cookies":{"type":"string","example":"session_id=9f8e7d6c5b4a3f2e1d0c; theme=dark","description":"A list of cookies separated by semicolons that authorizes the scraping process, so that content can be accessed as if logged in. For example: \"cookie1=value1; cookie2=value2; cookie3=value3\".\n"},"extractMainContent":{"type":"boolean","description":"When enabled, automatically removes common non-content elements such as the header, footer, nav, navbar, menu, sidebar and advertisements from the webpage, without needing to specify exclude tags.\n"},"includeOnlyTags":{"type":"string","example":"div.site-content","description":"A comma-separated list of CSS selectors representing DOM elements to exclusively extract from the webpage. For example, \"div.site-content\" extracts only the content of that div.\n"},"excludeTags":{"type":"string","example":"div#sidebar","description":"A comma-separated list of CSS selectors representing DOM elements to exclude from the scraping result. For example, \"div#sidebar\" excludes the div element with the id \"sidebar\".\n"}}},"products":{"title":"Products for Training","type":"array","items":{"type":"object","required":["id","information"],"properties":{"id":{"type":"string","description":"Unique ID for tracking the product in the knowledge base. Existing products with the same ID will be overwritten."},"information":{"type":"object","description":"Structured data of the product in a key-value format. Optimal performance is achieved with one or two levels of depth."}}},"description":"A list of products for training the chatbot.","example":[{"id":"shopify_1234567","information":{"id":"shopify_1234567","name":"Fleece Drawstring Joggers","color":"white"}}]},"qAndAs":{"title":"Q&As for Training","type":"array","items":{"type":"object","required":["question","answer"],"properties":{"question":{"type":"string","description":"The question on a specific topic."},"answer":{"type":"string","description":"The answer to the question."},"folder":{"type":"string","description":"The Q&A folder to put the pair in. If omitted, the pair takes the folder shared by all existing pairs with the same question and answer or, failing that, with the same question; otherwise it goes to the standard folder."}}},"description":"A list of Q&As for the chatbot to learn specific topic answers. Items without both a question and an answer are skipped, and a pair identical to an existing one is not added twice.","example":[{"question":"Do you ship internationally?","answer":"Yes, we ship to over 40 countries. International orders usually arrive within 7-14 business days."}]},"deletes":{"title":"Knowledge Chunks to Delete","type":"array","items":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["website","q&a","product","file"],"description":"The type of the knowledge chunk to delete."}},"oneOf":[{"required":["url"],"properties":{"url":{"type":"string","description":"The URL to delete if the type is `website`."}}},{"required":["id"],"properties":{"id":{"type":"string","description":"The product ID to delete if the type is `product`."}}},{"required":["question"],"properties":{"question":{"type":"string","description":"The question to delete if the type is `q&a`. Every Q&A with this exact question is removed."}}},{"required":["name"],"properties":{"name":{"type":"string","description":"The file name to delete if the type is `file`."}}}]},"description":"A list of knowledge sources to remove from the chatbot's knowledge base. To remove the plain text source, send `sourceText` as an empty string instead.","example":[{"type":"website","url":"https://www.example.com/help/old-returns-policy"},{"type":"product","id":"shopify_7654321"}]}}},"ChatbotStyles":{"title":"Chatbot styles","description":"The appearance settings of the chat widget.","type":"object","properties":{"theme":{"title":"Theme","type":"string","enum":["light","dark"],"description":"The theme of the chatbot interface."},"buttonColor":{"title":"Button color","type":"string","description":"The color of the chat bubble button in RGB format (e.g. rgb(0, 0, 0))."},"displayName":{"title":"Display name","type":"string","description":"The display name of the chatbot. In responses, only returned when one is set."},"alignChatButton":{"title":"Align chat button","type":"string","enum":["left","right"],"description":"The alignment of the chat bubble button."},"userMessageColor":{"title":"User message color","type":"string","description":"The background color of the user's messages in RGB format (e.g. rgb(59, 129, 246))."},"actionButtonColor":{"title":"Action button color","type":"string","description":"The color of the action buttons in RGB format (e.g. rgb(59, 129, 246))."},"profilePictureFile":{"title":"Profile picture file","type":"string","description":"URL or path of the chatbot's profile picture. Only returned when one is set."},"bubblePictureFile":{"title":"Bubble picture file","type":"string","description":"URL or path of the chat bubble icon. Only returned when one is set."},"autoOpenChatWindowAfter":{"title":"Auto open chat window after","type":"number","description":"The time (in seconds) after which the chat window opens automatically. A negative value disables automatic opening."}},"example":{"theme":"dark","buttonColor":"rgb(0, 0, 0)","displayName":"Support Bot","alignChatButton":"left","userMessageColor":"rgb(59, 129, 246)","actionButtonColor":"rgb(59, 129, 246)","profilePictureFile":"/storage/public/image/avatar_6650f1c2a9e4b83d2c7a1f05.png","bubblePictureFile":"/storage/public/image/chat_icon_6650f1c2a9e4b83d2c7a1f05.png","autoOpenChatWindowAfter":3}},"ChatbotLeadsConfig":{"title":"Configuration to collect customer information","description":"The information to be collected from potential customers.","type":"object","properties":{"message":{"title":"Message","type":"string","description":"The message shown at the top of the customer information form."},"collectName":{"title":"Collect name","type":"boolean","description":"Whether the form asks for the customer's name.","example":true},"collectEmail":{"title":"Collect email","type":"boolean","description":"Whether the form asks for the customer's email address.","example":true},"collectPhone":{"title":"Collect phone","type":"boolean","description":"Whether the form asks for the customer's phone number.","example":false},"nameMessage":{"title":"Name label","type":"string","default":"Name","description":"The label of the name field. You can translate it into your own language."},"emailMessage":{"title":"Email label","type":"string","default":"Email","description":"The label of the email field. You can translate it into your own language."},"phoneMessage":{"title":"Phone label","type":"string","default":"Phone Number","description":"The label of the phone field. You can translate it into your own language."}},"example":{"message":"Let us know how to contact you.","collectName":true,"collectEmail":true,"collectPhone":false,"nameMessage":"Name","emailMessage":"Email","phoneMessage":"Phone"}},"ChatbotNotification":{"title":"Configuration for email notifications from the chatbot","description":"The configuration for sending daily email notifications.","type":"object","properties":{"enableLeadsEmail":{"type":"boolean","description":"Specifies whether daily email summaries about leads collected today should be sent to you."},"leadsEmails":{"type":"array","items":{"type":"string"},"description":"List of emails to receive information about conversations related to leads."},"enableConversationEmails":{"type":"boolean","description":"Specifies whether daily email summaries about conversations that occurred today should be sent to you."},"conversationEmails":{"type":"array","items":{"type":"string"},"description":"List of emails to receive information about today's conversations."}},"example":{"enableLeadsEmail":true,"leadsEmails":["leads1@example.com","leads2@example.com"],"enableConversationEmails":true,"conversationEmails":["conversation1@example.com","conversation2@example.com"]}},"ChatbotDataSource":{"title":"Chatbot data source","required":["type"],"type":"object","properties":{"name":{"title":"Name","type":"string","description":"The name of the document, the product ID or the URL of the website. Absent for plain text and Q&As."},"characters":{"title":"Characters","type":"number","description":"The total number of characters in this data source."},"question":{"title":"Question","type":"string","description":"The question of a `q&a` source. Only in the retrain-chatbot response."},"answer":{"title":"Answer","type":"string","description":"The answer of a `q&a` source. Only in the retrain-chatbot response."},"folder":{"title":"Folder","type":"string","description":"The folder of a `q&a` source, when it has one. Only in the retrain-chatbot response."},"type":{"title":"Type","type":"string","description":"The type of the data source (for example `website`, `text`, `product` or `q&a`)."}},"example":{"name":"https://www.example.com/help/shipping","characters":10000,"type":"website"}},"Customer":{"title":"Customer","description":"A lead. Fields that are not set are omitted, and the answers of a custom lead form are included as extra top-level fields.","type":"object","required":["createdAt"],"properties":{"leadId":{"title":"Lead ID","type":"string","description":"The unique identifier of the lead (UUID)."},"name":{"title":"Name","type":"string","description":"The name provided by the customer."},"email":{"title":"Email","type":"string","description":"The email address provided by the customer."},"phone":{"title":"Phone","type":"string","description":"The phone number provided by the customer."},"psid":{"title":"Page Scoped User ID","type":"string","description":"The page-scoped user ID of the customer, if the customer is from Messenger."},"ig_username":{"title":"Instagram username","type":"string","description":"The Instagram username of the customer, if the customer is from Instagram."},"username":{"title":"Username","type":"string","description":"Slack or Telegram username. A platform-specific identifier, distinct from `ig_username` (Instagram) and `psid` (Messenger)."},"info":{"title":"Info","type":"string","description":"Additional information stored on the lead."},"source":{"title":"Source","type":"string","description":"The source the customer was acquired from. Only returned by get-customers.","enum":["widget","iframe","site","api","Whatsapp","WhatsappWebAPI","Messenger","Instagram","Telegram","Line","Slack","Discord","Workflow Studio","cron-trigger"]},"ipAddress":{"title":"IP Address","type":"string","description":"The IP address of the customer. Only returned by get-customers."},"userCountry":{"title":"User Country","type":"string","description":"The 2-letter ISO country code of the customer, based on an IP address lookup (`Unknown` when it could not be resolved). Only returned by get-customers."},"createdAt":{"title":"Created at","type":"number","description":"When the customer's information was submitted, in milliseconds since the Unix epoch."}},"example":{"leadId":"8d0c2b6e-4f1a-4b7c-9e3d-2a5f6b7c8d9e","name":"Jane Doe","email":"jane@chat-data.com","source":"widget","phone":"+14155550123","ipAddress":"203.0.113.42","userCountry":"US","createdAt":1791970200000}},"faqLink":{"title":"Links for Frequently Asked Questions","type":"object","properties":{"text":{"title":"Text","type":"string","description":"The descriptive text for the link.\n"},"link":{"title":"Link","type":"string","description":"The URL that users are taken to when they click the link.\n"}},"example":{"text":"How to train your chatbot","link":"https://cookbook.chat-data.com/docs/train-with-your-data"}},"ChatbotObject":{"title":"Chatbot","required":["chatbotId","chatbotName","visibility","createdAt","onlyAllowOnAddedDomains","domains","basePrompt","rateLimitPoints","rateLimitTimeframe","rateLimitMessage","suggestedMessages","initialMessages","styles","model","baseModel","numberOfConversations","dataSources","status","temperature","collectedCustomerInformation","leadsConfig"],"type":"object","properties":{"chatbotId":{"title":"Chatbot ID","type":"string","description":"The unique identifier allocated to the chatbot. Use this ID in API calls about this chatbot.","example":"6650f1c2a9e4b83d2c7a1f05"},"chatbotName":{"title":"Chatbot Name","type":"string","description":"The name of the chatbot.","example":"Support Bot"},"visibility":{"title":"Visibility","type":"string","enum":["private","public"],"description":"The visibility of the chatbot. It controls whether your chatbot is accessible to others."},"createdAt":{"title":"Created At","type":"number","description":"When the chatbot was created, in milliseconds since the Unix epoch.","example":1791970200000},"lastTrainedAt":{"title":"Last trained time","type":"number","description":"When the chatbot was last trained, in milliseconds since the Unix epoch. Absent if it has never been trained.","example":1791970200000},"onlyAllowOnAddedDomains":{"title":"Only allow on added domains","type":"boolean","description":"Whether the chatbot can be embedded (iframe or widget) on other websites; `false` disables embedding. Allowed domains are set by `domains`."},"domains":{"title":"Domains","type":"array","items":{"type":"string"},"description":"The domains on which the iframe and widget are allowed.","example":["example.com","chat.example.com"]},"disallowedUrls":{"title":"Disallowed URLs","type":"array","items":{"type":"string"},"description":"Pages on which the chat widget is not shown.","example":["https://www.example.com/checkout"]},"basePrompt":{"title":"Base prompt","type":"string","description":"The base prompt (instructions) for the chatbot.","example":"You are a friendly support assistant for Example Inc. Answer only from the provided knowledge base and keep replies under 120 words."},"imageDescriptionPrompt":{"title":"Image description prompt","type":"string","description":"The prompt used to describe images that users attach to their messages.","example":"Describe the image in detail, including any visible text."},"rateLimitPoints":{"title":"Rate limit points","type":"number","description":"The maximum number of messages one device can send every `rateLimitTimeframe` seconds. Each message counts as one here, however many message credits its model consumes.","example":20},"rateLimitTimeframe":{"title":"Rate limit timeframe","type":"number","description":"The time window, in seconds, to which the `rateLimitPoints` message limit applies.","example":240},"rateLimitMessage":{"title":"Rate limit message","type":"string","description":"The error message shown to the user when the conversation is rate limited.","example":"Too many messages in a row. Please wait a few minutes and try again."},"suggestedMessages":{"title":"Suggested messages","type":"array","items":{"type":"string"},"description":"Array of suggested messages shown in the chatbot.","example":["What are your opening hours?","How do I track my order?"]},"initialMessages":{"title":"Initial messages","type":"array","items":{"type":"string"},"description":"Array of initial messages the chatbot shows when a conversation starts.","example":["Hi! How can I help you today?"]},"styles":{"$ref":"#/components/schemas/ChatbotStyles"},"model":{"title":"Chatbot Model","type":"string","enum":["custom-data-upload","medical-chat-human","medical-chat-vet","custom-model"],"description":"The model the chatbot uses:\n- For training with your own data: `custom-data-upload`\n- For human medical questions: `medical-chat-human`\n- For veterinary medical questions: `medical-chat-vet`\n- For a custom model: `custom-model`\n"},"baseModel":{"title":"Base Model for RAG","type":"string","enum":["gpt-4o-mini","gpt-4o","gpt-4","gpt-4.1-nano","gpt-4.1-mini","gpt-4.1","gpt-5-nano","gpt-5-mini","gpt-5","gpt-5.1","gpt-5.2","gpt-5.6-sol","gpt-5.6-terra","gpt-5.6-luna","gpt-6-astra","gpt-6.1-sol","gpt-6-luna","gpt-5.5","gpt-5.4","gpt-5.4-nano","gpt-5.4-mini","gpt-o1","gpt-o3-mini","gpt-o3","gpt-o4-mini","claude-4-5-sonnet","claude-4-6-sonnet","claude-4-5-haiku","claude-4-opus","claude-4.1-opus","claude-4.5-opus","claude-4.6-opus","claude-5-opus","claude-5-sonnet","claude-5-5-opus","claude-5-5-sonnet","claude-5-5-haiku","gemini-3.0-flash","gemini-3.1-flash","gemini-3.5-flash-lite","gemini-3.7-flash","gemini-2.5-pro","gemini-3.0-pro","gemini-3.1-pro","deepseek-r1","deepseek-v3.2","mancer-deepseek-v4-flash"],"description":"The large language model (OpenAI GPT, Anthropic Claude, Google Gemini or DeepSeek) used in our RAG processing pipeline."},"numberOfConversations":{"title":"Number of conversations","type":"number","description":"The number of conversations with the chatbot.","example":100},"dataSources":{"title":"List of data sources","type":"array","items":{"$ref":"#/components/schemas/ChatbotDataSource"},"description":"A list of all data sources used to train the chatbot, along with the number of characters in each data source.","example":[{"name":"https://www.example.com/help/shipping","characters":10000,"type":"website"}]},"status":{"title":"Status","type":"number","minimum":0,"maximum":100,"example":100,"description":"The training progress of the chatbot. 100 means that the training has finished."},"temperature":{"title":"Temperature","type":"number","minimum":0,"maximum":1,"example":0,"description":"The temperature of the AI model, in the range [0, 1]."},"collectedCustomerInformation":{"title":"Collected customer information","type":"array","items":{"type":"object","required":["createdAt"],"properties":{"name":{"type":"string","description":"One identifier of the customer: the Messenger page-scoped ID if set, otherwise the phone number, otherwise the email address, otherwise the name."},"source":{"type":"string","description":"The source the customer was acquired from (for example `widget` or `api`)."},"createdAt":{"type":"string","format":"date-time","description":"When the customer's information was submitted (ISO 8601)."}}},"description":"The customers (leads) collected by the chatbot. Use [Get customers](/api-reference/get-customers) for their full details.","example":[{"name":"jane@chat-data.com","source":"widget","createdAt":"2026-10-14T09:30:00.000Z"}]},"storeChat":{"title":"Store Chat History","type":"boolean","example":true,"default":true,"description":"Indicates whether chat history is stored on our server. All chatbot models, including medical-chat-human and medical-chat-vet, start with storage enabled by default. Storage can be disabled for any model."},"trackIpAddress":{"title":"Track IP Address","type":"boolean","example":true,"default":true,"description":"Indicates whether IP addresses are stored for conversations and leads. This setting works independently of chat history storage, so IP addresses can be tracked even when chat history storage is disabled."},"calendar":{"title":"Calendly settings","type":"object","description":"The Calendly booking button settings.","properties":{"showCalendar":{"type":"boolean","description":"Whether the Calendly booking button is displayed in the chatbot widget or iframe."},"calendarUrl":{"type":"string","description":"The Calendly URL where users can schedule appointments."},"calendarMessage":{"type":"string","description":"The label of the booking button."}},"example":{"showCalendar":true,"calendarUrl":"https://calendly.com/jane-doe/30min","calendarMessage":"Book a demo"}},"calCom":{"title":"Cal.com settings","type":"object","description":"The Cal.com booking button settings.","properties":{"showCalendar":{"type":"boolean","description":"Whether the Cal.com booking button is displayed."},"username":{"type":"string","description":"The Cal.com username (or username/event path) to book with."},"calendarMessage":{"type":"string","description":"The label of the booking button."},"hideEventTypeDetails":{"type":"boolean","description":"Whether the event type details are hidden in the booking view."},"brandColor":{"type":"string","description":"The brand color of the booking view."},"layout":{"type":"string","description":"The layout of the booking view (for example `month`)."}},"example":{"showCalendar":false,"username":"jane-doe/30min","calendarMessage":"Book a demo","hideEventTypeDetails":false,"brandColor":"#292929","layout":"month"}},"inputPlaceholderMsg":{"title":"Input placeholder","type":"string","description":"The placeholder text of the message input.","example":"Message..."},"enableBouncingAnimation":{"title":"Enable bouncing animation","type":"boolean","default":true,"description":"Whether the chat bubble bounces at the start of a session to attract attention."},"enableBubbleSound":{"title":"Enable bubble sound","type":"boolean","description":"Whether a sound plays when the initial-message bubble pops up.","example":true},"bubbleSize":{"title":"Bubble size","type":"number","description":"The size of the chat bubble button, in pixels.","example":54},"padding":{"title":"Bubble padding","type":"object","description":"The distance of the chat bubble from the edges of the page, in pixels.","properties":{"x":{"type":"number","description":"The horizontal distance, in pixels."},"y":{"type":"number","description":"The vertical distance, in pixels."}},"example":{"x":16,"y":16}},"ignoreDataSource":{"title":"Ignore Data Source","type":"boolean","default":false,"description":"Whether your uploaded data should be ignored when the chatbot responds. If set to true, the chatbot answers like a general-purpose AI chatbot without your knowledge base. This option applies to chatbots based on the `custom-data-upload` model."},"leadsConfig":{"$ref":"#/components/schemas/ChatbotLeadsConfig"},"notification":{"$ref":"#/components/schemas/ChatbotNotification"},"webhooks":{"type":"array","description":"The chatbot's webhook endpoints.","items":{"$ref":"#/components/schemas/WebhookPayload"}},"team":{"type":"array","description":"The workspace members who can access the chatbot.","items":{"type":"object","properties":{"userId":{"type":"string","description":"The member's user ID."},"email":{"type":"string","description":"The member's email address."},"name":{"type":"string","description":"The member's name."},"permissions":{"type":"array","items":{"type":"string","enum":["read","train","full","admin"]},"description":"The member's permissions on the chatbot."},"role":{"type":"string","enum":["Owner","Member"],"description":"`Owner` for workspace owners, otherwise `Member`."},"workspaceRole":{"type":"string","enum":["owner","admin","full","train","read"],"description":"The member's workspace role."},"joinTime":{"type":"string","format":"date-time","description":"When the member joined the workspace (ISO 8601)."},"source":{"type":"string","enum":["workspace","chatbot"],"description":"`workspace` when the member can access every chatbot in the workspace, `chatbot` when access was granted for selected chatbots."}}},"example":[{"userId":"6650f1c2a9e4b83d2c7a1e11","email":"jane@example.com","name":"Jane Doe","permissions":["admin","full","train","read"],"role":"Owner","workspaceRole":"owner","joinTime":"2026-10-14T09:30:00.000Z","source":"workspace"}]},"toolsParams":{"type":"array","description":"The other chatbots this chatbot can call as tools.","items":{"type":"object","properties":{"chatbotId":{"type":"string","description":"The ID of the chatbot called as a tool."},"operationId":{"type":"string","description":"The tool name."},"description":{"type":"string","description":"When the tool is used."},"bearer":{"type":"string","description":"The API key used to call the chatbot."}}},"example":[]},"lastMessageAt":{"title":"Last message at","type":"number","description":"When the chatbot last received a message, in milliseconds since the Unix epoch.","example":1791970320000},"customBackend":{"title":"Custom Backend","type":"string","example":"https://bot.example.com/v1/chat","description":"The URL of the chatbot's custom backend. Only returned when the chatbot uses a custom backend."},"bearer":{"title":"Bearer","type":"string","description":"The bearer token used to authenticate against your custom backend. Only returned when one is set.","example":"cb_7d3f9a2e5c81b4f0"}}},"ListOfChatbotsRes":{"title":"List of chatbots response","required":["status","chatbots"],"type":"object","properties":{"status":{"type":"string","enum":["success"]},"chatbots":{"title":"List of chatbots","type":"array","items":{"$ref":"#/components/schemas/ChatbotObject"},"description":"The list of all chatbots in your workspace."}}},"UpdateChatbotSettingReq":{"title":"Update chatbot setting","required":["chatbotId"],"type":"object","properties":{"chatbotId":{"title":"Chatbot ID","type":"string","description":"The unique identifier allocated to the chatbot.","example":"6650f1c2a9e4b83d2c7a1f05"},"chatbotName":{"title":"Chatbot Name","type":"string","description":"The new name of the chatbot.","example":"Support Bot"},"basePrompt":{"title":"Base prompt","type":"string","description":"The base prompt (instructions) for the chatbot.","example":"You are a friendly support assistant for Example Inc. Answer only from the provided knowledge base and keep replies under 120 words."},"initialMessages":{"title":"Initial messages","type":"array","items":{"type":"string"},"description":"Array of initial messages the chatbot shows when a conversation starts.","example":["Hi! How can I help you today?"]},"suggestedMessages":{"title":"Suggested messages","type":"array","items":{"type":"string"},"description":"Array of suggested messages shown in the chatbot.","example":["What are your opening hours?","How do I track my order?"]},"visibility":{"title":"Visibility","type":"string","enum":["private","public"],"description":"The visibility of the chatbot. It controls whether your chatbot is accessible to others."},"onlyAllowOnAddedDomains":{"title":"Only allow on added domains","type":"boolean","description":"Whether the chatbot can be embedded (iframe or widget) on other websites; `false` disables embedding. Allowed domains are set by `domains`."},"domains":{"title":"Domains","type":"array","items":{"type":"string"},"description":"The domains on which the iframe and widget are allowed. Replaces the current list.","example":["example.com","chat.example.com"]},"disallowedUrls":{"title":"Disallowed URLs","type":"array","items":{"type":"string"},"description":"Pages on which the chat widget is not shown. Replaces the current list.","example":["https://www.example.com/checkout"]},"rateLimitPoints":{"title":"Rate limit points","type":"number","description":"The maximum number of messages one device can send every `rateLimitTimeframe` seconds. Each message counts as one here, however many message credits its model consumes.","example":20},"rateLimitTimeframe":{"title":"Rate limit timeframe","type":"number","description":"The time window, in seconds, to which the `rateLimitPoints` message limit applies.","example":240},"rateLimitMessage":{"title":"Rate limit message","type":"string","description":"The error message shown to the user when the conversation is rate limited.","example":"Too many messages in a row. Please wait a few minutes and try again."},"baseModel":{"title":"Base Model","type":"string","enum":["gpt-4o-mini","gpt-4o","gpt-4","gpt-4.1-nano","gpt-4.1-mini","gpt-4.1","gpt-5-nano","gpt-5-mini","gpt-5","gpt-5.1","gpt-5.2","gpt-5.6-sol","gpt-5.6-terra","gpt-5.6-luna","gpt-6-astra","gpt-6.1-sol","gpt-6-luna","gpt-5.5","gpt-5.4","gpt-5.4-nano","gpt-5.4-mini","gpt-o1","gpt-o3-mini","gpt-o3","gpt-o4-mini","claude-4-5-sonnet","claude-4-6-sonnet","claude-4-5-haiku","claude-4-opus","claude-4.1-opus","claude-4.5-opus","claude-4.6-opus","claude-5-opus","claude-5-sonnet","claude-5-5-opus","claude-5-5-sonnet","claude-5-5-haiku","gemini-3.0-flash","gemini-3.1-flash","gemini-3.5-flash-lite","gemini-3.7-flash","gemini-2.5-pro","gemini-3.0-pro","gemini-3.1-pro","deepseek-r1","deepseek-v3.2","mancer-deepseek-v4-flash"],"description":"The large language model (OpenAI GPT, Anthropic Claude, Google Gemini or DeepSeek) used in our RAG processing pipeline. In a HIPAA workspace, models not covered by a BAA are rejected."},"temperature":{"title":"Temperature","type":"number","minimum":0,"maximum":1,"example":0,"description":"The temperature of the AI model, in the range [0, 1]."},"storeChat":{"title":"Store Chat History","type":"boolean","example":true,"default":true,"description":"Indicates whether chat history is stored on our server. All chatbot models, including medical-chat-human and medical-chat-vet, start with storage enabled by default. Storage can be disabled for any model."},"qALinks":{"type":"array","items":{"$ref":"#/components/schemas/faqLink"},"description":"Links to frequently asked questions pages shown in the chatbot. Replaces the current links; items without both `text` and `link` are dropped."},"showCalendar":{"title":"Show Calendar","type":"boolean","default":false,"description":"Specifies whether the Calendly booking button should be displayed in the chatbot widget or iframe."},"calendarUrl":{"title":"Calendly URL","type":"string","example":"https://calendly.com/jane-doe/30min","description":"The Calendly URL where users can schedule appointments.\n"},"calendarMessage":{"title":"Calendly message","type":"string","example":"Book a demo","description":"The message to display for appointment scheduling."},"calCom":{"title":"Cal.com settings","type":"object","description":"The Cal.com booking button settings. The object replaces the current settings as a whole.","properties":{"showCalendar":{"type":"boolean","description":"Whether the Cal.com booking button is displayed."},"username":{"type":"string","description":"The Cal.com username (or username/event path) to book with."},"calendarMessage":{"type":"string","description":"The label of the booking button."},"hideEventTypeDetails":{"type":"boolean","description":"Whether the event type details are hidden in the booking view."},"brandColor":{"type":"string","description":"The brand color of the booking view."},"layout":{"type":"string","description":"The layout of the booking view (for example `month`)."}},"example":{"showCalendar":true,"username":"jane-doe/30min","calendarMessage":"Book a demo","hideEventTypeDetails":false,"brandColor":"#292929","layout":"month"}},"enableBouncingAnimation":{"title":"Enable bouncing animation","type":"boolean","default":true,"description":"Whether the chat bubble bounces at the start of a session to attract attention."},"enableBubbleSound":{"title":"Enable bubble sound","type":"boolean","description":"Whether a sound plays when the initial-message bubble pops up."},"bubbleSize":{"title":"Bubble size","type":"number","exclusiveMinimum":0,"description":"The size of the chat bubble button, in pixels. Values that are not positive numbers are ignored.","example":54},"inputPlaceholderMsg":{"title":"Input placeholder","type":"string","description":"The placeholder text of the message input.","example":"Message..."},"rerank":{"title":"Rerank","type":"boolean","description":"Whether retrieved knowledge base chunks are reranked before the chatbot answers. Reranking costs extra message credits."},"sources":{"title":"Sources","type":"object","description":"Whether and how the sources used for an answer are shown under it.","properties":{"enable":{"type":"boolean","description":"Whether sources are shown."},"label":{"type":"string","description":"The label shown above the sources."}},"example":{"enable":true,"label":"Sources"}},"footer":{"title":"Footer","type":"string","description":"Text shown at the bottom of the chat widget.","example":"Replies are generated by AI and may contain mistakes."},"ignoreDataSource":{"title":"Ignore Data Source","type":"boolean","default":false,"description":"Whether your uploaded data should be ignored when the chatbot responds. If set to true, the chatbot answers like a general-purpose AI chatbot without your knowledge base. This option applies to chatbots based on the `custom-data-upload` model."},"leadsConfig":{"$ref":"#/components/schemas/ChatbotLeadsConfig"},"styles":{"$ref":"#/components/schemas/ChatbotStyles"}}},"AddWebhookReq":{"title":"Add a webhook","required":["chatbotId","url","event"],"type":"object","properties":{"chatbotId":{"title":"Chatbot ID","type":"string","description":"The ID of the chatbot the webhook belongs to.","example":"6650f1c2a9e4b83d2c7a1f05"},"url":{"title":"URL","type":"string","description":"The URL endpoint that the chatbot delivers events to.","example":"https://example.com/webhooks/chat-data"},"event":{"title":"Event","type":"string","enum":["chat","live-chat-escalation","lead-submission","user-online","user-offline"],"description":"The type of event the webhook subscribes to. See [Webhooks](/api-reference/webhooks) for the `chat`, `live-chat-escalation` and `lead-submission` bodies. `user-online` and `user-offline` fire when the user joins or leaves a live chat session and carry `chatbot_id`, `chatbot_name`, `conversation_id` and, when known, the user's `name`, `email`, `phone`, `source` and `user_uuid`. If a webhook with this `url` already exists, the event is added to its subscriptions."},"contentType":{"title":"Content type","type":"string","enum":["text/plain","application/json"],"default":"text/plain","description":"The `Content-Type` of the deliveries. Endpoints on `hook.make.com`, `hook.*.make.com`, `n8n.cloud` and `*.n8n.cloud` always receive `text/plain`. Re-adding an existing `url` updates its content type."}}},"deleteWebhookReq":{"title":"Delete a webhook endpoint","description":"The webhook endpoint with the given URL is deleted, together with all of its event subscriptions.","required":["chatbotId","url"],"type":"object","properties":{"chatbotId":{"title":"Chatbot ID","type":"string","description":"The ID of the chatbot the webhook belongs to.","example":"6650f1c2a9e4b83d2c7a1f05"},"url":{"title":"URL","type":"string","description":"The URL endpoint that the chatbot delivers events to.","example":"https://example.com/webhooks/chat-data"}}},"WebhookPayload":{"title":"Webhook","required":["endpoint","events","secret","enable"],"type":"object","properties":{"endpoint":{"title":"Endpoint","type":"string","description":"The URL endpoint that the chatbot delivers events to.","example":"https://example.com/webhooks/chat-data"},"events":{"title":"Events","type":"array","items":{"type":"string","enum":["chat","live-chat-escalation","lead-submission","user-online","user-offline"]},"description":"An array of events that the webhook subscribes to.\nSee [Webhooks](/api-reference/webhooks) for the event bodies.\n"},"secret":{"title":"Signing Secret","type":"string","description":"The secret used to sign deliveries. The `x-chat-data-hmac-sha256` header carries the Base64 HMAC-SHA256 of the raw request body, keyed with this secret.","example":"4f9a2c7e1b8d3f6a0c5e9b2d7a1f4c8e3b6d9f2a5c8e1b4d7f0a3c6e9b2d5f8a"},"enable":{"title":"Enable Webhook","type":"boolean","description":"Indicates whether the webhook is turned on.","example":true},"contentType":{"title":"Content type","type":"string","enum":["text/plain","application/json"],"description":"The `Content-Type` of the deliveries.","example":"text/plain"}}},"DeliveredChatWebhookPayload":{"title":"Delivered Chat Webhook Payload","example":{"chatbot_id":"6650f1c2a9e4b83d2c7a1f05","conversation_id":"3f2b8c1e-9a4d-4e7b-8c2a-5d1e6f7a8b9c","messages":[{"role":"user","content":"What are your opening hours?"}],"answer":{"role":"assistant","content":"We are open Monday to Friday, 9am to 6pm."},"source":"widget","cost_credits":1,"client_ip":"203.0.113.42","is_live_chat":false,"conversation_url":"https://chat.example.com/conversation/QVuByBn5KKcSMnl8s8OZ0Z29X3zvoz-auadhozRjyTIU1pqa5b0EfSncMqr66awipPKWp79_stvOZu_LVd6VQO7vEiWGHRk1Sa_QlDpddCggmKQTVF2oslRss_e2p7S_G0rrKKgMluXg1Ale1SwZjIl5hEzDpRdoALLCnw0G80iqkguX32-C7OuDiXdzQUmnzBegtdnlhTmUhj3m3dmvPy6KabXzYrn4db-42FmntSSK5-9m"},"description":"Body delivered to a `chat`-event webhook endpoint after a chat turn\ncompletes. This is distinct from `WebhookPayload`, which describes the\nwebhook registration. Only the fields documented here are stable. The\nbody may also carry other fields, so rely only on the ones listed here.","type":"object","required":["chatbot_id","conversation_id","messages","answer","source"],"properties":{"chatbot_id":{"type":"string","description":"ID of the chatbot that produced the response."},"conversation_id":{"type":"string","description":"UUID of the conversation the message belongs to."},"messages":{"type":"array","description":"Conversation messages preceding the response.","items":{"$ref":"#/components/schemas/Message"}},"answer":{"type":"object","description":"The assistant message produced by this turn.","example":{"role":"assistant","content":"We are open Monday to Friday, 9am to 6pm."}},"source":{"type":"string","description":"Origin of the request (for example `widget`, `iframe`, `site` or `api`)."},"cost_credits":{"type":"number","description":"Credits charged for this turn."},"regenerate":{"type":"boolean","enum":[true],"description":"Present and `true` only when the `/chat` request used\n`skipCache: true` (a regenerated answer); absent otherwise. To\ntell regenerated events apart, check `payload.regenerate === true`."},"client_ip":{"type":"string","description":"Caller IP, included only when the chatbot has `trackIpAddress` enabled."},"is_live_chat":{"type":"boolean","description":"Whether the turn was handled by a live human agent."},"conversation_url":{"type":"string","description":"URL to view the conversation. Only present when the conversation portal is enabled."}}},"UpdateChatbotProfilePictureReq":{"type":"object","properties":{"image":{"title":"Picture file","type":"string","format":"binary","description":"The profile picture to upload. It must be a square PNG, JPEG, GIF or WebP image of up to 1 MB.","example":"profile-picture.png"}}},"Message":{"title":"Message","description":"A stored message. Messages can carry further internal fields; rely only on the ones documented here.","type":"object","required":["role","content"],"properties":{"role":{"title":"Role","type":"string","enum":["user","assistant","human"],"description":"The role of the message sender (`user`, `assistant`, or `human` for a live chat agent)."},"content":{"title":"Content","type":"string","description":"The text content of the message."},"isTranscript":{"title":"Is transcript","type":"boolean","description":"Indicates whether the message is a transcript of the realtime voice-to-voice interaction."},"upvote":{"title":"Upvote","type":"boolean","description":"Indicates whether the message is upvoted by the user."},"name":{"title":"Name","type":"string","description":"The name of the agent who sent the message, if the role is `human`."},"avatar":{"title":"Avatar","type":"string","description":"The avatar image URL of the agent who sent the message, if the role is `human`."},"timestamp":{"title":"Timestamp","type":"string","format":"date-time","description":"When the message was sent (ISO 8601)."},"mid":{"title":"Message ID","type":"string","description":"The ID of the message."},"reasoning":{"title":"Reasoning","type":"string","description":"The model's reasoning for an assistant message, when it was recorded."},"downvoteFeedback":{"title":"Downvote feedback","type":"string","description":"The user's feedback when they downvoted the message."},"read":{"title":"Read","type":"boolean","description":"Indicates whether the message has been read by the user or the agent."},"files":{"type":"array","description":"The files attached to the message.","items":{"type":"object","required":["name","type","url"],"properties":{"name":{"type":"string","description":"The name of the file."},"type":{"type":"string","description":"The MIME type of the file."},"url":{"type":"string","format":"uri","description":"The URL of the file in Azure Blob Storage. Use the `/get-sas-token` endpoint to get a URL with a SAS token for public access."}}}},"audioUrl":{"title":"Audio URL","type":"string","description":"The URL of the audio file in Azure Blob Storage, when the message is a transcript of an audio input. Use the `/get-sas-token` endpoint to get a URL with a SAS token for public access."},"score":{"title":"Score","type":"number","minimum":0,"maximum":1,"description":"The level of confidence in the generated answer. If no score is present, the answer was not derived from search results."}}},"MessageInput":{"title":"Message","type":"object","required":["role","content"],"properties":{"role":{"title":"Role","type":"string","enum":["user","assistant"],"description":"The role of the message sender (`user` or `assistant`)."},"content":{"title":"Content","type":"string","description":"The text content of the message."},"files":{"type":"array","description":"An optional array of file objects attached to the message. Only the chatbot's allowed number of files is kept on the last message (3 by default); extra files are dropped.","items":{"type":"object","required":["name","type","url"],"properties":{"name":{"type":"string","description":"The name of the attached file."},"type":{"type":"string","description":"The MIME type of the file, for example `image/png` or `application/pdf`. Images (`image/*`) are passed to the model as images. Other files are downloaded and parsed to text by the type the file host reports; PDF, DOCX, HTML, plain text and CSV are supported.","example":"application/pdf"},"url":{"type":"string","format":"uri","description":"The publicly accessible URL where the file is hosted by you."},"content":{"type":"string","description":"The text content of a non-image file. If this field is non-empty, it is used directly without downloading or parsing the file. If it is empty, the file is downloaded and parsed to text when the file type is supported. Files larger than the chatbot's file size limit (3 MB by default) cannot be downloaded, so parse them yourself and provide their content in this field."}}}}}},"SendConfidenceScoreReq":{"title":"Send Confidence Score Request","type":"object","required":["messages","chatbotId"],"properties":{"messages":{"title":"List of Message Objects","type":"array","items":{"$ref":"#/components/schemas/MessageInput"},"description":"The messages of the conversation, oldest first. On this endpoint, non-image `files` are not downloaded or parsed (only a provided `content` is used), and extra files are not dropped.","example":[{"role":"assistant","content":"How can I help you?"},{"role":"user","content":"How does Chat Data work?"}]},"baseModel":{"title":"Chatbot Base Model","type":"string","enum":["gpt-4o-mini","gpt-4o","gpt-4","gpt-4.1-nano","gpt-4.1-mini","gpt-4.1","gpt-5-nano","gpt-5-mini","gpt-5","gpt-5.1","gpt-5.2","gpt-5.6-sol","gpt-5.6-terra","gpt-5.6-luna","gpt-6-astra","gpt-6.1-sol","gpt-6-luna","gpt-5.5","gpt-5.4","gpt-5.4-nano","gpt-5.4-mini","gpt-o1","gpt-o3-mini","gpt-o3","gpt-o4-mini","claude-4-5-sonnet","claude-4-6-sonnet","claude-4-5-haiku","claude-4-opus","claude-4.1-opus","claude-4.5-opus","claude-4.6-opus","claude-5-opus","claude-5-sonnet","claude-5-5-opus","claude-5-5-sonnet","claude-5-5-haiku","gemini-3.0-flash","gemini-3.1-flash","gemini-3.5-flash-lite","gemini-3.7-flash","gemini-2.5-pro","gemini-3.0-pro","gemini-3.1-pro","deepseek-r1","deepseek-v3.2","mancer-deepseek-v4-flash"],"description":"Overrides the chatbot's `baseModel` setting when processing the RAG context for this request."},"chatbotId":{"type":"string","description":"The ID of the chatbot.","example":"6650f1c2a9e4b83d2c7a1f05"}}},"SendQueryKnowledgeBaseReq":{"title":"Query Knowledge Base Request","type":"object","required":["query"],"properties":{"query":{"description":"The text used to search the knowledge base by vector (cosine) similarity.","type":"string","title":"Query","example":"What are your opening hours?"},"count":{"title":"Context Count","type":"number","default":5,"description":"The minimum number of context segments to select when available. More are added until a minimum token budget is met, then the list is trimmed to a maximum token budget, so the result can hold more or fewer. Only segments with a positive cosine similarity to the query are returned."}}},"SendMessageReq":{"title":"Send Messages Request","type":"object","required":["messages","chatbotId"],"properties":{"messages":{"title":"List of Message Objects","type":"array","items":{"$ref":"#/components/schemas/MessageInput"},"description":"The messages of the conversation, oldest first. Every role must be `user` or `assistant`, and the last message must not be empty.","example":[{"role":"assistant","content":"Hi! How can I help you today?"},{"role":"user","content":"What are your opening hours?"}]},"chatbotId":{"type":"string","description":"The ID of the chatbot.","example":"6650f1c2a9e4b83d2c7a1f05"},"includeReasoning":{"title":"Include Reasoning","type":"boolean","example":false,"description":"Whether to include reasoning in the response. This parameter overrides the chatbot's reasoning settings. If true, the reasoning is included at the beginning of the response within a `<think>` tag, for example `<think>{reasoning}</think>{response}`."},"baseModel":{"title":"Chatbot Base Model","type":"string","enum":["gpt-4o-mini","gpt-4o","gpt-4","gpt-4.1-nano","gpt-4.1-mini","gpt-4.1","gpt-5-nano","gpt-5-mini","gpt-5","gpt-5.1","gpt-5.2","gpt-5.6-sol","gpt-5.6-terra","gpt-5.6-luna","gpt-6-astra","gpt-6.1-sol","gpt-6-luna","gpt-5.5","gpt-5.4","gpt-5.4-nano","gpt-5.4-mini","gpt-o1","gpt-o3-mini","gpt-o3","gpt-o4-mini","claude-4-5-sonnet","claude-4-6-sonnet","claude-4-5-haiku","claude-4-opus","claude-4.1-opus","claude-4.5-opus","claude-4.6-opus","claude-5-opus","claude-5-sonnet","claude-5-5-opus","claude-5-5-sonnet","claude-5-5-haiku","gemini-3.0-flash","gemini-3.1-flash","gemini-3.5-flash-lite","gemini-3.7-flash","gemini-2.5-pro","gemini-3.0-pro","gemini-3.1-pro","deepseek-r1","deepseek-v3.2","mancer-deepseek-v4-flash"],"description":"Overrides the chatbot's `baseModel` setting when processing the RAG context for this request."},"basePrompt":{"title":"Chatbot Base Prompt","type":"string","example":"You are a friendly support assistant for Example Inc. Answer only from the provided knowledge base and keep replies under 120 words.","description":"Overrides the chatbot's `basePrompt` when processing the RAG context for this request."},"stream":{"title":"Stream","type":"boolean","default":false,"description":"Whether to stream back partial progress or wait for the full response."},"openAIFormat":{"title":"OpenAI Format","type":"boolean","default":false,"description":"When set to true, the response is formatted to be compatible with OpenAI's `/chat/completions` API format. Non-streaming responses return a JSON object matching OpenAI's completion format; streaming responses return Server-Sent Events in OpenAI's chunk format."},"appendMessages":{"title":"Append Messages","type":"boolean","default":false,"description":"If `true`, `messages` must contain exactly one `user` message, which is appended to the stored messages of the conversation with the same `conversationId`. If `false`, it is assumed that the `messages` parameter contains the entire message history."},"conversationId":{"title":"Conversation ID","type":"string","description":"ID of the current conversation. If omitted, the chatbot generates one, which is not returned in the response.","example":"3f2b8c1e-9a4d-4e7b-8c2a-5d1e6f7a8b9c"},"skipCache":{"title":"Skip Response Cache","type":"boolean","default":false,"description":"When `true`, bypasses the response cache lookup for this request and runs the LLM pipeline normally. On success, the new response overwrites the prior cached entry under the same cache key. This is useful for regenerating answers when the cached response is no longer wanted.\n\nOnly the literal boolean `true` enables this behavior — loose-truthy values (`\"true\"`, `1`) are treated as `false` to prevent accidental cache bypass.\n\n**Side effects are unchanged from a normal send:** credits are charged, rate limits apply, AI actions fire, and the `chat` webhook emits (the only webhook this endpoint sends). Its payload carries an additional `regenerate: true` field so receivers can dedupe.\n\n**Persisted conversation history:** when `skipCache: true` and the persisted conversation's last message is an assistant message, that trailing assistant message is replaced (not appended after) by the newly generated response. If the last persisted message is a user message, the new response is appended normally. Callers managing their own conversation state typically send the trimmed history along with `skipCache: true` (or use a fresh `conversationId` for a branching alternative)."}}},"Conversation":{"example":{"conversationId":"3f2b8c1e-9a4d-4e7b-8c2a-5d1e6f7a8b9c","createdAt":1791970200000,"messages":[{"role":"user","content":"What are your opening hours?","timestamp":"2026-10-14T09:30:00.000Z","read":true},{"role":"assistant","content":"We're open Monday to Friday, 9am to 6pm EST. Outside those hours you can email support@example.com.","timestamp":"2026-10-14T09:30:03.000Z","score":0.87,"upvote":true,"read":true},{"role":"user","content":"Thanks! Can I talk to someone about a refund?","timestamp":"2026-10-14T09:31:00.000Z","read":true},{"role":"human","content":"Hi Jane, I'm Alex from the support team. I can help with your refund.","name":"Alex Chen","avatar":"https://example.blob.core.windows.net/chatfiles/6650f1c2a9e4b83d2c7a1f05/agent-avatar.png","timestamp":"2026-10-14T09:32:00.000Z","read":true}],"source":"widget","requestedLiveChat":true,"liveChatEnded":false,"chatbotId":"6650f1c2a9e4b83d2c7a1f05","ipAddress":"203.0.113.42","userCountry":"US","customer":{"leadId":"8d0c2b6e-4f1a-4b7c-9e3d-2a5f6b7c8d9e","name":"Jane Doe","email":"jane@chat-data.com","phone":"+14155550123","createdAt":1791970230000},"overalRating":5,"browserAgent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 14_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/129.0 Safari/537.36","urlPath":"/pricing"},"required":["conversationId","createdAt","messages","source","chatbotId"],"type":"object","title":"Conversation","properties":{"conversationId":{"type":"string","description":"ID of the conversation."},"createdAt":{"type":"number","description":"When the conversation was created, in milliseconds since the Unix epoch."},"lastMessageAt":{"type":"string","format":"date-time","description":"When the last message in the conversation was sent (ISO 8601), or when the conversation was created if that is not recorded. Only returned by get-conversation."},"messages":{"title":"List of Message Objects","type":"array","items":{"$ref":"#/components/schemas/Message"},"description":"The messages of the conversation, oldest first."},"source":{"type":"string","description":"Where the conversation took place.","enum":["widget","iframe","site","api","Whatsapp","WhatsappWebAPI","Messenger","Instagram","Telegram","Line","Slack","Discord","Workflow Studio","cron-trigger"]},"requestedLiveChat":{"type":"boolean","description":"Whether live chat support was requested in this conversation."},"liveChatEnded":{"type":"boolean","description":"Whether live chat has ended in this conversation."},"chatbotId":{"type":"string","description":"The ID of the chatbot."},"ipAddress":{"type":"string","description":"The IP address of the user."},"userCountry":{"type":"string","description":"The 2-letter ISO country code of the user, based on an IP address lookup (`Unknown` when it could not be resolved)."},"customer":{"$ref":"#/components/schemas/Customer","description":"The lead attached to the conversation, if any. In conversations, `source`, `ipAddress` and `userCountry` are not included in it."},"overalRating":{"type":"number","description":"The overall rating the user gave the conversation (1-5), if any.","minimum":1,"maximum":5},"browserAgent":{"type":"string","description":"The user agent string of the browser used in the conversation."},"urlPath":{"type":"string","description":"The URL path where the conversation started, when the source is `widget`."}}},"ConversationsRes":{"required":["status","conversations","total"],"type":"object","title":"Chatbot Conversations Response","properties":{"status":{"type":"string","enum":["success"]},"conversations":{"type":"array","items":{"$ref":"#/components/schemas/Conversation"},"description":"The conversations, most recently active first. Only conversations with at least one user message are included."},"total":{"type":"number","description":"Total number of matching conversations, ignoring pagination."}}},"LeadsRes":{"required":["status","customers","total"],"type":"object","title":"Chatbot Leads Response","properties":{"status":{"type":"string","enum":["success"]},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"},"description":"The customers, newest first."},"total":{"type":"number","description":"Total number of matching customers, ignoring pagination."}}},"RequestParamProperty":{"type":"object","required":["name","type","description"],"properties":{"name":{"type":"string","description":"The name of the property.","example":"symbol"},"type":{"type":"string","description":"The data type of the property.","enum":["string","number","boolean","array","object"],"example":"string"},"description":{"type":"string","description":"Description of the property.","example":"The stock ticker symbol of the company."},"required":{"type":"boolean","description":"Whether this property is required.","default":false,"example":true},"items":{"$ref":"#/components/schemas/RequestParamProperty","description":"For array types, describes the array items."},"properties":{"type":"array","description":"For object types, describes the object's properties.","items":{"$ref":"#/components/schemas/RequestParamProperty"}}}},"RequestParam":{"type":"object","example":{"name":"symbol","type":"string","description":"The stock ticker symbol to look up.","required":true,"static":false,"example":"AAPL"},"required":["name","type","description","required"],"properties":{"name":{"type":"string","description":"The name of the parameter."},"type":{"type":"string","description":"The data type of the parameter.","enum":["string","number","boolean","array","object"]},"description":{"type":"string","description":"Description of the parameter."},"required":{"type":"boolean","description":"Whether this parameter is required.","default":false},"static":{"type":"boolean","description":"Indicates whether the parameter is static. A static parameter always sends its example value instead of a value generated by the chatbot.","default":false},"example":{"type":"string","description":"Stringified example value. For non-string types (number, boolean, array, object), the value should be JSON-parseable."},"items":{"$ref":"#/components/schemas/RequestParamProperty","description":"For array types, describes the array items."},"properties":{"type":"array","description":"For object types, describes the object's properties.","items":{"$ref":"#/components/schemas/RequestParamProperty"}}}},"Header":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string","description":"The name of the header.","example":"Content-Type"},"value":{"type":"string","description":"The value of the header.","example":"application/json"}}},"ActionBase":{"type":"object","required":["name","description","type"],"properties":{"name":{"type":"string","description":"The name of the action. Only letters, numbers, underscores and hyphens are allowed.","example":"stockPriceLookup"},"description":{"type":"string","description":"Description of when to trigger the action.","example":"The user wants to know the current stock price of a company"},"type":{"type":"string","description":"The type of action."},"url":{"type":"string","description":"For API actions, the URL to call. Use `{name}` placeholders for path parameters.","example":"https://api.example.com/stocks/{symbol}/price"},"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"],"description":"For API actions, the HTTP method."},"headers":{"type":"array","description":"For API actions, the HTTP headers of the request.","items":{"$ref":"#/components/schemas/Header"}},"pathParams":{"type":"array","description":"For API actions, the URL path parameters.","items":{"$ref":"#/components/schemas/RequestParam"}},"queryParams":{"type":"array","description":"For API actions, the URL query parameters.","items":{"$ref":"#/components/schemas/RequestParam"}},"bodyParams":{"type":"array","description":"For API actions, the request body parameters.","items":{"$ref":"#/components/schemas/RequestParam"}},"includeImages":{"type":"boolean","description":"For search actions, whether to include images in the results. Defaults to `true`."},"prioritizeRecentResults":{"type":"boolean","description":"For search actions, whether to prioritize recent results."},"enableDateRestriction":{"type":"boolean","description":"For search actions, whether to enable the date restriction."},"includedDomains":{"type":"array","description":"For search actions, the domains to restrict the web search to, as full URLs (for example `https://www.example.com`). Leave empty to search all domains.","items":{"type":"string"}},"link":{"type":"string","description":"For button actions, the link the button opens. Required for button actions."},"label":{"type":"string","description":"For button actions, the button label. Required for button actions."},"enabled":{"type":"boolean","default":true,"description":"Whether the action is enabled. New actions are enabled unless this is `false`."}}},"ActionInput":{"example":{"name":"stockPriceLookup","description":"The user wants to know the current stock price of a company","type":"api","url":"https://api.example.com/stocks/{symbol}/price","method":"GET","headers":[{"name":"Authorization","value":"Bearer stk_live_3f9a2c7d1e"}],"pathParams":[{"name":"symbol","type":"string","description":"The stock ticker symbol to look up.","required":true,"example":"AAPL"}]},"allOf":[{"$ref":"#/components/schemas/ActionBase"},{"type":"object","required":["name","description","type"],"properties":{"type":{"type":"string","enum":["api","search","lead","button"],"description":"The type of action."}}}]},"Action":{"example":{"index":0,"name":"stockPriceLookup","description":"The user wants to know the current stock price of a company","type":"api","url":"https://api.example.com/stocks/{symbol}/price","method":"GET","headers":[{"name":"Authorization","value":"Bearer stk_live_3f9a2c7d1e"}],"pathParams":[{"name":"symbol","type":"string","description":"The stock ticker symbol to look up.","required":true,"example":"AAPL"}],"return_file":false},"allOf":[{"$ref":"#/components/schemas/ActionBase"},{"type":"object","required":["index","name","description","type"],"properties":{"type":{"type":"string","description":"The type of action. Besides `api`, `search`, `lead` and `button`, actions created in the dashboard can have other types, such as `scrape`, `document`, `order_tracking`, `appointment-ui`, `mcp` or `workflow_action`."},"index":{"type":"integer","description":"The position of the action in the chatbot's action list (0-based)."},"return_file":{"type":"boolean","description":"Whether the action returns a file.","default":false}}}]},"subscriptions":{"title":"Current subscriptions of the workspace","description":"The quantity of each plan and add-on the workspace subscribes to. A workspace without subscriptions gets `{ \"free\": 1 }`; otherwise every key below is listed, with 0 for items it does not subscribe to, and `free` is always 1.","type":"object","properties":{"free":{"type":"number","description":"Quantity of the Free plan in the workspace.","default":1},"entry":{"type":"number","description":"Quantity of the Entry plan in the workspace."},"standard":{"type":"number","description":"Quantity of the Standard plan in the workspace."},"professional":{"type":"number","description":"Quantity of the Professional plan in the workspace."},"extra_messages":{"type":"number","description":"Quantity of the Extra Message Credits add-on in the workspace."},"extra_chatbots":{"type":"number","description":"Quantity of the Extra Chatbots add-on in the workspace."},"remove_brand":{"type":"number","description":"Quantity of the Reseller plan in the workspace."},"remove_label":{"type":"number","description":"Quantity of the Remove 'Powered by Chat Data' add-on in the workspace."},"live_chat":{"type":"number","description":"Quantity of the Live Chat add-on in the workspace."},"webhook_delivery":{"type":"number","description":"Quantity of the Webhook Delivery add-on in the workspace."},"storage":{"type":"number","description":"Quantity of the 10GB Storage add-on in the workspace."},"sso_login":{"type":"number","description":"Quantity of the SSO Login add-on in the workspace."},"customize_plan_1":{"type":"number","description":"Quantity of the Enterprise plan in the workspace."},"scrape":{"type":"number","description":"Quantity of the legacy monthly scrape credits subscription in the workspace."},"entry_legacy":{"type":"number","description":"How many of the `entry` subscriptions are on the Entry plan as sold before August 2026."}},"example":{"free":1,"entry":0,"standard":1,"professional":0,"customize_plan_1":0,"extra_chatbots":0,"extra_messages":0,"live_chat":0,"remove_brand":0,"remove_label":0,"webhook_delivery":0,"sso_login":0,"storage":0,"scrape":0,"entry_legacy":0}},"currentPlan":{"required":["subscriptions","remainingTrainingChars","refreshingTrainingChars","remainingCredits","refreshingCredits","chatbots","chatbotsLimit","chatbotCharactersLimit","gatherLeads","customDomain","api","customModel","userAnalysis","shareAnalysis","notification","gpt4","removeBrand","files"],"type":"object","properties":{"subscriptions":{"$ref":"#/components/schemas/subscriptions"},"remainingTrainingChars":{"type":"number","example":50000000,"description":"The number of characters currently available for training or retraining chatbots in the workspace. Remaining characters do not carry over to the next billing period."},"refreshingTrainingChars":{"type":"number","example":110000000,"description":"The number of training characters the plan grants each billing period."},"remainingCredits":{"type":"number","example":5000,"description":"The number of message credits currently available for asking questions. It includes purchased permanent credits, which carry over; plan credits do not carry over to the next billing period."},"refreshingCredits":{"type":"number","example":10000,"description":"The number of message credits that renew each billing period."},"chatbots":{"type":"number","example":2,"description":"The number of chatbots in the workspace."},"chatbotsLimit":{"type":"number","example":5,"description":"The maximum number of chatbots allowed in the workspace."},"chatbotCharactersLimit":{"type":"number","example":11000000,"description":"The maximum number of characters that can be used to train one chatbot. The effective limit can be lower, because all chatbots in the workspace share its character capacity."},"gatherLeads":{"type":"boolean","example":true,"description":"Whether the workspace can collect customer information through the chatbot."},"customDomain":{"type":"boolean","example":true,"description":"Whether the chatbot can be hosted under a custom domain."},"api":{"type":"boolean","example":true,"description":"Whether the workspace can use the API."},"customModel":{"type":"boolean","example":true,"description":"Whether the workspace can use its own model as the backend for the chatbot widget UI."},"userAnalysis":{"type":"boolean","example":true,"description":"Whether the workspace can access aggregated user analysis statistics."},"shareAnalysis":{"type":"boolean","example":true,"description":"Whether the workspace can share a chatbot's analytics publicly."},"notification":{"type":"boolean","example":true,"description":"Whether the workspace can receive daily email notifications."},"gpt4":{"type":"boolean","example":true,"description":"Whether the workspace can use GPT-4 models to answer questions."},"removeBrand":{"type":"boolean","example":false,"description":"Whether the plan removes the Chat Data branding. The \"Powered by Chat Data\" label can also be hidden by the Remove Label add-on, which this field does not reflect."},"files":{"type":"number","example":2560,"description":"The file storage limit of the workspace, in MB."}}},"analysisRes":{"example":{"status":"success","countryDistribution":[{"country":"US","count":184},{"country":"GB","count":61}],"hourDistribution":[{"hour":"14","source":"iframe","count":37},{"hour":"15","source":"iframe","count":29}],"creditsDistribution":[{"date":1791849600000,"source":"api","count":96},{"date":1791936000000,"source":"iframe","count":412}],"messagesDistribution":[{"date":1791849600000,"source":"api","count":88},{"date":1791936000000,"source":"iframe","count":356}],"liveChatEmailsDistribution":[{"date":1791849600000,"source":"api","count":1},{"date":1791936000000,"source":"iframe","count":3}],"liveChatSmsDistribution":[{"date":1791849600000,"source":"api","count":0},{"date":1791936000000,"source":"iframe","count":2}],"liveChatEscalationsDistribution":[{"date":1791849600000,"source":"api","count":1},{"date":1791936000000,"source":"iframe","count":4}],"upVotesDistribution":[{"date":1791849600000,"source":"api","count":6},{"date":1791936000000,"source":"iframe","count":21}],"downVotesDistribution":[{"date":1791849600000,"source":"api","count":1},{"date":1791936000000,"source":"iframe","count":4}],"conversationsDistribution":[{"date":1791849600000,"source":"api","count":14},{"date":1791936000000,"source":"iframe","count":58}],"leadsCountDistribution":[{"date":1791849600000,"source":"api","count":2},{"date":1791936000000,"source":"iframe","count":9}],"workflowEmailsDistribution":[{"date":1791849600000,"source":"api","count":1},{"date":1791936000000,"source":"iframe","count":5}],"topicsDistribution":[{"topic":"Pricing","count":26},{"topic":"Shipping","count":17}],"sentimentsDistribution":[{"sentiment":"positive","count":41},{"sentiment":"neutral","count":12}],"ratingDistribution":[{"rating":"5","count":19},{"rating":"4","count":7}]},"required":["status","countryDistribution","hourDistribution","creditsDistribution","messagesDistribution","liveChatEmailsDistribution","liveChatSmsDistribution","liveChatEscalationsDistribution","upVotesDistribution","downVotesDistribution","conversationsDistribution","leadsCountDistribution","workflowEmailsDistribution","topicsDistribution","sentimentsDistribution","ratingDistribution"],"type":"object","title":"Aggregated Statistics of Chatbot Usage","properties":{"status":{"type":"string","enum":["success"]},"countryDistribution":{"title":"Country Distribution of Messages","type":"array","description":"Messages per user country, most messages first.","items":{"type":"object","properties":{"country":{"type":"string","description":"The 2-letter ISO country code from the IP address lookup (`Unknown` when it could not be resolved)."},"count":{"type":"number","description":"The number of messages for users from this country within the specified date range."}}}},"hourDistribution":{"title":"Hour Distribution of Messages","type":"array","description":"Messages per UTC hour and source, ordered by hour.","items":{"type":"object","properties":{"hour":{"type":"string","description":"The UTC hour when the messages occurred."},"source":{"type":"string","enum":["widget","iframe","site","api","Whatsapp","WhatsappWebAPI","Messenger","Instagram","Telegram","Line","Slack","Discord","Workflow Studio","cron-trigger","youtube-transcription","image-description-test","metering"],"description":"The source of the messages."},"count":{"type":"number","description":"The number of messages during this UTC hour within the specified date range."}}}},"creditsDistribution":{"title":"Date Distribution of Message Credits Consumption","type":"array","description":"One entry per day and source, oldest first.","items":{"type":"object","properties":{"date":{"type":"number","description":"The day, as a timestamp in milliseconds since the Unix epoch."},"source":{"type":"string","enum":["widget","iframe","site","api","Whatsapp","WhatsappWebAPI","Messenger","Instagram","Telegram","Line","Slack","Discord","Workflow Studio","cron-trigger","youtube-transcription","image-description-test","metering"],"description":"The source where message credits were consumed."},"count":{"type":"number","description":"The number of message credits consumed on the specified date."}}}},"messagesDistribution":{"title":"Date Distribution of Messages","type":"array","description":"One entry per day and source, oldest first.","items":{"type":"object","properties":{"date":{"type":"number","description":"The day, as a timestamp in milliseconds since the Unix epoch."},"source":{"type":"string","enum":["widget","iframe","site","api","Whatsapp","WhatsappWebAPI","Messenger","Instagram","Telegram","Line","Slack","Discord","Workflow Studio","cron-trigger","youtube-transcription","image-description-test","metering"],"description":"The source where the messages were sent."},"count":{"type":"number","description":"The number of messages sent on the specified date."}}}},"liveChatEmailsDistribution":{"title":"Date Distribution of Live Chat Emails","type":"array","description":"One entry per day and source, oldest first.","items":{"type":"object","properties":{"date":{"type":"number","description":"The day, as a timestamp in milliseconds since the Unix epoch."},"source":{"type":"string","enum":["widget","iframe","site","api","Whatsapp","WhatsappWebAPI","Messenger","Instagram","Telegram","Line","Slack","Discord","Workflow Studio","cron-trigger","youtube-transcription","image-description-test","metering"],"description":"The source where the live chat emails were sent."},"count":{"type":"number","description":"The number of live chat emails sent on the specified date."}}}},"liveChatSmsDistribution":{"title":"Date Distribution of Live Chat SMS","type":"array","description":"One entry per day and source, oldest first.","items":{"type":"object","properties":{"date":{"type":"number","description":"The day, as a timestamp in milliseconds since the Unix epoch."},"source":{"type":"string","enum":["widget","iframe","site","api","Whatsapp","WhatsappWebAPI","Messenger","Instagram","Telegram","Line","Slack","Discord","Workflow Studio","cron-trigger","youtube-transcription","image-description-test","metering"],"description":"The source where the live chat SMS messages were sent."},"count":{"type":"number","description":"The number of live chat SMS messages sent on the specified date."}}}},"liveChatEscalationsDistribution":{"title":"Date Distribution of Live Chat Escalations","type":"array","description":"One entry per day and source, oldest first.","items":{"type":"object","properties":{"date":{"type":"number","description":"The day, as a timestamp in milliseconds since the Unix epoch."},"source":{"type":"string","enum":["widget","iframe","site","api","Whatsapp","WhatsappWebAPI","Messenger","Instagram","Telegram","Line","Slack","Discord","Workflow Studio","cron-trigger","youtube-transcription","image-description-test","metering"],"description":"The source where the live chat escalations happened."},"count":{"type":"number","description":"The number of live chat escalations on the specified date."}}}},"upVotesDistribution":{"title":"Date Distribution of Upvotes","type":"array","description":"One entry per day and source, oldest first.","items":{"type":"object","properties":{"date":{"type":"number","description":"The day, as a timestamp in milliseconds since the Unix epoch."},"source":{"type":"string","enum":["widget","iframe","site","api","Whatsapp","WhatsappWebAPI","Messenger","Instagram","Telegram","Line","Slack","Discord","Workflow Studio","cron-trigger","youtube-transcription","image-description-test","metering"],"description":"The source where the upvotes occurred."},"count":{"type":"number","description":"The number of upvotes on the specified date."}}}},"downVotesDistribution":{"title":"Date Distribution of Downvotes","type":"array","description":"One entry per day and source, oldest first.","items":{"type":"object","properties":{"date":{"type":"number","description":"The day, as a timestamp in milliseconds since the Unix epoch."},"source":{"type":"string","enum":["widget","iframe","site","api","Whatsapp","WhatsappWebAPI","Messenger","Instagram","Telegram","Line","Slack","Discord","Workflow Studio","cron-trigger","youtube-transcription","image-description-test","metering"],"description":"The source where the downvotes occurred."},"count":{"type":"number","description":"The number of downvotes on the specified date."}}}},"conversationsDistribution":{"title":"Date Distribution of Conversations","type":"array","description":"One entry per day and source, oldest first.","items":{"type":"object","properties":{"date":{"type":"number","description":"The day, as a timestamp in milliseconds since the Unix epoch."},"source":{"type":"string","enum":["widget","iframe","site","api","Whatsapp","WhatsappWebAPI","Messenger","Instagram","Telegram","Line","Slack","Discord","Workflow Studio","cron-trigger","youtube-transcription","image-description-test","metering"],"description":"The source where the conversations started."},"count":{"type":"number","description":"The number of conversations started on the specified date."}}}},"leadsCountDistribution":{"title":"Date Distribution of Leads","type":"array","description":"One entry per day and source, oldest first.","items":{"type":"object","properties":{"date":{"type":"number","description":"The day, as a timestamp in milliseconds since the Unix epoch."},"source":{"type":"string","enum":["widget","iframe","site","api","Whatsapp","WhatsappWebAPI","Messenger","Instagram","Telegram","Line","Slack","Discord","Workflow Studio","cron-trigger","youtube-transcription","image-description-test","metering"],"description":"The source where the leads were collected."},"count":{"type":"number","description":"The number of leads collected on the specified date."}}}},"workflowEmailsDistribution":{"title":"Date Distribution of Workflow Emails","type":"array","description":"One entry per day and source, oldest first.","items":{"type":"object","properties":{"date":{"type":"number","description":"The day, as a timestamp in milliseconds since the Unix epoch."},"source":{"type":"string","enum":["widget","iframe","site","api","Whatsapp","WhatsappWebAPI","Messenger","Instagram","Telegram","Line","Slack","Discord","Workflow Studio","cron-trigger","youtube-transcription","image-description-test","metering"],"description":"The source where the workflow emails were sent."},"count":{"type":"number","description":"The number of workflow emails sent on the specified date."}}}},"topicsDistribution":{"title":"Distribution of Chat Topics","type":"array","description":"Totals per topic, highest count first.","items":{"type":"object","properties":{"topic":{"type":"string","description":"The topic name."},"count":{"type":"number","description":"The number of user messages classified with this topic."}}}},"sentimentsDistribution":{"title":"Distribution of Chat Sentiments","type":"array","description":"Totals per sentiment, highest count first.","items":{"type":"object","properties":{"sentiment":{"type":"string","description":"The sentiment value (for example positive, negative or neutral)."},"count":{"type":"number","description":"The number of user messages classified with this sentiment."}}}},"ratingDistribution":{"title":"Distribution of Chat Ratings","type":"array","description":"Totals per rating, highest count first.","items":{"type":"object","properties":{"rating":{"type":"string","description":"The rating value (1-5)."},"count":{"type":"number","description":"The number of conversations with this rating."}}}}}},"currentPlanRes":{"required":["status","plan","email","name"],"type":"object","title":"Current plan","properties":{"status":{"type":"string","enum":["success"]},"email":{"type":"string","description":"The email address of the workspace owner.","example":"jane@example.com"},"name":{"type":"string","description":"The name of the workspace owner.","example":"Jane Doe"},"plan":{"$ref":"#/components/schemas/currentPlan","description":"The workspace's current plan."}}},"ChatbotStatusRes":{"title":"Chatbot Status Response","required":["status","progress"],"type":"object","properties":{"status":{"type":"string","enum":["success"],"description":"The overall status of the chatbot."},"progress":{"type":"number","minimum":0,"maximum":100,"description":"The training progress of the chatbot. For the pre-trained medical chat models, the progress is set to 100 when the chatbot is created. For chatbots trained on your own data, it starts at 0.\n"}}},"SuccessStatus":{"title":"Success","required":["status"],"type":"object","properties":{"status":{"type":"string","enum":["success"]}}},"ErrorStatus":{"type":"object","title":"Error","required":["status","message"],"properties":{"status":{"type":"string","enum":["error"]},"message":{"type":"string","description":"A detailed explanation of why the request has failed.","example":"No chatbot associated with the provided chatbotId was found for the user."}}},"RateLimitError":{"type":"object","title":"Too many requests error","required":["status","message"],"properties":{"status":{"type":"string","enum":["error"]},"message":{"type":"string","description":"Says how many seconds to wait before retrying. The same number is in the `Retry-After` header.","example":"Too many API requests in a row. Please retry after 12 seconds"}}},"AuthenticationErrorObject":{"type":"object","title":"Authentication Error","required":["status","message"],"properties":{"status":{"type":"string","enum":["error"]},"message":{"type":"string","description":"Why authentication failed. One of:\n- `Authorization header is missing`\n- `Invalid Authorization header format` (the header is not `Bearer <key>`)\n- `Unauthenticated Request` (no API key matches)\n- `API key workspace is unavailable or has been deleted.`\n- `API key workspace has no owner.`\n- `API access isn't included in your workspace's current plan. Upgrade at https://www.chat-data.com/pricing to enable API calls.`","example":"Unauthenticated Request"}}},"SubUserErrorObject":{"type":"object","title":"Sub-user error","description":"Error body of the sub-user operations. It has a `message` and, unlike other errors, usually no `status` field.","required":["message"],"properties":{"status":{"type":"string","enum":["error"],"description":"Only present on the 403 returned for a chatbot-scoped API key."},"message":{"type":"string","description":"A detailed explanation of why the request has failed."}}}},"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}}}}