{ "openapi": "3.1.0", "info": { "title": "Turbo Agent API", "version": "1", "description": "Your server uses the API to talk to an agent: it creates a chat for a customer, sends their messages and reads the agent's replies. It can also upload files, fill in the forms the agent asks for and pass the chat to your team.\n\nEvery request goes to `https://turboagent.app/v1/channels/{channelKey}`, where `channelKey` is the `data-deployment` value in the code to add to your website, with the agent's chat key in `Authorization: Bearer ck_…`. Call the API only from your server, so the key never reaches a customer's device. Requests with an `Origin` header, which browsers send, are refused.\n\nRequests that change something take an `Idempotency-Key` header. If no answer comes back, send the same request with the same key: you get the first result, and nothing happens twice.\n\nErrors are JSON, such as `{\"error\":{\"code\":\"rate_limited\",\"message\":\"Too many requests. Try again shortly.\",\"requestId\":\"rq_3f1c9a7e5b2d4c6a\",\"retryAfterSeconds\":2}}`. Act on `code`; `message` may change. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`. After a 429, wait `Retry-After` seconds, then send the same request again.\n\n| Limit | |\n| --- | --- |\n| Message text | 4,000 UTF-16 code units, the length JavaScript gives a string |\n| Files | JPEG, PNG, GIF, WebP, PDF or plain text, up to 4 MiB each |\n| Files in a chat | 4 a message, 40 a chat and 80 MiB a chat |\n| Unsent files | Deleted after a day |\n| JSON body | 32 KiB, or 2 MiB to submit a collection |\n| Collection answers | 20 a submission, 2,000 UTF-16 code units each |\n| Messages a page | Up to 50, 20 if you don't say |\n| Idempotency-Key | Kept 30 days to create a chat, and as long as the chat for the rest |" }, "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "servers": [{ "url": "https://turboagent.app" }], "security": [{ "chatKey": [] }], "paths": { "/v1/channels/{channelKey}/chats": { "post": { "operationId": "createChat", "summary": "Create a chat", "description": "Starts a chat. Sending the same Idempotency-Key again returns the same chat, as it is now.", "parameters": [ { "name": "channelKey", "in": "path", "required": true, "description": "The channel's address. It's under Channel address on the agent's Chat key screen, and is the data-deployment value in the code you add to your website.", "schema": { "type": "string", "pattern": "^dep_[a-z0-9_-]{6,80}$", "examples": ["dep_example123"] } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "8–128 letters, digits or . _ : -, a UUID recommended. Repeat it to retry the same request safely.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{8,128}$", "examples": ["2f0a43a4-8c55-4c7e-9b8f-4b1bba0b1d6e"] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{8,128}$", "description": "Your own ID for the customer: 8–128 letters, digits or . _ : -. It belongs to this channel and is not a sign-in.", "examples": ["shopper_123"] }, "locale": { "type": "string", "maxLength": 64, "pattern": "^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$", "description": "A BCP 47 language tag. Chats default to en.", "examples": ["en-GB"] } }, "additionalProperties": false, "examples": [{ "userId": "shopper_123", "locale": "en" }] } } } }, "responses": { "200": { "description": "The first result, when the same Idempotency-Key is sent again.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/Chat" } }, "required": ["item"], "additionalProperties": false }, "examples": { "created": { "$ref": "#/components/examples/createChat.created" } } } } }, "201": { "description": "Created.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/Chat" } }, "required": ["item"], "additionalProperties": false }, "examples": { "created": { "$ref": "#/components/examples/createChat.created" } } } } }, "400": { "description": "invalid_id, invalid_json, invalid_request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_id": { "$ref": "#/components/examples/invalid_id" }, "invalid_json": { "$ref": "#/components/examples/invalid_json" }, "invalid_request": { "$ref": "#/components/examples/invalid_request" } } } } }, "401": { "description": "invalid_api_key", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "$ref": "#/components/examples/invalid_api_key" } } } } }, "403": { "description": "origin_not_allowed, channel_disabled, workspace_suspended", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "origin_not_allowed": { "$ref": "#/components/examples/origin_not_allowed" }, "channel_disabled": { "$ref": "#/components/examples/channel_disabled" }, "workspace_suspended": { "$ref": "#/components/examples/workspace_suspended" } } } } }, "409": { "description": "idempotency_conflict, idempotency_key_expired", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_conflict": { "$ref": "#/components/examples/idempotency_conflict" }, "idempotency_key_expired": { "$ref": "#/components/examples/idempotency_key_expired" } } } } }, "410": { "description": "idempotency_resource_gone", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_resource_gone": { "$ref": "#/components/examples/idempotency_resource_gone" } } } } }, "413": { "description": "payload_too_large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "payload_too_large": { "$ref": "#/components/examples/payload_too_large" } } } } }, "415": { "description": "unsupported_media_type", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unsupported_media_type": { "$ref": "#/components/examples/unsupported_media_type" } } } } }, "429": { "description": "rate_limited, chat_limit_reached, capacity_limited", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "chat_limit_reached": { "$ref": "#/components/examples/chat_limit_reached" }, "capacity_limited": { "$ref": "#/components/examples/capacity_limited" } } } } }, "500": { "description": "internal_error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } } } } }, "/v1/channels/{channelKey}/chats/{chatId}": { "get": { "operationId": "getChat", "summary": "Get a chat", "description": "Reads a chat: who is answering it and whether it is waiting for your team.", "parameters": [ { "name": "channelKey", "in": "path", "required": true, "description": "The channel's address. It's under Channel address on the agent's Chat key screen, and is the data-deployment value in the code you add to your website.", "schema": { "type": "string", "pattern": "^dep_[a-z0-9_-]{6,80}$", "examples": ["dep_example123"] } }, { "name": "chatId", "in": "path", "required": true, "description": "The chat's ID, from createChat.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,128}$", "examples": ["4b13b730-69d4-441c-8aee-42de75fef073"] } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/Chat" } }, "required": ["item"], "additionalProperties": false }, "examples": { "teammate": { "$ref": "#/components/examples/getChat.teammate" } } } } }, "400": { "description": "invalid_id", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_id": { "$ref": "#/components/examples/invalid_id" } } } } }, "401": { "description": "invalid_api_key", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "$ref": "#/components/examples/invalid_api_key" } } } } }, "403": { "description": "origin_not_allowed, channel_disabled, workspace_suspended", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "origin_not_allowed": { "$ref": "#/components/examples/origin_not_allowed" }, "channel_disabled": { "$ref": "#/components/examples/channel_disabled" }, "workspace_suspended": { "$ref": "#/components/examples/workspace_suspended" } } } } }, "404": { "description": "chat_not_found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "chat_not_found": { "$ref": "#/components/examples/chat_not_found" } } } } }, "429": { "description": "rate_limited", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "internal_error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } } } } }, "/v1/channels/{channelKey}/chats/{chatId}/messages": { "post": { "operationId": "sendMessage", "summary": "Send a message", "description": "Sends the customer's message and returns the agent's reply. While the chat is with your team, the reply is null.", "parameters": [ { "name": "channelKey", "in": "path", "required": true, "description": "The channel's address. It's under Channel address on the agent's Chat key screen, and is the data-deployment value in the code you add to your website.", "schema": { "type": "string", "pattern": "^dep_[a-z0-9_-]{6,80}$", "examples": ["dep_example123"] } }, { "name": "chatId", "in": "path", "required": true, "description": "The chat's ID, from createChat.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,128}$", "examples": ["4b13b730-69d4-441c-8aee-42de75fef073"] } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "8–128 letters, digits or . _ : -, a UUID recommended. Repeat it to retry the same request safely.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{8,128}$", "examples": ["2f0a43a4-8c55-4c7e-9b8f-4b1bba0b1d6e"] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "description": "The customer's message.", "type": "string", "x-max-utf16-code-units": 4000 }, "fileIds": { "description": "1–4 uploaded files to send with the message.", "uniqueItems": true, "minItems": 1, "maxItems": 4, "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,128}$", "description": "8–128 letters, digits, underscores or hyphens.", "examples": ["4b13b730-69d4-441c-8aee-42de75fef073"] } } }, "additionalProperties": false, "description": "Text, files or both. Text alone must contain more than spaces.", "anyOf": [ { "required": ["text"], "properties": { "text": { "pattern": "\\S" } } }, { "required": ["fileIds"] } ], "examples": [{ "text": "When are you open?" }] } } } }, "responses": { "200": { "description": "The first result, when the same Idempotency-Key is sent again. With Accept: text/event-stream, the reply as a stream, whether new or sent again.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/MessageTurn" } }, "required": ["item"], "additionalProperties": false }, "examples": { "answered": { "$ref": "#/components/examples/sendMessage.answered" }, "waiting": { "$ref": "#/components/examples/sendMessage.waiting" } } }, "text/event-stream": { "schema": { "type": "string", "description": "Server-sent events: start, then delta for each part of the reply, then done or error. A comment line is sent every 15 seconds to keep the connection open. If the stream ends without done or error, the result is unknown: send the request again with the same Idempotency-Key, or list the messages." }, "x-events": { "start": { "type": "object", "properties": { "chatId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,128}$", "description": "8–128 letters, digits, underscores or hyphens.", "examples": ["4b13b730-69d4-441c-8aee-42de75fef073"] }, "requestId": { "type": "string", "description": "The X-Request-Id of this request." }, "messageId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,128}$", "description": "The customer's message.", "examples": ["4b13b730-69d4-441c-8aee-42de75fef073"] }, "replyId": { "anyOf": [ { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,128}$", "description": "8–128 letters, digits, underscores or hyphens.", "examples": ["4b13b730-69d4-441c-8aee-42de75fef073"] }, { "type": "null" } ], "description": "The agent's reply, or null while the chat is with your team." } }, "required": ["chatId", "requestId", "messageId", "replyId"], "additionalProperties": false }, "delta": { "type": "object", "properties": { "text": { "type": "string", "description": "More of the reply's text." } }, "required": ["text"], "additionalProperties": false }, "done": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/MessageTurn" } }, "required": ["item"], "additionalProperties": false }, "error": { "$ref": "#/components/schemas/Error" } }, "example": "event: start\ndata: {\"chatId\":\"4b13b730-69d4-441c-8aee-42de75fef073\",\"requestId\":\"rq_3f1c9a7e5b2d4c6a\",\"messageId\":\"29a1fb72-55e2-44c6-bf21-a21f8e25fbc1\",\"replyId\":\"8f0e2d6c-3b1a-4f5e-9c7d-2a6b4e8f1c3d\"}\n\nevent: delta\ndata: {\"text\":\"We're open 9am to 5:30pm Monday to Saturday, \"}\n\nevent: delta\ndata: {\"text\":\"and 10am to 4pm on Sunday.\"}\n\nevent: done\ndata: {\"item\":{\"message\":{\"id\":\"29a1fb72-55e2-44c6-bf21-a21f8e25fbc1\",\"chatId\":\"4b13b730-69d4-441c-8aee-42de75fef073\",\"role\":\"visitor\",\"text\":\"When are you open?\",\"createdAt\":\"2026-10-12T09:00:01.000Z\",\"author\":null,\"files\":[],\"citations\":[],\"products\":[],\"orders\":[],\"choices\":[],\"collection\":null,\"handoffOffer\":null},\"reply\":{\"id\":\"8f0e2d6c-3b1a-4f5e-9c7d-2a6b4e8f1c3d\",\"chatId\":\"4b13b730-69d4-441c-8aee-42de75fef073\",\"role\":\"agent\",\"text\":\"We're open 9am to 5:30pm Monday to Saturday, and 10am to 4pm on Sunday.\",\"createdAt\":\"2026-10-12T09:00:03.000Z\",\"author\":null,\"files\":[],\"citations\":[{\"title\":\"Opening times\",\"url\":\"https://shop.example/pages/opening-times\",\"updatedAt\":\"2026-10-01T08:00:00.000Z\"}],\"products\":[],\"orders\":[],\"choices\":[],\"collection\":null,\"handoffOffer\":null},\"chat\":{\"id\":\"4b13b730-69d4-441c-8aee-42de75fef073\",\"channelKey\":\"dep_example123\",\"userId\":\"shopper_123\",\"mode\":\"agent\",\"teammate\":null,\"createdAt\":\"2026-10-12T09:00:00.000Z\",\"updatedAt\":\"2026-10-12T09:00:03.000Z\",\"resolvedAt\":null,\"historyComplete\":true,\"handoff\":null}}}\n\n" } } }, "201": { "description": "Created.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/MessageTurn" } }, "required": ["item"], "additionalProperties": false }, "examples": { "answered": { "$ref": "#/components/examples/sendMessage.answered" }, "waiting": { "$ref": "#/components/examples/sendMessage.waiting" } } } } }, "400": { "description": "invalid_id, invalid_json, invalid_request, unsupported_resume", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_id": { "$ref": "#/components/examples/invalid_id" }, "invalid_json": { "$ref": "#/components/examples/invalid_json" }, "invalid_request": { "$ref": "#/components/examples/invalid_request" }, "unsupported_resume": { "$ref": "#/components/examples/unsupported_resume" } } } } }, "401": { "description": "invalid_api_key", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "$ref": "#/components/examples/invalid_api_key" } } } } }, "403": { "description": "origin_not_allowed, channel_disabled, workspace_suspended", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "origin_not_allowed": { "$ref": "#/components/examples/origin_not_allowed" }, "channel_disabled": { "$ref": "#/components/examples/channel_disabled" }, "workspace_suspended": { "$ref": "#/components/examples/workspace_suspended" } } } } }, "404": { "description": "chat_not_found, file_not_found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "chat_not_found": { "$ref": "#/components/examples/chat_not_found" }, "file_not_found": { "$ref": "#/components/examples/file_not_found" } } } } }, "406": { "description": "unsupported_accept", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unsupported_accept": { "$ref": "#/components/examples/unsupported_accept" } } } } }, "409": { "description": "idempotency_conflict, turn_in_progress, operation_capacity_reached, chat_closed, operation_interrupted, operation_superseded, file_not_ready", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_conflict": { "$ref": "#/components/examples/idempotency_conflict" }, "turn_in_progress": { "$ref": "#/components/examples/turn_in_progress" }, "operation_capacity_reached": { "$ref": "#/components/examples/operation_capacity_reached" }, "chat_closed": { "$ref": "#/components/examples/chat_closed" }, "operation_interrupted": { "$ref": "#/components/examples/operation_interrupted" }, "operation_superseded": { "$ref": "#/components/examples/operation_superseded" }, "file_not_ready": { "$ref": "#/components/examples/file_not_ready" } } } } }, "413": { "description": "payload_too_large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "payload_too_large": { "$ref": "#/components/examples/payload_too_large" } } } } }, "415": { "description": "unsupported_media_type", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unsupported_media_type": { "$ref": "#/components/examples/unsupported_media_type" } } } } }, "429": { "description": "rate_limited, chat_limit_reached", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "chat_limit_reached": { "$ref": "#/components/examples/chat_limit_reached" } } } } }, "500": { "description": "internal_error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } }, "503": { "description": "service_unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "service_unavailable": { "$ref": "#/components/examples/service_unavailable" } } } } } } }, "get": { "operationId": "listMessages", "summary": "List messages", "description": "Lists a chat's messages, oldest first.", "parameters": [ { "name": "channelKey", "in": "path", "required": true, "description": "The channel's address. It's under Channel address on the agent's Chat key screen, and is the data-deployment value in the code you add to your website.", "schema": { "type": "string", "pattern": "^dep_[a-z0-9_-]{6,80}$", "examples": ["dep_example123"] } }, { "name": "chatId", "in": "path", "required": true, "description": "The chat's ID, from createChat.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,128}$", "examples": ["4b13b730-69d4-441c-8aee-42de75fef073"] } }, { "name": "limit", "in": "query", "required": false, "description": "How many messages to return, 1–50. Defaults to 20.", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "nextCursor from the previous page.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,2048}$" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "nextCursor": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Null on the last page." } }, "required": ["items", "nextCursor"], "additionalProperties": false }, "examples": { "page": { "$ref": "#/components/examples/listMessages.page" } } } } }, "400": { "description": "invalid_id, invalid_request, invalid_cursor", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_id": { "$ref": "#/components/examples/invalid_id" }, "invalid_request": { "$ref": "#/components/examples/invalid_request" }, "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" } } } } }, "401": { "description": "invalid_api_key", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "$ref": "#/components/examples/invalid_api_key" } } } } }, "403": { "description": "origin_not_allowed, channel_disabled, workspace_suspended", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "origin_not_allowed": { "$ref": "#/components/examples/origin_not_allowed" }, "channel_disabled": { "$ref": "#/components/examples/channel_disabled" }, "workspace_suspended": { "$ref": "#/components/examples/workspace_suspended" } } } } }, "404": { "description": "chat_not_found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "chat_not_found": { "$ref": "#/components/examples/chat_not_found" } } } } }, "410": { "description": "cursor_expired", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "cursor_expired": { "$ref": "#/components/examples/cursor_expired" } } } } }, "429": { "description": "rate_limited", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "internal_error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } } } } }, "/v1/channels/{channelKey}/chats/{chatId}/files": { "post": { "operationId": "uploadFile", "summary": "Upload a file", "description": "Uploads a file to send with a message. Unsent files are deleted after a day.", "parameters": [ { "name": "channelKey", "in": "path", "required": true, "description": "The channel's address. It's under Channel address on the agent's Chat key screen, and is the data-deployment value in the code you add to your website.", "schema": { "type": "string", "pattern": "^dep_[a-z0-9_-]{6,80}$", "examples": ["dep_example123"] } }, { "name": "chatId", "in": "path", "required": true, "description": "The chat's ID, from createChat.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,128}$", "examples": ["4b13b730-69d4-441c-8aee-42de75fef073"] } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "8–128 letters, digits or . _ : -, a UUID recommended. Repeat it to retry the same request safely.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{8,128}$", "examples": ["2f0a43a4-8c55-4c7e-9b8f-4b1bba0b1d6e"] } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "contentEncoding": "binary", "maxLength": 4194304, "anyOf": [ { "contentMediaType": "image/jpeg" }, { "contentMediaType": "image/png" }, { "contentMediaType": "image/gif" }, { "contentMediaType": "image/webp" }, { "contentMediaType": "application/pdf" }, { "contentMediaType": "text/plain" } ], "description": "One JPEG, PNG, GIF, WebP, PDF or plain text file, up to 4 MiB." } }, "required": ["file"], "additionalProperties": false } } } }, "responses": { "200": { "description": "The first result, when the same Idempotency-Key is sent again.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/File" } }, "required": ["item"], "additionalProperties": false }, "examples": { "uploaded": { "$ref": "#/components/examples/uploadFile.uploaded" } } } } }, "201": { "description": "Created.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/File" } }, "required": ["item"], "additionalProperties": false }, "examples": { "uploaded": { "$ref": "#/components/examples/uploadFile.uploaded" } } } } }, "400": { "description": "invalid_id, invalid_request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_id": { "$ref": "#/components/examples/invalid_id" }, "invalid_request": { "$ref": "#/components/examples/invalid_request" } } } } }, "401": { "description": "invalid_api_key", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "$ref": "#/components/examples/invalid_api_key" } } } } }, "403": { "description": "origin_not_allowed, channel_disabled, workspace_suspended", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "origin_not_allowed": { "$ref": "#/components/examples/origin_not_allowed" }, "channel_disabled": { "$ref": "#/components/examples/channel_disabled" }, "workspace_suspended": { "$ref": "#/components/examples/workspace_suspended" } } } } }, "404": { "description": "chat_not_found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "chat_not_found": { "$ref": "#/components/examples/chat_not_found" } } } } }, "409": { "description": "idempotency_conflict, chat_closed, file_not_ready, file_limit_reached, file_storage_limit", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_conflict": { "$ref": "#/components/examples/idempotency_conflict" }, "chat_closed": { "$ref": "#/components/examples/chat_closed" }, "file_not_ready": { "$ref": "#/components/examples/file_not_ready" }, "file_limit_reached": { "$ref": "#/components/examples/file_limit_reached" }, "file_storage_limit": { "$ref": "#/components/examples/file_storage_limit" } } } } }, "413": { "description": "payload_too_large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "payload_too_large": { "$ref": "#/components/examples/payload_too_large" } } } } }, "415": { "description": "unsupported_media_type, unsupported_file", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unsupported_media_type": { "$ref": "#/components/examples/unsupported_media_type" }, "unsupported_file": { "$ref": "#/components/examples/unsupported_file" } } } } }, "429": { "description": "rate_limited", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "internal_error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } } } } }, "/v1/channels/{channelKey}/chats/{chatId}/files/{fileId}": { "get": { "operationId": "downloadFile", "summary": "Download a file", "description": "Downloads a file sent in the chat.", "parameters": [ { "name": "channelKey", "in": "path", "required": true, "description": "The channel's address. It's under Channel address on the agent's Chat key screen, and is the data-deployment value in the code you add to your website.", "schema": { "type": "string", "pattern": "^dep_[a-z0-9_-]{6,80}$", "examples": ["dep_example123"] } }, { "name": "chatId", "in": "path", "required": true, "description": "The chat's ID, from createChat.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,128}$", "examples": ["4b13b730-69d4-441c-8aee-42de75fef073"] } }, { "name": "fileId", "in": "path", "required": true, "description": "The file's ID, from uploadFile or a message's files.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,128}$", "examples": ["4b13b730-69d4-441c-8aee-42de75fef073"] } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Content-Disposition": { "$ref": "#/components/headers/Content-Disposition" } }, "content": { "*/*": { "schema": { "type": "string", "format": "binary", "contentEncoding": "binary", "description": "The file's bytes, with the Content-Type it was uploaded with." } } } }, "400": { "description": "invalid_id", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_id": { "$ref": "#/components/examples/invalid_id" } } } } }, "401": { "description": "invalid_api_key", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "$ref": "#/components/examples/invalid_api_key" } } } } }, "403": { "description": "origin_not_allowed, channel_disabled, workspace_suspended", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "origin_not_allowed": { "$ref": "#/components/examples/origin_not_allowed" }, "channel_disabled": { "$ref": "#/components/examples/channel_disabled" }, "workspace_suspended": { "$ref": "#/components/examples/workspace_suspended" } } } } }, "404": { "description": "chat_not_found, file_not_found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "chat_not_found": { "$ref": "#/components/examples/chat_not_found" }, "file_not_found": { "$ref": "#/components/examples/file_not_found" } } } } }, "409": { "description": "file_not_ready", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "file_not_ready": { "$ref": "#/components/examples/file_not_ready" } } } } }, "429": { "description": "rate_limited", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "internal_error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } } } } }, "/v1/channels/{channelKey}/chats/{chatId}/collection": { "get": { "operationId": "getCollection", "summary": "Get the collection", "description": "Reads the details collected in the chat and any form the agent is asking for.", "parameters": [ { "name": "channelKey", "in": "path", "required": true, "description": "The channel's address. It's under Channel address on the agent's Chat key screen, and is the data-deployment value in the code you add to your website.", "schema": { "type": "string", "pattern": "^dep_[a-z0-9_-]{6,80}$", "examples": ["dep_example123"] } }, { "name": "chatId", "in": "path", "required": true, "description": "The chat's ID, from createChat.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,128}$", "examples": ["4b13b730-69d4-441c-8aee-42de75fef073"] } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/Collection" } }, "required": ["item"], "additionalProperties": false }, "examples": { "form": { "$ref": "#/components/examples/getCollection.form" } } } } }, "400": { "description": "invalid_id", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_id": { "$ref": "#/components/examples/invalid_id" } } } } }, "401": { "description": "invalid_api_key", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "$ref": "#/components/examples/invalid_api_key" } } } } }, "403": { "description": "origin_not_allowed, channel_disabled, workspace_suspended", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "origin_not_allowed": { "$ref": "#/components/examples/origin_not_allowed" }, "channel_disabled": { "$ref": "#/components/examples/channel_disabled" }, "workspace_suspended": { "$ref": "#/components/examples/workspace_suspended" } } } } }, "404": { "description": "chat_not_found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "chat_not_found": { "$ref": "#/components/examples/chat_not_found" } } } } }, "429": { "description": "rate_limited", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "internal_error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } } } }, "post": { "operationId": "submitCollection", "summary": "Submit the collection", "description": "Saves, skips or cancels the form the agent is asking for.", "parameters": [ { "name": "channelKey", "in": "path", "required": true, "description": "The channel's address. It's under Channel address on the agent's Chat key screen, and is the data-deployment value in the code you add to your website.", "schema": { "type": "string", "pattern": "^dep_[a-z0-9_-]{6,80}$", "examples": ["dep_example123"] } }, { "name": "chatId", "in": "path", "required": true, "description": "The chat's ID, from createChat.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,128}$", "examples": ["4b13b730-69d4-441c-8aee-42de75fef073"] } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "8–128 letters, digits or . _ : -, a UUID recommended. Repeat it to retry the same request safely.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{8,128}$", "examples": ["2f0a43a4-8c55-4c7e-9b8f-4b1bba0b1d6e"] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionSubmission" } } } }, "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/Collection" } }, "required": ["item"], "additionalProperties": false }, "examples": { "saved": { "$ref": "#/components/examples/submitCollection.saved" } } } } }, "400": { "description": "invalid_id, invalid_json, invalid_request, invalid_submission", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_id": { "$ref": "#/components/examples/invalid_id" }, "invalid_json": { "$ref": "#/components/examples/invalid_json" }, "invalid_request": { "$ref": "#/components/examples/invalid_request" }, "invalid_submission": { "$ref": "#/components/examples/invalid_submission" } } } } }, "401": { "description": "invalid_api_key", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "$ref": "#/components/examples/invalid_api_key" } } } } }, "403": { "description": "origin_not_allowed, channel_disabled, workspace_suspended", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "origin_not_allowed": { "$ref": "#/components/examples/origin_not_allowed" }, "channel_disabled": { "$ref": "#/components/examples/channel_disabled" }, "workspace_suspended": { "$ref": "#/components/examples/workspace_suspended" } } } } }, "404": { "description": "chat_not_found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "chat_not_found": { "$ref": "#/components/examples/chat_not_found" } } } } }, "409": { "description": "idempotency_conflict, turn_in_progress, operation_capacity_reached, chat_closed, version_conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_conflict": { "$ref": "#/components/examples/idempotency_conflict" }, "turn_in_progress": { "$ref": "#/components/examples/turn_in_progress" }, "operation_capacity_reached": { "$ref": "#/components/examples/operation_capacity_reached" }, "chat_closed": { "$ref": "#/components/examples/chat_closed" }, "version_conflict": { "$ref": "#/components/examples/version_conflict" } } } } }, "413": { "description": "payload_too_large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "payload_too_large": { "$ref": "#/components/examples/payload_too_large" } } } } }, "415": { "description": "unsupported_media_type", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unsupported_media_type": { "$ref": "#/components/examples/unsupported_media_type" } } } } }, "429": { "description": "rate_limited, chat_limit_reached", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "chat_limit_reached": { "$ref": "#/components/examples/chat_limit_reached" } } } } }, "500": { "description": "internal_error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } }, "503": { "description": "service_unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "service_unavailable": { "$ref": "#/components/examples/service_unavailable" } } } } } } } }, "/v1/channels/{channelKey}/chats/{chatId}/handoff": { "post": { "operationId": "requestHandoff", "summary": "Pass the chat to your team", "description": "Passes the chat to your team, accepting the agent's latest offer.", "parameters": [ { "name": "channelKey", "in": "path", "required": true, "description": "The channel's address. It's under Channel address on the agent's Chat key screen, and is the data-deployment value in the code you add to your website.", "schema": { "type": "string", "pattern": "^dep_[a-z0-9_-]{6,80}$", "examples": ["dep_example123"] } }, { "name": "chatId", "in": "path", "required": true, "description": "The chat's ID, from createChat.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,128}$", "examples": ["4b13b730-69d4-441c-8aee-42de75fef073"] } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "8–128 letters, digits or . _ : -, a UUID recommended. Repeat it to retry the same request safely.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{8,128}$", "examples": ["2f0a43a4-8c55-4c7e-9b8f-4b1bba0b1d6e"] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmationId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,128}$", "description": "From the message's handoffOffer.", "examples": ["4b13b730-69d4-441c-8aee-42de75fef073"] }, "email": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "An email address.", "examples": ["shopper@example.test"] }, "locale": { "type": "string", "maxLength": 64, "pattern": "^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$", "description": "A BCP 47 language tag. Chats default to en.", "examples": ["en-GB"] } }, "required": ["confirmationId"], "additionalProperties": false, "examples": [ { "confirmationId": "confirm_example123", "email": "shopper@example.test", "locale": "en-GB" } ] } } } }, "responses": { "200": { "description": "The first result, when the same Idempotency-Key is sent again.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/Chat" } }, "required": ["item"], "additionalProperties": false }, "examples": { "waiting": { "$ref": "#/components/examples/requestHandoff.waiting" } } } } }, "201": { "description": "Created.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/Chat" } }, "required": ["item"], "additionalProperties": false }, "examples": { "waiting": { "$ref": "#/components/examples/requestHandoff.waiting" } } } } }, "400": { "description": "invalid_id, invalid_json, invalid_request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_id": { "$ref": "#/components/examples/invalid_id" }, "invalid_json": { "$ref": "#/components/examples/invalid_json" }, "invalid_request": { "$ref": "#/components/examples/invalid_request" } } } } }, "401": { "description": "invalid_api_key", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "$ref": "#/components/examples/invalid_api_key" } } } } }, "403": { "description": "origin_not_allowed, channel_disabled, workspace_suspended", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "origin_not_allowed": { "$ref": "#/components/examples/origin_not_allowed" }, "channel_disabled": { "$ref": "#/components/examples/channel_disabled" }, "workspace_suspended": { "$ref": "#/components/examples/workspace_suspended" } } } } }, "404": { "description": "chat_not_found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "chat_not_found": { "$ref": "#/components/examples/chat_not_found" } } } } }, "409": { "description": "idempotency_conflict, turn_in_progress, operation_capacity_reached, chat_closed, confirmation_required, collection_incomplete", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_conflict": { "$ref": "#/components/examples/idempotency_conflict" }, "turn_in_progress": { "$ref": "#/components/examples/turn_in_progress" }, "operation_capacity_reached": { "$ref": "#/components/examples/operation_capacity_reached" }, "chat_closed": { "$ref": "#/components/examples/chat_closed" }, "confirmation_required": { "$ref": "#/components/examples/confirmation_required" }, "collection_incomplete": { "$ref": "#/components/examples/collection_incomplete" } } } } }, "413": { "description": "payload_too_large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "payload_too_large": { "$ref": "#/components/examples/payload_too_large" } } } } }, "415": { "description": "unsupported_media_type", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unsupported_media_type": { "$ref": "#/components/examples/unsupported_media_type" } } } } }, "429": { "description": "rate_limited, chat_limit_reached", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "chat_limit_reached": { "$ref": "#/components/examples/chat_limit_reached" } } } } }, "500": { "description": "internal_error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } }, "503": { "description": "service_unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "service_unavailable": { "$ref": "#/components/examples/service_unavailable" } } } } } } } } }, "components": { "schemas": { "Chat": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,128}$", "description": "The chat's ID. Keep it to send messages to the chat.", "examples": ["4b13b730-69d4-441c-8aee-42de75fef073"] }, "channelKey": { "type": "string", "pattern": "^dep_[a-z0-9_-]{6,80}$", "description": "The channel's address. It's under Channel address on the agent's Chat key screen, and is the data-deployment value in the code you add to your website.", "examples": ["dep_example123"] }, "userId": { "type": "string", "pattern": "^[A-Za-z0-9._:@-]{1,128}$", "description": "The customer's ID in this channel: your userId, one your website signed for the widget, or a random one for a guest. 1–128 letters, digits or . _ : @ -. It is not a sign-in.", "examples": ["shopper_123"] }, "mode": { "type": "string", "enum": ["agent", "waiting", "teammate", "resolved"], "description": "agent: the agent answers. waiting: waiting for your team. teammate: a teammate is answering. resolved: closed." }, "teammate": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string", "description": "The teammate's name." } }, "required": ["name"], "additionalProperties": false }, { "type": "null" } ], "description": "The teammate answering, while one is." }, "createdAt": { "description": "When the chat started.", "$ref": "#/components/schemas/Instant" }, "updatedAt": { "description": "When the chat last changed.", "$ref": "#/components/schemas/Instant" }, "resolvedAt": { "anyOf": [{ "$ref": "#/components/schemas/Instant" }, { "type": "null" }], "description": "When the chat was resolved." }, "historyComplete": { "type": "boolean", "description": "False when older messages are no longer kept." }, "handoff": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": ["waiting", "claimed", "resolved", "failed"], "description": "waiting: no teammate has it yet. claimed: a teammate has it. resolved: your team closed it. failed: it didn't reach your team." }, "requestedAt": { "description": "When the customer asked for your team.", "$ref": "#/components/schemas/Instant" }, "requiresEmail": { "type": "boolean", "description": "True when your team will reply by email, so the customer's email is needed." }, "nextAvailableAt": { "anyOf": [{ "$ref": "#/components/schemas/Instant" }, { "type": "null" }], "description": "When your team is next available; null when they are available now." }, "timezone": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Your team's support hours time zone.", "examples": ["Europe/London"] } }, "required": [ "status", "requestedAt", "requiresEmail", "nextAvailableAt", "timezone" ], "additionalProperties": false, "description": "The chat's current request to pass it to your team." }, { "type": "null" } ], "description": "The latest request to pass the chat to your team; null if there isn't one." } }, "required": [ "id", "channelKey", "userId", "mode", "teammate", "createdAt", "updatedAt", "resolvedAt", "historyComplete", "handoff" ], "additionalProperties": false, "description": "A chat between a customer and the channel's agent." }, "Collection": { "type": "object", "properties": { "version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Send it back as expectedVersion when you submit." }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/Field" }, "description": "Every field the chat's answers refer to." }, "values": { "type": "array", "items": { "type": "object", "properties": { "fieldId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "description": "1–128 letters, digits, underscores or hyphens, as your workspace set it.", "examples": ["field_email"] }, "value": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "status": { "type": "string", "enum": ["accepted", "declined", "unknown", "disputed"], "description": "Only an accepted value is an answer." }, "actor": { "type": "string", "enum": ["visitor", "teammate"], "description": "Who gave it: the customer (visitor) or a teammate." }, "updatedAt": { "$ref": "#/components/schemas/Instant" } }, "required": ["fieldId", "value", "status", "actor", "updatedAt"], "additionalProperties": false }, "description": "The answers so far." }, "request": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,128}$", "description": "Send it as collectionRequestId when you submit.", "examples": ["4b13b730-69d4-441c-8aee-42de75fef073"] }, "collectionId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "description": "1–128 letters, digits, underscores or hyphens, as your workspace set it.", "examples": ["field_email"] }, "purpose": { "type": "string", "description": "Why the agent is asking." }, "fields": { "type": "array", "items": { "type": "object", "properties": { "fieldId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "description": "1–128 letters, digits, underscores or hyphens, as your workspace set it.", "examples": ["field_email"] }, "required": { "type": "boolean" } }, "required": ["fieldId", "required"], "additionalProperties": false } }, "complete": { "type": "boolean", "description": "True once every required field is answered." }, "canSkip": { "type": "boolean", "description": "Whether the customer may skip the form." }, "canCancel": { "type": "boolean", "description": "Whether the customer may cancel the form." } }, "required": [ "id", "collectionId", "purpose", "fields", "complete", "canSkip", "canCancel" ], "additionalProperties": false }, { "type": "null" } ], "description": "The form the agent is asking the customer to fill in, if any." }, "missing": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "description": "1–128 letters, digits, underscores or hyphens, as your workspace set it.", "examples": ["field_email"] }, "description": "Required fields still unanswered." }, "pendingAction": { "anyOf": [{ "type": "string", "enum": ["handoff"] }, { "type": "null" }], "description": "handoff when the answers are for passing the chat to your team." }, "error": { "anyOf": [ { "type": "string", "enum": ["invalid_submission", "collection_incomplete", "confirmation_required"] }, { "type": "null" } ], "description": "Why the last submission wasn't saved, if it wasn't." } }, "required": ["version", "fields", "values", "request", "missing", "pendingAction", "error"], "additionalProperties": false, "description": "The details collected in a chat." }, "CollectionSubmission": { "type": "object", "properties": { "collectionRequestId": { "anyOf": [ { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,128}$", "description": "8–128 letters, digits, underscores or hyphens.", "examples": ["4b13b730-69d4-441c-8aee-42de75fef073"] }, { "type": "null" } ], "description": "request.id from the collection you read, or null if it had no request." }, "expectedVersion": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The collection's version when you read it." }, "action": { "type": "string", "enum": ["save", "skip", "cancel"] }, "values": { "description": "Answers by field ID.", "maxProperties": 20, "type": "object", "propertyNames": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "description": "1–128 letters, digits, underscores or hyphens, as your workspace set it.", "examples": ["field_email"] }, "additionalProperties": { "type": "string", "x-max-utf16-code-units": 2000 } }, "fieldIds": { "description": "Optional fields the customer skipped.", "maxItems": 20, "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "description": "1–128 letters, digits, underscores or hyphens, as your workspace set it.", "examples": ["field_email"] } } }, "required": ["collectionRequestId", "expectedVersion", "action"], "additionalProperties": false, "examples": [ { "collectionRequestId": "form_example123", "expectedVersion": 3, "action": "save", "values": { "field_email": "shopper@example.test" } } ] }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_json", "invalid_request", "invalid_id", "invalid_cursor", "invalid_submission", "unsupported_resume", "invalid_api_key", "origin_not_allowed", "channel_disabled", "workspace_suspended", "not_found", "chat_not_found", "file_not_found", "method_not_allowed", "unsupported_accept", "unsupported_media_type", "unsupported_file", "idempotency_conflict", "idempotency_key_expired", "turn_in_progress", "operation_interrupted", "operation_superseded", "operation_capacity_reached", "chat_closed", "version_conflict", "file_not_ready", "file_limit_reached", "file_storage_limit", "confirmation_required", "collection_incomplete", "cursor_expired", "idempotency_resource_gone", "payload_too_large", "rate_limited", "capacity_limited", "chat_limit_reached", "internal_error", "service_unavailable" ], "description": "What went wrong. Act on this." }, "message": { "type": "string", "description": "What went wrong, in words. It may change." }, "requestId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,128}$", "description": "Also sent as X-Request-Id. Quote it when you ask us about a request." }, "field": { "description": "A JSON pointer to the request field at fault.", "type": "string" }, "retryAfterSeconds": { "description": "Seconds to wait before trying again.", "type": "integer", "minimum": 1, "maximum": 2678400 } }, "required": ["code", "message", "requestId"], "additionalProperties": false } }, "required": ["error"], "additionalProperties": false, "description": "Why a request failed.", "examples": [ { "error": { "code": "rate_limited", "message": "Too many requests. Try again shortly.", "requestId": "rq_example", "retryAfterSeconds": 2 } } ] }, "Field": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "description": "1–128 letters, digits, underscores or hyphens, as your workspace set it.", "examples": ["field_email"] }, "label": { "type": "string", "description": "What the customer is asked." }, "description": { "type": "string", "description": "More about what to enter, if anything." }, "type": { "type": "string", "enum": ["text", "email", "choice"] }, "choices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "description": "1–128 letters, digits, underscores or hyphens, as your workspace set it.", "examples": ["field_email"] }, "label": { "type": "string" } }, "required": ["id", "label"], "additionalProperties": false }, "description": "A choice field's options. Its answer is the chosen option's id." } }, "required": ["id", "label", "description", "type", "choices"], "additionalProperties": false, "description": "A detail the agent can ask for." }, "File": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,128}$", "description": "The file's ID. Send it in a message's fileIds.", "examples": ["4b13b730-69d4-441c-8aee-42de75fef073"] }, "chatId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,128}$", "description": "The chat's ID.", "examples": ["4b13b730-69d4-441c-8aee-42de75fef073"] }, "filename": { "type": "string", "description": "The file's name when it was uploaded." }, "mediaType": { "type": "string", "description": "The file's type.", "examples": ["image/jpeg"] }, "byteSize": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The file's size in bytes." }, "createdAt": { "description": "When the file was uploaded.", "$ref": "#/components/schemas/Instant" }, "expiresAt": { "anyOf": [{ "$ref": "#/components/schemas/Instant" }, { "type": "null" }], "description": "When an unsent file is deleted; null once it is sent with a message." } }, "required": ["id", "chatId", "filename", "mediaType", "byteSize", "createdAt", "expiresAt"], "additionalProperties": false, "description": "A file uploaded to a chat." }, "HandoffOffer": { "type": "object", "properties": { "confirmationId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,128}$", "description": "Send it to requestHandoff to accept the offer.", "examples": ["4b13b730-69d4-441c-8aee-42de75fef073"] }, "requiresEmail": { "type": "boolean", "description": "True when your team will reply by email, so the customer's email is needed." }, "nextAvailableAt": { "anyOf": [{ "$ref": "#/components/schemas/Instant" }, { "type": "null" }], "description": "When your team is next available; null when they are available now." }, "timezone": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "Your team's support hours time zone.", "examples": ["Europe/London"] } }, "required": ["confirmationId", "requiresEmail", "nextAvailableAt", "timezone"], "additionalProperties": false, "description": "An offer to pass the chat to your team. Accept it with requestHandoff." }, "Instant": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$", "description": "A UTC time with milliseconds.", "examples": ["2026-10-12T00:00:00.000Z"] }, "Message": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,128}$", "description": "The message's ID.", "examples": ["4b13b730-69d4-441c-8aee-42de75fef073"] }, "chatId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,128}$", "description": "The chat's ID.", "examples": ["4b13b730-69d4-441c-8aee-42de75fef073"] }, "role": { "type": "string", "enum": ["visitor", "agent", "teammate", "system"], "description": "Who sent it: the customer (visitor), the agent, a teammate, or system for a notice." }, "text": { "type": "string", "description": "The message, as plain text." }, "createdAt": { "anyOf": [{ "$ref": "#/components/schemas/Instant" }, { "type": "null" }], "description": "Null for some older messages." }, "author": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string", "description": "The teammate's name." } }, "required": ["name"], "additionalProperties": false }, { "type": "null" } ], "description": "The teammate who sent it, for a teammate's message." }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/File" }, "description": "Files sent with the message." }, "citations": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "The source's title." }, "url": { "anyOf": [{ "type": "string", "format": "uri" }, { "type": "null" }], "description": "The source's address, if it has one." }, "updatedAt": { "anyOf": [{ "$ref": "#/components/schemas/Instant" }, { "type": "null" }], "description": "When it last changed, if known." } }, "required": ["title", "url", "updatedAt"], "additionalProperties": false }, "description": "Where the agent's answer came from, such as pages of your website." }, "products": { "maxItems": 3, "type": "array", "items": { "$ref": "#/components/schemas/Product" }, "description": "Products the agent showed." }, "orders": { "maxItems": 10, "type": "array", "items": { "$ref": "#/components/schemas/Order" }, "description": "Orders the agent looked up." }, "choices": { "type": "array", "items": { "type": "string" }, "description": "Replies the customer can pick. Send one as the next message's text." }, "collection": { "anyOf": [{ "$ref": "#/components/schemas/Collection" }, { "type": "null" }], "description": "The collection when the message asks the customer to fill in a form." }, "handoffOffer": { "anyOf": [{ "$ref": "#/components/schemas/HandoffOffer" }, { "type": "null" }], "description": "The agent's offer to pass the chat to your team, if it made one." } }, "required": [ "id", "chatId", "role", "text", "createdAt", "author", "files", "citations", "products", "orders", "choices", "collection", "handoffOffer" ], "additionalProperties": false, "description": "One message in a chat." }, "MessageTurn": { "type": "object", "properties": { "message": { "$ref": "#/components/schemas/Message" }, "reply": { "anyOf": [{ "$ref": "#/components/schemas/Message" }, { "type": "null" }], "description": "The agent's reply, or null while the chat is with your team." }, "chat": { "$ref": "#/components/schemas/Chat" } }, "required": ["message", "reply", "chat"], "additionalProperties": false, "description": "A message sent, its reply and the chat afterwards." }, "Order": { "type": "object", "properties": { "reference": { "type": "string", "description": "How the customer knows it.", "examples": ["Web order 12345"] }, "kind": { "type": "string", "enum": ["online", "workshop", "order"], "description": "online: a website order. workshop: a repair or service job. order: a customer order placed in a shop." }, "status": { "type": "string", "description": "Your shop's own wording." }, "complete": { "type": "boolean", "description": "Closed in your shop's system: finished and handed over." }, "placedLabel": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "When it was placed, as a label." }, "dueLabel": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "When it is due, as a label." }, "servicedItem": { "anyOf": [{ "type": "string" }, { "type": "null" }], "description": "The item being repaired or serviced." }, "items": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string", "description": "What the item is." }, "quantity": { "type": "number", "minimum": 0 }, "arrived": { "anyOf": [{ "type": "boolean" }, { "type": "null" }], "description": "Whether an item ordered in has arrived; null when unknown." } }, "required": ["description", "quantity", "arrived"], "additionalProperties": false } }, "store": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "anyOf": [{ "type": "string" }, { "type": "null" }] } }, "required": ["name", "phone"], "additionalProperties": false }, { "type": "null" } ], "description": "The shop that has it, if it's in one." } }, "required": [ "reference", "kind", "status", "complete", "placedLabel", "dueLabel", "servicedItem", "items", "store" ], "additionalProperties": false, "description": "An order the agent looked up." }, "Product": { "type": "object", "properties": { "id": { "type": "string", "description": "The product's ID in your catalogue." }, "title": { "type": "string" }, "brand": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "imageUrl": { "anyOf": [{ "type": "string", "format": "uri" }, { "type": "null" }], "description": "A picture of the product." }, "productUrl": { "anyOf": [{ "type": "string", "format": "uri" }, { "type": "null" }], "description": "The product's page on your website." }, "inStock": { "anyOf": [{ "type": "boolean" }, { "type": "null" }], "description": "Null when stock is unknown." }, "clickAndCollectOnly": { "type": "boolean", "description": "True when it can only be collected from a shop, not delivered." }, "price": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "number", "minimum": 0, "description": "In the currency's main unit." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "An ISO 4217 code.", "examples": ["GBP"] }, "was": { "anyOf": [{ "type": "number", "minimum": 0 }, { "type": "null" }], "description": "The price before a sale." }, "from": { "type": "boolean", "description": "True when amount is the lowest of several prices." } }, "required": ["amount", "currency", "was", "from"], "additionalProperties": false }, { "type": "null" } ], "description": "Null when the price is unknown." } }, "required": [ "id", "title", "brand", "imageUrl", "productUrl", "inStock", "clickAndCollectOnly", "price" ], "additionalProperties": false, "description": "A product the agent showed." } }, "securitySchemes": { "chatKey": { "type": "http", "scheme": "bearer", "bearerFormat": "ck_ and 64 lowercase hex digits", "description": "The agent's chat key, from Advanced in its settings. Keep it on your server." } }, "headers": { "X-Request-Id": { "description": "Identifies the request. Quote it if you ask us about one.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests the channel can make in the current window.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Seconds until the window resets.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds to wait before sending the request again. Always sent with 429.", "schema": { "type": "integer", "minimum": 1, "maximum": 2678400 } }, "Content-Disposition": { "description": "The file's name. Images are inline; other files are attachments.", "schema": { "type": "string" } } }, "examples": { "createChat.created": { "value": { "item": { "id": "4b13b730-69d4-441c-8aee-42de75fef073", "channelKey": "dep_example123", "userId": "shopper_123", "mode": "agent", "teammate": null, "createdAt": "2026-10-12T09:00:00.000Z", "updatedAt": "2026-10-12T09:00:00.000Z", "resolvedAt": null, "historyComplete": true, "handoff": null } } }, "getChat.teammate": { "value": { "item": { "id": "4b13b730-69d4-441c-8aee-42de75fef073", "channelKey": "dep_example123", "userId": "shopper_123", "mode": "teammate", "teammate": { "name": "Alex" }, "createdAt": "2026-10-12T09:00:00.000Z", "updatedAt": "2026-10-12T09:04:00.000Z", "resolvedAt": null, "historyComplete": true, "handoff": { "status": "claimed", "requestedAt": "2026-10-12T09:02:00.000Z", "requiresEmail": false, "nextAvailableAt": null, "timezone": "Europe/London" } } } }, "sendMessage.answered": { "value": { "item": { "message": { "id": "29a1fb72-55e2-44c6-bf21-a21f8e25fbc1", "chatId": "4b13b730-69d4-441c-8aee-42de75fef073", "role": "visitor", "text": "When are you open?", "createdAt": "2026-10-12T09:00:01.000Z", "author": null, "files": [], "citations": [], "products": [], "orders": [], "choices": [], "collection": null, "handoffOffer": null }, "reply": { "id": "8f0e2d6c-3b1a-4f5e-9c7d-2a6b4e8f1c3d", "chatId": "4b13b730-69d4-441c-8aee-42de75fef073", "role": "agent", "text": "We're open 9am to 5:30pm Monday to Saturday, and 10am to 4pm on Sunday.", "createdAt": "2026-10-12T09:00:03.000Z", "author": null, "files": [], "citations": [ { "title": "Opening times", "url": "https://shop.example/pages/opening-times", "updatedAt": "2026-10-01T08:00:00.000Z" } ], "products": [], "orders": [], "choices": [], "collection": null, "handoffOffer": null }, "chat": { "id": "4b13b730-69d4-441c-8aee-42de75fef073", "channelKey": "dep_example123", "userId": "shopper_123", "mode": "agent", "teammate": null, "createdAt": "2026-10-12T09:00:00.000Z", "updatedAt": "2026-10-12T09:00:03.000Z", "resolvedAt": null, "historyComplete": true, "handoff": null } } } }, "sendMessage.waiting": { "value": { "item": { "message": { "id": "29a1fb72-55e2-44c6-bf21-a21f8e25fbc1", "chatId": "4b13b730-69d4-441c-8aee-42de75fef073", "role": "visitor", "text": "Is anyone there?", "createdAt": "2026-10-12T19:30:00.000Z", "author": null, "files": [], "citations": [], "products": [], "orders": [], "choices": [], "collection": null, "handoffOffer": null }, "reply": null, "chat": { "id": "4b13b730-69d4-441c-8aee-42de75fef073", "channelKey": "dep_example123", "userId": "shopper_123", "mode": "waiting", "teammate": null, "createdAt": "2026-10-12T09:00:00.000Z", "updatedAt": "2026-10-12T19:30:00.000Z", "resolvedAt": null, "historyComplete": true, "handoff": { "status": "waiting", "requestedAt": "2026-10-12T19:28:00.000Z", "requiresEmail": true, "nextAvailableAt": "2026-10-13T08:00:00.000Z", "timezone": "Europe/London" } } } } }, "listMessages.page": { "value": { "items": [ { "id": "29a1fb72-55e2-44c6-bf21-a21f8e25fbc1", "chatId": "4b13b730-69d4-441c-8aee-42de75fef073", "role": "visitor", "text": "When are you open?", "createdAt": "2026-10-12T09:00:01.000Z", "author": null, "files": [], "citations": [], "products": [], "orders": [], "choices": [], "collection": null, "handoffOffer": null }, { "id": "8f0e2d6c-3b1a-4f5e-9c7d-2a6b4e8f1c3d", "chatId": "4b13b730-69d4-441c-8aee-42de75fef073", "role": "agent", "text": "We're open 9am to 5:30pm Monday to Saturday, and 10am to 4pm on Sunday.", "createdAt": "2026-10-12T09:00:03.000Z", "author": null, "files": [], "citations": [ { "title": "Opening times", "url": "https://shop.example/pages/opening-times", "updatedAt": "2026-10-01T08:00:00.000Z" } ], "products": [], "orders": [], "choices": [], "collection": null, "handoffOffer": null }, { "id": "c5d0a8e2-7f14-4b9a-a3e6-1d2c9b8f7e60", "chatId": "4b13b730-69d4-441c-8aee-42de75fef073", "role": "visitor", "text": "Have you got a helmet for a 4-year-old?", "createdAt": "2026-10-12T09:00:20.000Z", "author": null, "files": [], "citations": [], "products": [], "orders": [], "choices": [], "collection": null, "handoffOffer": null }, { "id": "e1b7f3a9-2c6d-4e80-9f5a-6b3d1c0a8e24", "chatId": "4b13b730-69d4-441c-8aee-42de75fef073", "role": "agent", "text": "This one fits heads from 48 to 52 cm, which suits most 4-year-olds.", "createdAt": "2026-10-12T09:00:23.000Z", "author": null, "files": [], "citations": [], "products": [ { "id": "kids-helmet-48-52", "title": "Kids' cycle helmet, 48–52 cm", "brand": "Trailcraft", "imageUrl": "https://shop.example/images/kids-helmet.jpg", "productUrl": "https://shop.example/products/kids-helmet", "inStock": true, "clickAndCollectOnly": false, "price": { "amount": 29.99, "currency": "GBP", "was": 34.99, "from": false } } ], "orders": [], "choices": ["Show me other sizes", "Talk to the team"], "collection": null, "handoffOffer": null } ], "nextCursor": null } }, "uploadFile.uploaded": { "value": { "item": { "id": "file_7Qx2mLr9Kd", "chatId": "4b13b730-69d4-441c-8aee-42de75fef073", "filename": "receipt.pdf", "mediaType": "application/pdf", "byteSize": 48213, "createdAt": "2026-10-12T09:02:00.000Z", "expiresAt": "2026-10-13T09:02:00.000Z" } } }, "getCollection.form": { "value": { "item": { "version": 3, "fields": [ { "id": "field_name", "label": "Your name", "description": "", "type": "text", "choices": [] }, { "id": "field_email", "label": "Email", "description": "So the team can reply if you leave.", "type": "email", "choices": [] } ], "values": [ { "fieldId": "field_name", "value": "Sam Taylor", "status": "accepted", "actor": "visitor", "updatedAt": "2026-10-12T09:01:10.000Z" } ], "request": { "id": "form_example123", "collectionId": "collection_contact", "purpose": "So the team can get back to you.", "fields": [ { "fieldId": "field_name", "required": true }, { "fieldId": "field_email", "required": true } ], "complete": false, "canSkip": false, "canCancel": true }, "missing": ["field_email"], "pendingAction": "handoff", "error": null } } }, "submitCollection.saved": { "value": { "item": { "version": 4, "fields": [ { "id": "field_name", "label": "Your name", "description": "", "type": "text", "choices": [] }, { "id": "field_email", "label": "Email", "description": "So the team can reply if you leave.", "type": "email", "choices": [] } ], "values": [ { "fieldId": "field_name", "value": "Sam Taylor", "status": "accepted", "actor": "visitor", "updatedAt": "2026-10-12T09:01:10.000Z" }, { "fieldId": "field_email", "value": "sam@example.test", "status": "accepted", "actor": "visitor", "updatedAt": "2026-10-12T09:01:30.000Z" } ], "request": { "id": "form_example123", "collectionId": "collection_contact", "purpose": "So the team can get back to you.", "fields": [ { "fieldId": "field_name", "required": true }, { "fieldId": "field_email", "required": true } ], "complete": true, "canSkip": false, "canCancel": true }, "missing": [], "pendingAction": "handoff", "error": null } } }, "requestHandoff.waiting": { "value": { "item": { "id": "4b13b730-69d4-441c-8aee-42de75fef073", "channelKey": "dep_example123", "userId": "shopper_123", "mode": "waiting", "teammate": null, "createdAt": "2026-10-12T09:00:00.000Z", "updatedAt": "2026-10-12T19:28:00.000Z", "resolvedAt": null, "historyComplete": true, "handoff": { "status": "waiting", "requestedAt": "2026-10-12T19:28:00.000Z", "requiresEmail": true, "nextAvailableAt": "2026-10-13T08:00:00.000Z", "timezone": "Europe/London" } } } }, "invalid_json": { "summary": "The body isn't a JSON object.", "description": "Send a JSON object with Content-Type: application/json.", "value": { "error": { "code": "invalid_json", "message": "The body isn't a JSON object.", "requestId": "rq_3f1c9a7e5b2d4c6a" } } }, "invalid_request": { "summary": "The request isn't valid.", "description": "Fix the field named in error.field, then send it again.", "value": { "error": { "code": "invalid_request", "message": "The request isn't valid.", "requestId": "rq_3f1c9a7e5b2d4c6a", "field": "/userId" } } }, "invalid_id": { "summary": "An ID in the path isn't valid.", "description": "Use the ID exactly as the API returned it.", "value": { "error": { "code": "invalid_id", "message": "An ID in the path isn't valid.", "requestId": "rq_3f1c9a7e5b2d4c6a" } } }, "invalid_cursor": { "summary": "The cursor isn't valid.", "description": "Send nextCursor exactly as the last page returned it, or start without one.", "value": { "error": { "code": "invalid_cursor", "message": "The cursor isn't valid.", "requestId": "rq_3f1c9a7e5b2d4c6a" } } }, "invalid_submission": { "summary": "Some answers aren't valid.", "description": "Read the collection again, fix the answers and submit.", "value": { "error": { "code": "invalid_submission", "message": "Some answers aren't valid.", "requestId": "rq_3f1c9a7e5b2d4c6a" } } }, "unsupported_resume": { "summary": "Streams can't be resumed.", "description": "Send the message again with the same Idempotency-Key, or list the messages.", "value": { "error": { "code": "unsupported_resume", "message": "Streams can't be resumed.", "requestId": "rq_3f1c9a7e5b2d4c6a" } } }, "invalid_api_key": { "summary": "The chat key isn't valid for this channel.", "description": "Send Authorization: Bearer and the agent's chat key, from Advanced in its settings.", "value": { "error": { "code": "invalid_api_key", "message": "The chat key isn't valid for this channel.", "requestId": "rq_3f1c9a7e5b2d4c6a" } } }, "origin_not_allowed": { "summary": "Browsers can't use the API.", "description": "Call the API from your server, which keeps the key secret.", "value": { "error": { "code": "origin_not_allowed", "message": "Browsers can't use the API.", "requestId": "rq_3f1c9a7e5b2d4c6a" } } }, "channel_disabled": { "summary": "This channel is turned off.", "description": "Publish the agent again.", "value": { "error": { "code": "channel_disabled", "message": "This channel is turned off.", "requestId": "rq_3f1c9a7e5b2d4c6a" } } }, "workspace_suspended": { "summary": "This workspace is suspended.", "description": "Contact us to restore it.", "value": { "error": { "code": "workspace_suspended", "message": "This workspace is suspended.", "requestId": "rq_3f1c9a7e5b2d4c6a" } } }, "not_found": { "summary": "API route not found.", "description": "Check the method and path against the API reference.", "value": { "error": { "code": "not_found", "message": "API route not found.", "requestId": "rq_3f1c9a7e5b2d4c6a" } } }, "chat_not_found": { "summary": "Chat not found.", "description": "Use a chat ID this channel created. Deleted chats are gone.", "value": { "error": { "code": "chat_not_found", "message": "Chat not found.", "requestId": "rq_3f1c9a7e5b2d4c6a" } } }, "file_not_found": { "summary": "File not found.", "description": "Use a file ID uploaded to this chat.", "value": { "error": { "code": "file_not_found", "message": "File not found.", "requestId": "rq_3f1c9a7e5b2d4c6a" } } }, "method_not_allowed": { "summary": "Method not allowed for this route.", "description": "Use a method the Allow header lists.", "value": { "error": { "code": "method_not_allowed", "message": "Method not allowed for this route.", "requestId": "rq_3f1c9a7e5b2d4c6a" } } }, "unsupported_accept": { "summary": "The Accept header asks for a format the API doesn't send.", "description": "Accept application/json or, to stream a reply, text/event-stream.", "value": { "error": { "code": "unsupported_accept", "message": "The Accept header asks for a format the API doesn't send.", "requestId": "rq_3f1c9a7e5b2d4c6a" } } }, "unsupported_media_type": { "summary": "The Content-Type isn't supported here.", "description": "Send application/json, or multipart/form-data to upload a file.", "value": { "error": { "code": "unsupported_media_type", "message": "The Content-Type isn't supported here.", "requestId": "rq_3f1c9a7e5b2d4c6a" } } }, "unsupported_file": { "summary": "This type of file isn't supported.", "description": "Upload a JPEG, PNG, GIF, WebP, PDF or plain text file.", "value": { "error": { "code": "unsupported_file", "message": "This type of file isn't supported.", "requestId": "rq_3f1c9a7e5b2d4c6a" } } }, "idempotency_conflict": { "summary": "This Idempotency-Key was used for a different request.", "description": "Use a new key for a new request.", "value": { "error": { "code": "idempotency_conflict", "message": "This Idempotency-Key was used for a different request.", "requestId": "rq_3f1c9a7e5b2d4c6a" } } }, "idempotency_key_expired": { "summary": "This Idempotency-Key has expired.", "description": "Read the resource to see what happened, then use a new key.", "value": { "error": { "code": "idempotency_key_expired", "message": "This Idempotency-Key has expired.", "requestId": "rq_3f1c9a7e5b2d4c6a" } } }, "turn_in_progress": { "summary": "The chat is still answering a message.", "description": "Wait for the reply, then send again.", "value": { "error": { "code": "turn_in_progress", "message": "The chat is still answering a message.", "requestId": "rq_3f1c9a7e5b2d4c6a" } } }, "operation_interrupted": { "summary": "This request was interrupted and its result is unknown.", "description": "List the messages to see what happened before sending anything new.", "value": { "error": { "code": "operation_interrupted", "message": "This request was interrupted and its result is unknown.", "requestId": "rq_3f1c9a7e5b2d4c6a" } } }, "operation_superseded": { "summary": "The chat moved on before this request finished.", "description": "Read the chat, then decide whether to send a new request.", "value": { "error": { "code": "operation_superseded", "message": "The chat moved on before this request finished.", "requestId": "rq_3f1c9a7e5b2d4c6a" } } }, "operation_capacity_reached": { "summary": "This chat can't take more requests.", "description": "Start a new chat.", "value": { "error": { "code": "operation_capacity_reached", "message": "This chat can't take more requests.", "requestId": "rq_3f1c9a7e5b2d4c6a" } } }, "chat_closed": { "summary": "This chat is resolved.", "description": "Start a new chat.", "value": { "error": { "code": "chat_closed", "message": "This chat is resolved.", "requestId": "rq_3f1c9a7e5b2d4c6a" } } }, "version_conflict": { "summary": "The collection changed since you read it.", "description": "Read the collection again, keep the customer's answers and submit with its version.", "value": { "error": { "code": "version_conflict", "message": "The collection changed since you read it.", "requestId": "rq_3f1c9a7e5b2d4c6a" } } }, "file_not_ready": { "summary": "The file isn't ready yet.", "description": "Upload it again with the same Idempotency-Key.", "value": { "error": { "code": "file_not_ready", "message": "The file isn't ready yet.", "requestId": "rq_3f1c9a7e5b2d4c6a" } } }, "file_limit_reached": { "summary": "This chat has 40 files already.", "description": "Start a new chat to send more.", "value": { "error": { "code": "file_limit_reached", "message": "This chat has 40 files already.", "requestId": "rq_3f1c9a7e5b2d4c6a" } } }, "file_storage_limit": { "summary": "This chat's files would go over 80 MiB.", "description": "Send a smaller file or start a new chat.", "value": { "error": { "code": "file_storage_limit", "message": "This chat's files would go over 80 MiB.", "requestId": "rq_3f1c9a7e5b2d4c6a" } } }, "confirmation_required": { "summary": "Passing the chat to your team needs a current offer.", "description": "List the messages for the latest handoffOffer and use its confirmationId.", "value": { "error": { "code": "confirmation_required", "message": "Passing the chat to your team needs a current offer.", "requestId": "rq_3f1c9a7e5b2d4c6a" } } }, "collection_incomplete": { "summary": "Some required answers are missing.", "description": "Fill in the fields listed in missing, then submit.", "value": { "error": { "code": "collection_incomplete", "message": "Some required answers are missing.", "requestId": "rq_3f1c9a7e5b2d4c6a" } } }, "cursor_expired": { "summary": "Messages on this page are no longer kept.", "description": "Start listing again without a cursor.", "value": { "error": { "code": "cursor_expired", "message": "Messages on this page are no longer kept.", "requestId": "rq_3f1c9a7e5b2d4c6a" } } }, "idempotency_resource_gone": { "summary": "The chat this Idempotency-Key created was deleted.", "description": "Use a new key to start a new chat.", "value": { "error": { "code": "idempotency_resource_gone", "message": "The chat this Idempotency-Key created was deleted.", "requestId": "rq_3f1c9a7e5b2d4c6a" } } }, "payload_too_large": { "summary": "Request too large.", "description": "Send at most 32 KiB of JSON, or a file up to 4 MiB.", "value": { "error": { "code": "payload_too_large", "message": "Request too large.", "requestId": "rq_3f1c9a7e5b2d4c6a" } } }, "rate_limited": { "summary": "Too many requests. Try again shortly.", "description": "Wait for Retry-After seconds, then send the same request again.", "value": { "error": { "code": "rate_limited", "message": "Too many requests. Try again shortly.", "requestId": "rq_3f1c9a7e5b2d4c6a", "retryAfterSeconds": 2 } } }, "capacity_limited": { "summary": "Too many chats are open right now.", "description": "Wait for Retry-After seconds, then try again.", "value": { "error": { "code": "capacity_limited", "message": "Too many chats are open right now.", "requestId": "rq_3f1c9a7e5b2d4c6a", "retryAfterSeconds": 30 } } }, "chat_limit_reached": { "summary": "This workspace has used its chats for the month.", "description": "Wait for Retry-After seconds or add chats to the plan.", "value": { "error": { "code": "chat_limit_reached", "message": "This workspace has used its chats for the month.", "requestId": "rq_3f1c9a7e5b2d4c6a", "retryAfterSeconds": 1209600 } } }, "internal_error": { "summary": "Something went wrong. Please try again.", "description": "Send the same request again with the same Idempotency-Key.", "value": { "error": { "code": "internal_error", "message": "Something went wrong. Please try again.", "requestId": "rq_3f1c9a7e5b2d4c6a" } } }, "service_unavailable": { "summary": "The API is unavailable. Try again shortly.", "description": "Wait for Retry-After seconds, then send the same request again.", "value": { "error": { "code": "service_unavailable", "message": "The API is unavailable. Try again shortly.", "requestId": "rq_3f1c9a7e5b2d4c6a", "retryAfterSeconds": 5 } } } } } }