{ "openapi": "3.1.0", "info": { "title": "Takechat adapter", "version": "1.2.1", "description": "One authenticated workspace per mount. GETs are no-store; timestamps ISO 8601; country is ISO 3166-1 alpha-2. Errors are {error, code?}; code is a snake_case reason (conversation_closed, channel_restricted, idempotency_conflict, rate_limited, invalid_request, unauthorized, forbidden, not_found, too_large, unavailable) and clients treat unknown codes by HTTP status. Sending must atomically persist a clientMessageId reservation and return the canonical outcome on replay, even after closing. Never redeliver an unknown outcome. Optional conversation customerId is a global : ID, stable for the same person across every workspace the issuer serves and never derived from contact details. Optional source names the store, inbox or brand a conversation came from. Optional updatedAt changes on any message, state, delivery status, priority or source change. Optional ai guides the operator's AI; its channels keys are conversation.channel values. Message text is Markdown without images from the business and plain text from the customer. fallback means the text stands in for non-text content such as a tool call or media; write it for a person, with any result to open (a generated image, a file) as a Markdown link to a lasting HTTPS URL, never raw tool input or JSON. When deliveryStatus is present, deliveryFailed equals deliveryStatus == failed. See the one-page website for provider obligations." }, "servers": [ { "url": "https://adapter.example.com/api/desk/v1" } ], "components": { "securitySchemes": { "operatorKey": { "type": "http", "scheme": "bearer" } } }, "paths": { "/info": { "get": { "security": [ { "operatorKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "protocolVersion": { "type": "number", "const": 1 }, "workspace": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 300 }, "name": { "type": "string", "minLength": 1, "maxLength": 300 } }, "required": [ "id", "name" ], "additionalProperties": false }, "operator": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 300 }, "name": { "type": "string", "minLength": 1, "maxLength": 300 } }, "required": [ "id", "name" ], "additionalProperties": false }, "capabilities": { "type": "object", "properties": { "setState": { "type": "boolean" }, "sendMessage": { "default": false, "type": "boolean" }, "paging": { "default": false, "type": "boolean" }, "priority": { "default": false, "type": "boolean" } }, "required": [ "setState", "sendMessage", "paging", "priority" ], "additionalProperties": false }, "ai": { "anyOf": [ { "type": "object", "properties": { "instructions": { "type": "string", "minLength": 1, "maxLength": 40000 }, "channels": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "maxLength": 12000 } } }, "required": [ "instructions", "channels" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "protocolVersion", "workspace", "operator", "capabilities" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9_]+$" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "401": { "description": "Invalid key", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9_]+$" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9_]+$" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9_]+$" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "409": { "description": "State or idempotency conflict: code conversation_closed, channel_restricted or idempotency_conflict", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9_]+$" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "413": { "description": "Body too large", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9_]+$" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "429": { "description": "Rate limited: code rate_limited", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9_]+$" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "503": { "description": "Unavailable or invalid backend output", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9_]+$" } }, "required": [ "error" ], "additionalProperties": {} } } } } } } }, "/conversations": { "get": { "security": [ { "operatorKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversations": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 300 }, "channel": { "type": "string", "minLength": 1, "maxLength": 300 }, "visitorId": { "type": [ "string", "null" ] }, "customerId": { "description": "Global customer ID as :, issued under a domain the provider controls. The same person gets the same value in every workspace the issuer serves; never reassign it. Must not contain or be derived from email, phone or name. Null or omitted when the person is not verified; clients treat identical strings as the same person.", "anyOf": [ { "type": "string", "maxLength": 300, "pattern": "^[a-z0-9-]+(\\.[a-z0-9-]+)+:[\\x21-\\x7e]+$" }, { "type": "null" } ] }, "source": { "description": "The store, inbox, brand or page this conversation came from, when one workspace mixes several. id is stable and opaque within the workspace, for grouping and filtering; name is shown to operators. Never contact details. Null or omitted when the workspace has one source.", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 300 }, "name": { "type": "string", "minLength": 1, "maxLength": 300 } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "contactName": { "type": [ "string", "null" ] }, "contactEmail": { "type": [ "string", "null" ] }, "contactPhone": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "startedAt": { "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+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "lastMessageAt": { "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+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "updatedAt": { "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+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "lastRole": { "anyOf": [ { "type": "string", "enum": [ "user", "assistant" ] }, { "type": "null" } ] }, "lastText": { "type": [ "string", "null" ] }, "state": { "type": "string", "enum": [ "open", "closed" ] }, "priority": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] } }, "required": [ "id", "channel", "visitorId", "contactName", "contactEmail", "contactPhone", "country", "startedAt", "lastMessageAt", "lastRole", "lastText", "state" ], "additionalProperties": false } }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] } }, "required": [ "conversations" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9_]+$" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "401": { "description": "Invalid key", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9_]+$" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9_]+$" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9_]+$" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "409": { "description": "State or idempotency conflict: code conversation_closed, channel_restricted or idempotency_conflict", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9_]+$" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "413": { "description": "Body too large", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9_]+$" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "429": { "description": "Rate limited: code rate_limited", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9_]+$" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "503": { "description": "Unavailable or invalid backend output", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9_]+$" } }, "required": [ "error" ], "additionalProperties": {} } } } } }, "description": "Ordered by lastMessageAt descending, then id descending, at most 100 per page. lastMessageAt is the last message's time; state changes, rescoring and contact edits do not move a conversation. With capabilities.paging the list takes state, limit and cursor and returns nextCursor; with capabilities.priority each conversation carries priority and sort=priority is accepted. Adapters without paging ignore these parameters and return one page.", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 200 }, "description": "Optional contact search across the full store, applied before paging." }, { "name": "state", "in": "query", "schema": { "type": "string", "enum": [ "open", "closed" ] }, "description": "Only conversations in this state, applied like q before limit and paging. Needs capabilities.paging." }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "recent", "priority" ], "default": "recent" }, "description": "recent: lastMessageAt descending, then id descending. priority: priority descending with unscored (null) last, then lastMessageAt and id descending. priority needs capabilities.priority; otherwise 400." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "description": "Page size. Needs capabilities.paging." }, { "name": "cursor", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 500 }, "description": "The previous page's nextCursor, passed back unchanged with the same q, state and sort. Opaque; a keyset position such as the last row's (priority, lastMessageAt, id), so pages stay consistent while conversations are added or rescored. Invalid cursors return 400." } ] } }, "/conversations/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 300 } } ], "patch": { "security": [ { "operatorKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "state": { "type": "string", "enum": [ "open", "closed" ] } }, "required": [ "state" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9_]+$" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "401": { "description": "Invalid key", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9_]+$" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9_]+$" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9_]+$" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "409": { "description": "State or idempotency conflict: code conversation_closed, channel_restricted or idempotency_conflict", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9_]+$" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "413": { "description": "Body too large", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9_]+$" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "429": { "description": "Rate limited: code rate_limited", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9_]+$" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "503": { "description": "Unavailable or invalid backend output", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9_]+$" } }, "required": [ "error" ], "additionalProperties": {} } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "state": { "type": "string", "enum": [ "open", "closed" ] } }, "required": [ "state" ], "additionalProperties": false } } } } } }, "/conversations/{id}/messages": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 300 } } ], "get": { "security": [ { "operatorKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "messages": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 300 }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "text": { "type": "string", "description": "What the operator reads. Business (assistant) text is Markdown without images: links, emphasis, lists, tables and code. Customer text is plain; bare URLs become links." }, "createdAt": { "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+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "fallback": { "type": "boolean", "description": "text stands in for content that isn't text, such as a tool call or media. Write it for a person: what happened and its result, with anything to open (a generated image, a file) as a Markdown link to a lasting HTTPS URL, [Generated image](https://…). Never raw tool input or JSON, internal or credential-bearing URLs, or links that expire while the message is listed." }, "deliveryFailed": { "type": "boolean" }, "clientMessageId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "operator": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 300 }, "name": { "type": "string", "minLength": 1, "maxLength": 300 } }, "required": [ "id", "name" ], "additionalProperties": false }, "deliveryStatus": { "type": "string", "enum": [ "pending", "sent", "delivered", "failed", "unknown" ] } }, "required": [ "id", "role", "text", "createdAt", "fallback", "deliveryFailed" ], "additionalProperties": false } }, "truncated": { "type": "boolean" }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 4096 }, { "type": "null" } ] }, "reply": { "type": "object", "properties": { "allowed": { "type": "boolean" }, "reason": { "type": [ "string", "null" ] }, "maxLength": { "type": "integer", "minimum": 1, "maximum": 8000 } }, "required": [ "allowed", "reason", "maxLength" ], "additionalProperties": false } }, "required": [ "messages" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9_]+$" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "401": { "description": "Invalid key", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9_]+$" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9_]+$" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9_]+$" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "409": { "description": "State or idempotency conflict: code conversation_closed, channel_restricted or idempotency_conflict", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9_]+$" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "413": { "description": "Body too large", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9_]+$" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "429": { "description": "Rate limited: code rate_limited", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9_]+$" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "503": { "description": "Unavailable or invalid backend output", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9_]+$" } }, "required": [ "error" ], "additionalProperties": {} } } } } }, "description": "One page of at most 500 messages, returned oldest first. The first page holds the newest; when older messages exist, set truncated to true and return nextCursor to fetch the page before it. Takechat follows nextCursor until it holds 500 messages, so a store whose backend reads fewer at a time can still serve the newest 500. Adapters that return every message on one page omit nextCursor or return null.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 500 }, "description": "Most messages to return. A page may hold fewer, as long as nextCursor leads to the rest." }, { "name": "cursor", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 4096 }, "description": "The previous page's nextCursor, passed back unchanged; returns the messages just before that page. Opaque; a keyset position such as the oldest returned message's (createdAt, id), not an offset, so pages stay consistent while new messages arrive. Invalid cursors return 400." } ] }, "post": { "security": [ { "operatorKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "message": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 300 }, "role": { "type": "string", "const": "assistant" }, "text": { "type": "string", "description": "What the operator reads. Business (assistant) text is Markdown without images: links, emphasis, lists, tables and code. Customer text is plain; bare URLs become links." }, "createdAt": { "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+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "fallback": { "type": "boolean", "description": "text stands in for content that isn't text, such as a tool call or media. Write it for a person: what happened and its result, with anything to open (a generated image, a file) as a Markdown link to a lasting HTTPS URL, [Generated image](https://…). Never raw tool input or JSON, internal or credential-bearing URLs, or links that expire while the message is listed." }, "deliveryFailed": { "type": "boolean" }, "clientMessageId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "operator": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 300 }, "name": { "type": "string", "minLength": 1, "maxLength": 300 } }, "required": [ "id", "name" ], "additionalProperties": false }, "deliveryStatus": { "type": "string", "enum": [ "pending", "sent", "delivered", "failed", "unknown" ] } }, "required": [ "id", "role", "text", "createdAt", "fallback", "deliveryFailed", "clientMessageId", "operator", "deliveryStatus" ], "additionalProperties": false } }, "required": [ "message" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9_]+$" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "401": { "description": "Invalid key", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9_]+$" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9_]+$" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9_]+$" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "409": { "description": "State or idempotency conflict: code conversation_closed, channel_restricted or idempotency_conflict", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9_]+$" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "413": { "description": "Body too large", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9_]+$" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "429": { "description": "Rate limited: code rate_limited", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9_]+$" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "503": { "description": "Unavailable or invalid backend output", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9_]+$" } }, "required": [ "error" ], "additionalProperties": {} } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "clientMessageId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "text": { "type": "string", "minLength": 1, "maxLength": 8000 } }, "required": [ "clientMessageId", "text" ], "additionalProperties": false } } } }, "description": "Existing conversations only. clientMessageId is a UUID unique within workspace/conversation; same body replays the canonical message, changed body returns 409. Length uses UTF-16 code units. Recheck authentication and atomically enforce channel/state constraints." } } } }