{ "openapi": "3.1.0", "tags": [ { "name": "Discovery", "description": "Installation context, granted websites, capabilities, guides and write receipts." }, { "name": "Conversations", "description": "Stored conversations, transcripts, messages and dispositions." }, { "name": "Visitors", "description": "Stored visitors, their conversation history and visitor notes." }, { "name": "Contacts", "description": "Stored contacts, linked visitors and contact notes." }, { "name": "Files", "description": "Message attachment metadata and bounded content reads." }, { "name": "Directory and catalogues", "description": "Operators, channels, teams, dispositions, saved responses, saved links and offers." }, { "name": "Reporting", "description": "Aggregated reports over stored conversations." }, { "name": "AI features", "description": "Configured AI feature metadata and typed execution." }, { "name": "Configuration", "description": "AI feature configuration metadata and dry-run previews." }, { "name": "Event subscriptions", "description": "Payload-free change receipts pulled from a subscription." }, { "name": "Realtime", "description": "WebSocket sessions that stream the same change receipts." } ], "info": { "title": "INSIDE Gateway installation REST API", "version": "1.0.0", "description": "Implemented app-installation reads, reviewed conversation/visitor writes and bounded typed AI execution. Human Dashboard/admin APIs are separate. Credentials require expiry, explicit websites and live policy checks. Conversation and visitor writes require a mapped native author for the exact granted website; author permissions and presence do not grant app authority. Typed AI execution uses supplied context without an operator mapping." }, "servers": [ { "url": "https://api.inside.chat", "description": "Hosted Gateway" }, { "url": "http://localhost:8787", "description": "Local development" } ], "components": { "securitySchemes": { "installation_token": { "type": "http", "scheme": "bearer", "bearerFormat": "igw_live_ or igw_test_ opaque installation token", "description": "Use the secret disclosed once when issuing an expiring credential. Never put it in a URL." }, "oauth_client_credentials": { "type": "oauth2", "description": "Confidential installations exchange their credential ID and once-disclosed secret for a short-lived bearer. Parent and token authority are rechecked on every use.", "flows": { "clientCredentials": { "tokenUrl": "https://api.inside.chat/oauth/token", "scopes": { "website_read": "website read", "health_read": "health read", "conversation_read": "conversation read", "contact_read": "contact read", "contact_read_pii": "contact read pii", "visitor_notes_read": "visitor notes read", "config_read": "config read", "config_plan": "config plan", "ai_features_read": "ai features read", "ai_execute": "ai execute", "reports_read": "reports read", "file_read": "file read", "message_content_read": "message content read", "visitor_notes_write": "visitor notes write", "conversation_update": "conversation update", "directory_read": "directory read", "live_read": "live read", "event_read": "event read", "internal_notes_read": "internal notes read" } } } } } }, "paths": { "/api/v1/operations/{operation_id}": { "get": { "operationId": "operation_get", "summary": "Get a write receipt", "description": "Read retained original app command status by operation_id and website_id. Requires original credential/revision and current operation grants. No native action or result content; acknowledged does not prove success/delivery.", "parameters": [ { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^op_[a-f0-9]{64}$" } }, { "name": "website_id", "in": "query", "required": true, "description": "Required original explicitly granted website. Receipt IDs do not confer ownership.", "schema": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" } } ], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [] } ], "x-required-scopes": [], "x-required-data-access": [], "x-restrictions-supported": true, "x-restriction-dimensions": [ "channel_ids", "team_ids", "subsite_ids" ], "x-mutation": false, "x-idempotency-required": false, "x-author-mapping-required": false, "x-current-original-operation-permissions": true, "responses": { "200": { "description": "Authorized result. Projection depends on current scopes and data policy.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "operation_id", "website_id", "operation", "status", "coverage" ], "properties": { "operation_id": { "type": "string", "pattern": "^op_[a-f0-9]{64}$" }, "website_id": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" }, "operation": { "type": "string", "enum": [ "visitor_note_add", "conversation_disposition_set", "ai_feature_execute", "config_plan" ] }, "status": { "type": "string", "enum": [ "pending", "acknowledged", "outcome_unknown" ] }, "coverage": { "const": "gateway_command_receipt" } } } } } } } }, "400": { "description": "Invalid, duplicate or unsupported request parameters." }, "401": { "description": "Missing, expired or revoked installation credential." }, "404": { "description": "Resource not found or not permitted by current authority." }, "422": { "description": "The requested capability is not available for application installations." }, "429": { "description": "Per-app quota exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Enrollment, native service or required authority is unavailable." } }, "tags": [ "Discovery" ] } }, "/api/v1/websites": { "get": { "operationId": "websites", "summary": "List granted websites", "description": "List explicitly granted website IDs; new websites are never granted automatically.", "parameters": [], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "website_read" ] } ], "x-required-scopes": [ "website_read" ], "x-required-data-access": [], "x-restrictions-supported": true, "x-restriction-dimensions": [ "channel_ids", "team_ids", "subsite_ids" ], "x-mutation": false, "x-idempotency-required": false, "x-author-mapping-required": false, "responses": { "200": { "description": "Authorized result. Projection depends on current scopes and data policy.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "websites" ], "properties": { "websites": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "website_id" ], "properties": { "website_id": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" } } } } } } } } }, "400": { "description": "Invalid, duplicate or unsupported request parameters." }, "401": { "description": "Missing, expired or revoked installation credential." }, "404": { "description": "Resource not found or not permitted by current authority." }, "422": { "description": "The requested capability is not available for application installations." }, "429": { "description": "Per-app quota exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Enrollment, native service or required authority is unavailable." } }, "tags": [ "Discovery" ] } }, "/api/v1/capabilities": { "get": { "operationId": "capabilities", "summary": "List capabilities for a website", "description": "List currently granted read and reviewed write operations for one explicitly granted website. Native target and integration checks still apply.", "parameters": [ { "name": "website_id", "in": "query", "required": true, "description": "An explicitly granted website.", "schema": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" } } ], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [] } ], "x-required-scopes": [], "x-required-data-access": [], "x-restrictions-supported": true, "x-restriction-dimensions": [ "channel_ids", "team_ids", "subsite_ids" ], "x-mutation": false, "x-idempotency-required": false, "x-author-mapping-required": false, "responses": { "200": { "description": "Authorized result. Projection depends on current scopes and data policy.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "website_id", "native_commands_paused", "operations" ], "properties": { "website_id": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" }, "native_commands_paused": { "type": "boolean", "description": "true while INSIDE pauses native commands for this website. Only operation_get remains listed." }, "operations": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "name", "method", "path", "fields", "required_scopes", "data_access", "discovery", "description", "restriction_dimensions", "mutation", "idempotency_required", "author_mapping_required" ], "properties": { "name": { "type": "string", "description": "Operation and MCP tool name." }, "method": { "type": "string" }, "path": { "type": "string", "description": "Path template with :parameter placeholders." }, "fields": { "type": "array", "items": { "type": "string" } }, "required_scopes": { "type": "array", "items": { "type": "string" } }, "data_access": { "type": "array", "items": { "type": "string", "enum": [ "message_content", "pii", "internal_notes" ] } }, "discovery": { "type": "boolean" }, "description": { "type": "string" }, "restriction_dimensions": { "type": "array", "items": { "type": "string", "enum": [ "channel_ids", "team_ids", "subsite_ids" ] } }, "mutation": { "type": "boolean" }, "idempotency_required": { "type": "boolean" }, "author_mapping_required": { "type": "boolean" } } } } } } } } }, "400": { "description": "Invalid, duplicate or unsupported request parameters." }, "401": { "description": "Missing, expired or revoked installation credential." }, "404": { "description": "Resource not found or not permitted by current authority." }, "422": { "description": "The requested capability is not available for application installations." }, "429": { "description": "Per-app quota exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Enrollment, native service or required authority is unavailable." } }, "tags": [ "Discovery" ] } }, "/api/v1/health": { "get": { "operationId": "health", "summary": "Check website readiness", "description": "Check enrollment readiness for one explicitly granted website. This does not contact the native cluster or prove live health.", "parameters": [ { "name": "website_id", "in": "query", "required": true, "description": "An explicitly granted website.", "schema": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" } } ], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "health_read" ] } ], "x-required-scopes": [ "health_read" ], "x-required-data-access": [], "x-restrictions-supported": true, "x-restriction-dimensions": [ "channel_ids", "team_ids", "subsite_ids" ], "x-mutation": false, "x-idempotency-required": false, "x-author-mapping-required": false, "responses": { "200": { "description": "Authorized result. Projection depends on current scopes and data policy.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "website_id", "enrollment_ready", "live_health" ], "properties": { "website_id": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" }, "enrollment_ready": { "type": "boolean", "description": "The website is enrolled with the Gateway." }, "live_health": { "const": "not_checked", "description": "This check never contacts the website cluster." } } } } } }, "400": { "description": "Invalid, duplicate or unsupported request parameters." }, "401": { "description": "Missing, expired or revoked installation credential." }, "404": { "description": "Resource not found or not permitted by current authority." }, "422": { "description": "The requested capability is not available for application installations." }, "429": { "description": "Per-app quota exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Enrollment, native service or required authority is unavailable." } }, "tags": [ "Discovery" ] } }, "/api/v1/conversations": { "get": { "operationId": "conversations_list", "summary": "List conversations", "description": "Page stored conversations, including non-AI chats. Visitor/status/cursor and channel/team/subsite restrictions intersect before paging. query searches a literal subject prefix and needs content/PII scopes and flags. contact_id uses stored links and additionally needs contact_read/contact_read_pii, PII and unrestricted policy. Excludes unsaved live state; subjects need content/PII.", "parameters": [ { "name": "website_id", "in": "query", "required": true, "description": "An explicitly granted website.", "schema": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" } }, { "name": "visitor_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^vis_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$", "maxLength": 100 } }, { "name": "contact_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^ctc_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$", "maxLength": 100, "description": "Filter by stored website-owned contact/visitor links. Requires contact_read, contact_read_pii, PII data access and unrestricted installation policy. Intersects visitor/status/cursor; missing or erased contact associations yield an empty page." } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "unassigned", "open", "pending", "closed", "resolved", "onhold" ] } }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Literal trimmed prefix over stored conversation subject using native database collation. Requires message_content_read and contact_read_pii scopes plus both data flags. Intersects all current filters before paging; no transcript-body or remote search." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^con_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$", "maxLength": 100, "description": "Continue at the last delivered owned resource ID. Existing canonical base64 positive signed-64-bit numeric history cursors are also accepted for transcript and visitor history." } } ], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "conversation_read" ] } ], "x-required-scopes": [ "conversation_read" ], "x-required-data-access": [], "x-restrictions-supported": true, "x-restriction-dimensions": [ "channel_ids", "team_ids", "subsite_ids" ], "x-mutation": false, "x-idempotency-required": false, "x-author-mapping-required": false, "x-conditional-permissions": [ { "parameter": "contact_id", "required_scopes": [ "contact_read", "contact_read_pii" ], "required_data_access": [ "pii" ], "unrestricted_policy": true }, { "parameter": "query", "required_scopes": [ "message_content_read", "contact_read_pii" ], "required_data_access": [ "message_content", "pii" ] } ], "responses": { "200": { "description": "Authorized result. Projection depends on current scopes and data policy.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "data", "next_cursor", "coverage" ], "properties": { "data": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "id", "visitor_id", "operator_id", "status", "platform", "started_at", "active", "subject" ], "properties": { "id": { "type": "string", "maxLength": 100, "pattern": "^con_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, "visitor_id": { "type": "string", "maxLength": 100, "pattern": "^vis_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, "operator_id": { "anyOf": [ { "type": "string", "maxLength": 100, "pattern": "^opr_[0-9]{1,20}_[1-9][0-9]{0,9}$" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "unassigned", "open", "pending", "closed", "resolved", "onhold", "unknown" ] }, "platform": { "type": "string", "enum": [ "chat", "email", "voice", "sms", "messenger", "salesforce", "zendesk", "facebook", "line", "whatsapp", "twitter", "wechat", "apple_messages", "qr_code", "google_business_messages", "instagram", "kakao_talk", "viber", "unknown" ] }, "started_at": { "type": "string", "format": "date-time", "maxLength": 40 }, "active": { "type": "boolean" }, "subject": { "anyOf": [ { "type": "string", "maxLength": 4000 }, { "type": "null" } ] } } } }, "next_cursor": { "anyOf": [ { "type": "string", "maxLength": 100, "pattern": "^con_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, { "type": "null" } ] }, "coverage": { "const": "persisted_conversations" } } } } } } } }, "400": { "description": "Invalid, duplicate or unsupported request parameters." }, "401": { "description": "Missing, expired or revoked installation credential." }, "404": { "description": "Resource not found or not permitted by current authority." }, "422": { "description": "The requested capability is not available for application installations." }, "429": { "description": "Per-app quota exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Enrollment, native service or required authority is unavailable." } }, "tags": [ "Conversations" ] } }, "/api/v1/contacts": { "get": { "operationId": "contacts_list", "summary": "List contacts", "description": "Page stored contact IDs and blocked state, descending. Personal fields and search need contact_read_pii and PII; query_field selects all/name/email/mobile/phone, query_match prefix/exact. Unrestricted policy required; excludes deleted contacts, custom fields, links and remote CRM.", "parameters": [ { "name": "website_id", "in": "query", "required": true, "description": "An explicitly granted website.", "schema": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" } }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Requires both contact_read_pii and PII data access. Prefix search over stored native primary name, email, mobile and phone. Wildcards are literal; custom fields and remote CRM data are excluded." } }, { "name": "query_field", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "name", "email", "mobile", "phone" ], "default": "all", "description": "Requires query and current PII access. Exact matching uses native database collation with no address normalization or automatic contact selection." } }, { "name": "query_match", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "prefix", "exact" ], "default": "prefix", "description": "Requires query and current PII access. Exact matching uses native database collation with no address normalization or automatic contact selection." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^ctc_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$", "maxLength": 100 } } ], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "contact_read" ] } ], "x-required-scopes": [ "contact_read" ], "x-required-data-access": [], "x-restrictions-supported": false, "x-restriction-dimensions": [], "x-mutation": false, "x-idempotency-required": false, "x-author-mapping-required": false, "x-conditional-permissions": [ { "parameter": "query", "required_scopes": [ "contact_read_pii" ], "required_data_access": [ "pii" ] } ], "responses": { "200": { "description": "Authorized result. Projection depends on current scopes and data policy.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "data", "next_cursor", "coverage" ], "properties": { "data": { "type": "array", "maxItems": 100, "items": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "id", "blocked", "access" ], "properties": { "id": { "type": "string", "maxLength": 100, "pattern": "^ctc_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, "blocked": { "type": "boolean" }, "access": { "type": "object", "additionalProperties": false, "required": [ "pii" ], "properties": { "pii": { "const": false } } } } }, { "type": "object", "additionalProperties": false, "required": [ "id", "blocked", "name", "email", "mobile", "phone", "access" ], "properties": { "id": { "type": "string", "maxLength": 100, "pattern": "^ctc_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, "blocked": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string", "maxLength": 320 }, { "type": "null" } ] }, "mobile": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "access": { "type": "object", "additionalProperties": false, "required": [ "pii" ], "properties": { "pii": { "const": true } } } } } ] } }, "next_cursor": { "anyOf": [ { "type": "string", "maxLength": 100, "pattern": "^ctc_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, { "type": "null" } ] }, "coverage": { "const": "stored_primary_contacts" } } } } } } } }, "400": { "description": "Invalid, duplicate or unsupported request parameters." }, "401": { "description": "Missing, expired or revoked installation credential." }, "404": { "description": "Resource not found or not permitted by current authority." }, "422": { "description": "The requested capability is not available for application installations." }, "429": { "description": "Per-app quota exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Enrollment, native service or required authority is unavailable." } }, "tags": [ "Contacts" ] } }, "/api/v1/contacts/{contact_id}": { "get": { "operationId": "contact_get", "summary": "Get a contact", "description": "Read an owned contact ID and blocked state. Personal fields need contact_read_pii and PII access. Unrestricted policy required; excludes reachability and remote CRM.", "parameters": [ { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ctc_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" } }, { "name": "website_id", "in": "query", "required": false, "description": "Optional; if present must match the resource owner.", "schema": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" } } ], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "contact_read" ] } ], "x-required-scopes": [ "contact_read" ], "x-required-data-access": [], "x-restrictions-supported": false, "x-restriction-dimensions": [], "x-mutation": false, "x-idempotency-required": false, "x-author-mapping-required": false, "responses": { "200": { "description": "Authorized result. Projection depends on current scopes and data policy.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "contact" ], "properties": { "contact": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "id", "blocked", "access" ], "properties": { "id": { "type": "string", "maxLength": 100, "pattern": "^ctc_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, "blocked": { "type": "boolean" }, "access": { "type": "object", "additionalProperties": false, "required": [ "pii" ], "properties": { "pii": { "const": false } } } } }, { "type": "object", "additionalProperties": false, "required": [ "id", "blocked", "name", "email", "mobile", "phone", "access" ], "properties": { "id": { "type": "string", "maxLength": 100, "pattern": "^ctc_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, "blocked": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string", "maxLength": 320 }, { "type": "null" } ] }, "mobile": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "access": { "type": "object", "additionalProperties": false, "required": [ "pii" ], "properties": { "pii": { "const": true } } } } } ] } } } } } } } }, "400": { "description": "Invalid, duplicate or unsupported request parameters." }, "401": { "description": "Missing, expired or revoked installation credential." }, "404": { "description": "Resource not found or not permitted by current authority." }, "422": { "description": "The requested capability is not available for application installations." }, "429": { "description": "Per-app quota exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Enrollment, native service or required authority is unavailable." } }, "tags": [ "Contacts" ] } }, "/api/v1/contacts/{contact_id}/visitors": { "get": { "operationId": "contact_visitors", "summary": "List visitors linked to a contact", "description": "Page stored website-owned visitor IDs linked to a contact, descending. Requires unrestricted policy. Excludes deleted contacts/visitors, live state, profiles and remote CRM associations.", "parameters": [ { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ctc_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" } }, { "name": "website_id", "in": "query", "required": false, "description": "Optional; if present must match the resource owner.", "schema": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^vis_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$", "maxLength": 100 } } ], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "contact_read", "contact_read_pii", "conversation_read" ] } ], "x-required-scopes": [ "contact_read", "contact_read_pii", "conversation_read" ], "x-required-data-access": [ "pii" ], "x-restrictions-supported": false, "x-restriction-dimensions": [], "x-mutation": false, "x-idempotency-required": false, "x-author-mapping-required": false, "responses": { "200": { "description": "Authorized result. Projection depends on current scopes and data policy.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "data", "next_cursor", "coverage", "contact_id" ], "properties": { "data": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "maxLength": 100, "pattern": "^vis_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" } } } }, "next_cursor": { "anyOf": [ { "type": "string", "maxLength": 100, "pattern": "^vis_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, { "type": "null" } ] }, "coverage": { "const": "stored_contact_visitor_links" }, "contact_id": { "type": "string", "maxLength": 100, "pattern": "^ctc_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" } } } } } } } }, "400": { "description": "Invalid, duplicate or unsupported request parameters." }, "401": { "description": "Missing, expired or revoked installation credential." }, "404": { "description": "Resource not found or not permitted by current authority." }, "422": { "description": "The requested capability is not available for application installations." }, "429": { "description": "Per-app quota exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Enrollment, native service or required authority is unavailable." } }, "tags": [ "Contacts" ] } }, "/api/v1/contacts/{contact_id}/notes": { "get": { "operationId": "contact_notes", "summary": "List contact notes", "description": "Page active stored notes across visitors linked to one owned contact, descending. Requires unrestricted policy and notes/content/PII access. Excludes deleted contacts/visitors/notes, attachments and reminders. No remote CRM call.", "parameters": [ { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ctc_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" } }, { "name": "website_id", "in": "query", "required": false, "description": "Optional; if present must match the resource owner.", "schema": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,9}$", "maxLength": 10, "description": "Continue before the last delivered positive native note ID; maximum2147483647. Current contact associations and website policy remain authoritative." } } ], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "contact_read", "contact_read_pii", "conversation_read", "visitor_notes_read" ] } ], "x-required-scopes": [ "contact_read", "contact_read_pii", "conversation_read", "visitor_notes_read" ], "x-required-data-access": [ "message_content", "pii", "internal_notes" ], "x-restrictions-supported": false, "x-restriction-dimensions": [], "x-mutation": false, "x-idempotency-required": false, "x-author-mapping-required": false, "responses": { "200": { "description": "Authorized result. Projection depends on current scopes and data policy.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "contact_id", "notes", "next_cursor", "coverage" ], "properties": { "contact_id": { "type": "string", "maxLength": 100, "pattern": "^ctc_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, "notes": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "id", "note_id", "text", "title", "author", "created_at", "text_truncated" ], "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,9}$", "maxLength": 10 }, "note_id": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "text": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string", "maxLength": 240 }, { "type": "null" } ] }, "author": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time", "maxLength": 40 }, { "type": "null" } ] }, "text_truncated": { "type": "boolean" } } } }, "next_cursor": { "anyOf": [ { "type": "string", "pattern": "^[1-9][0-9]{0,9}$", "maxLength": 10 }, { "type": "null" } ] }, "coverage": { "const": "persisted_contact_visitor_notes" } } } } } } } }, "400": { "description": "Invalid, duplicate or unsupported request parameters." }, "401": { "description": "Missing, expired or revoked installation credential." }, "404": { "description": "Resource not found or not permitted by current authority." }, "422": { "description": "The requested capability is not available for application installations." }, "429": { "description": "Per-app quota exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Enrollment, native service or required authority is unavailable." } }, "tags": [ "Contacts" ] } }, "/api/v1/settings/catalog": { "get": { "operationId": "config_catalog", "summary": "List configuration areas", "description": "Read the implemented native configuration areas for an explicitly granted unrestricted website. Only closed AI feature metadata and separately scoped name/enabled dry-run previews are supported. Native apply is unavailable.", "parameters": [ { "name": "website_id", "in": "query", "required": true, "description": "An explicitly granted website.", "schema": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" } } ], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "config_read" ] } ], "x-required-scopes": [ "config_read" ], "x-required-data-access": [], "x-restrictions-supported": false, "x-restriction-dimensions": [], "x-mutation": false, "x-idempotency-required": false, "x-author-mapping-required": false, "responses": { "200": { "description": "Authorized result. Projection depends on current scopes and data policy.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "areas", "plan_available", "apply_available" ], "properties": { "areas": { "type": "array", "items": { "type": "object", "required": [ "path", "type", "read_only" ], "properties": { "path": { "const": "/ai/features" }, "type": { "const": "collection" }, "read_only": { "const": true } } } }, "plan_available": { "type": "boolean", "description": "true when the credential also has config_plan." }, "apply_available": { "const": false } } } }, "description": "Implemented configuration areas. Only /ai/features is available." } } } }, "400": { "description": "Invalid, duplicate or unsupported request parameters." }, "401": { "description": "Missing, expired or revoked installation credential." }, "404": { "description": "Resource not found or not permitted by current authority." }, "422": { "description": "The requested capability is not available for application installations." }, "429": { "description": "Per-app quota exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Enrollment, native service or required authority is unavailable." } }, "tags": [ "Configuration" ] } }, "/api/v1/settings/schema": { "get": { "operationId": "config_schema", "summary": "Get the configuration schema", "description": "Read the closed metadata schema for /ai/features and separately scoped dry-run preview fields. Current configuration remains read-only; this grants no approval or native apply authority.", "parameters": [ { "name": "website_id", "in": "query", "required": true, "description": "An explicitly granted website.", "schema": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" } }, { "name": "path", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "/ai/features" ] } } ], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "config_read" ] } ], "x-required-scopes": [ "config_read" ], "x-required-data-access": [], "x-restrictions-supported": false, "x-restriction-dimensions": [], "x-mutation": false, "x-idempotency-required": false, "x-author-mapping-required": false, "responses": { "200": { "description": "Authorized result. Projection depends on current scopes and data policy.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "path", "type", "read_only", "plan_available", "preview_fields", "apply_available", "item_schema" ], "properties": { "path": { "const": "/ai/features" }, "type": { "const": "collection" }, "read_only": { "const": true }, "plan_available": { "type": "boolean" }, "preview_fields": { "type": "array", "items": { "type": "string", "enum": [ "name", "enabled" ] } }, "apply_available": { "const": false }, "item_schema": { "type": "object", "description": "JSON Schema for one AI feature item." } } } }, "description": "Metadata schema for the AI feature configuration area." } } } }, "400": { "description": "Invalid, duplicate or unsupported request parameters." }, "401": { "description": "Missing, expired or revoked installation credential." }, "404": { "description": "Resource not found or not permitted by current authority." }, "422": { "description": "The requested capability is not available for application installations." }, "429": { "description": "Per-app quota exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Enrollment, native service or required authority is unavailable." } }, "tags": [ "Configuration" ] } }, "/api/v1/settings/item": { "get": { "operationId": "config_get", "summary": "Read configuration", "description": "Read bounded current active-version metadata at /ai/features or an owned stable feature path. Unrestricted installation policy required. Credentials, instructions, settings, models, functions and history are excluded.", "parameters": [ { "name": "website_id", "in": "query", "required": true, "description": "An explicitly granted website.", "schema": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" } }, { "name": "path", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 200, "pattern": "^/ai/features(?:/aif_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18})?$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^aif_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" } } ], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "config_read" ] } ], "x-required-scopes": [ "config_read" ], "x-required-data-access": [], "x-restrictions-supported": false, "x-restriction-dimensions": [], "x-mutation": false, "x-idempotency-required": false, "x-author-mapping-required": false, "responses": { "200": { "description": "Authorized result. Projection depends on current scopes and data policy.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "oneOf": [ { "type": "object", "required": [ "path", "items", "truncated", "next_cursor" ], "properties": { "path": { "const": "/ai/features" }, "items": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "type", "enabled", "version" ], "properties": { "id": { "type": "string", "pattern": "^aif_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, "name": { "type": "string", "maxLength": 200 }, "type": { "type": "string", "enum": [ "autopilot", "ask_ai", "copilot", "translation", "language_detection", "spam_checker", "spelling_grammar_check", "rephrase", "chat_summary", "metrics", "scoring", "product_recommendation", "email_autopilot", "voice_autopilot", "citation_summary", "unsupported" ] }, "enabled": { "type": "boolean" }, "version": { "type": "integer", "minimum": 1, "description": "Latest active version. Send it as expected_version." } } }, "maxItems": 100 }, "truncated": { "type": "boolean", "description": "More rows exist after next_cursor." }, "next_cursor": { "anyOf": [ { "type": "string", "pattern": "^aif_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, { "type": "null" } ] } } }, { "type": "object", "required": [ "path", "item" ], "properties": { "path": { "type": "string", "description": "/ai/features/{feature_id}" }, "item": { "type": "object", "required": [ "id", "name", "type", "enabled", "version" ], "properties": { "id": { "type": "string", "pattern": "^aif_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, "name": { "type": "string", "maxLength": 200 }, "type": { "type": "string", "enum": [ "autopilot", "ask_ai", "copilot", "translation", "language_detection", "spam_checker", "spelling_grammar_check", "rephrase", "chat_summary", "metrics", "scoring", "product_recommendation", "email_autopilot", "voice_autopilot", "citation_summary", "unsupported" ] }, "enabled": { "type": "boolean" }, "version": { "type": "integer", "minimum": 1, "description": "Latest active version. Send it as expected_version." } } } } } ] } }, "description": "A page of AI feature metadata for path=/ai/features, or one item for path=/ai/features/{feature_id}." } } } }, "400": { "description": "Invalid, duplicate or unsupported request parameters." }, "401": { "description": "Missing, expired or revoked installation credential." }, "404": { "description": "Resource not found or not permitted by current authority." }, "422": { "description": "The requested capability is not available for application installations." }, "429": { "description": "Per-app quota exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Enrollment, native service or required authority is unavailable." } }, "tags": [ "Configuration" ] } }, "/api/v1/settings/search": { "get": { "operationId": "config_search", "summary": "Search configuration", "description": "Search current AI feature names and public type labels on an explicitly granted unrestricted website. Returns bounded logical paths and metadata only; never searches or discloses private configuration.", "parameters": [ { "name": "website_id", "in": "query", "required": true, "description": "An explicitly granted website.", "schema": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" } }, { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^aif_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" } } ], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "config_read" ] } ], "x-required-scopes": [ "config_read" ], "x-required-data-access": [], "x-restrictions-supported": false, "x-restriction-dimensions": [], "x-mutation": false, "x-idempotency-required": false, "x-author-mapping-required": false, "responses": { "200": { "description": "Authorized result. Projection depends on current scopes and data policy.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "matches", "truncated", "next_cursor" ], "properties": { "matches": { "type": "array", "items": { "type": "object", "required": [ "path", "label", "type", "version" ], "properties": { "path": { "type": "string", "description": "/ai/features/{feature_id}" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "autopilot", "ask_ai", "copilot", "translation", "language_detection", "spam_checker", "spelling_grammar_check", "rephrase", "chat_summary", "metrics", "scoring", "product_recommendation", "email_autopilot", "voice_autopilot", "citation_summary", "unsupported" ] }, "version": { "type": "integer", "minimum": 1 } } }, "maxItems": 100 }, "truncated": { "type": "boolean", "description": "More rows exist after next_cursor." }, "next_cursor": { "anyOf": [ { "type": "string", "pattern": "^aif_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, { "type": "null" } ] } } } }, "description": "AI features whose name or type label contains the query, case-insensitively." } } } }, "400": { "description": "Invalid, duplicate or unsupported request parameters." }, "401": { "description": "Missing, expired or revoked installation credential." }, "404": { "description": "Resource not found or not permitted by current authority." }, "422": { "description": "The requested capability is not available for application installations." }, "429": { "description": "Per-app quota exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Enrollment, native service or required authority is unavailable." } }, "tags": [ "Configuration" ] } }, "/api/v1/settings/plans": { "post": { "operationId": "config_plan", "summary": "Preview a configuration change", "description": "Preview an exact name/enabled diff for an owned AI feature at the expected latest active version. Requires an unrestricted installation policy. This dry run changes no native configuration, creates no approval or apply authority, and preserves all hidden settings. Native apply remains unavailable. Results are retained for 24 hours. A permanent content-free tombstone prevents the same key from creating a new effect after result expiry. Reuse the same key and identical input when retrying. Changed input or policy/revisions conflict. Current policy is checked before result reuse. An unknown outcome returns 409 outcome_unknown; never retry with a new key automatically.", "parameters": [ { "name": "website_id", "in": "query", "required": true, "description": "An explicitly granted website.", "schema": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "A stable key for this intended effect. Reuse the same key and input for retries; never automatically replace it after an unknown outcome.", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]+$" } } ], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "config_read", "config_plan" ] } ], "x-required-scopes": [ "config_read", "config_plan" ], "x-required-data-access": [], "x-restrictions-supported": false, "x-restriction-dimensions": [], "x-mutation": true, "x-idempotency-required": true, "x-author-mapping-required": false, "x-preview-only": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "path", "expected_version", "changes" ], "properties": { "path": { "type": "string", "maxLength": 200, "pattern": "^/ai/features/aif_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, "expected_version": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "changes": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^(?=.*\\S)[^<>\\x00-\\x1f\\x7f-\\x9f]+$" }, "enabled": { "type": "boolean" } } } } } } } }, "responses": { "200": { "description": "Authorized result. Projection depends on current scopes and data policy.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "preview" ], "properties": { "preview": { "type": "object", "required": [ "website_id", "path", "feature_id", "expected_version", "changes", "has_changes", "approval_required", "apply_available", "status" ], "properties": { "website_id": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" }, "path": { "type": "string" }, "feature_id": { "type": "string", "pattern": "^aif_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, "expected_version": { "type": "integer", "minimum": 1 }, "changes": { "type": "array", "items": { "type": "object", "required": [ "field", "before", "after" ], "properties": { "field": { "type": "string", "enum": [ "name", "enabled" ] }, "before": { "anyOf": [ { "type": "string" }, { "type": "boolean" } ] }, "after": { "anyOf": [ { "type": "string" }, { "type": "boolean" } ] } } }, "description": "Actual changes only, in name then enabled order. Empty for a no-op." }, "has_changes": { "type": "boolean" }, "approval_required": { "const": true }, "apply_available": { "const": false }, "status": { "const": "preview_only" } } } } } }, "description": "A dry-run diff. Nothing is saved, and the preview grants no approval or apply authority." } } }, "headers": { "X-Gateway-Operation-Id": { "description": "Retained command receipt identifier when command reservation was acknowledged; use operation_get with the original credential and website. Not proof of native success or delivery.", "schema": { "type": "string", "pattern": "^op_[a-f0-9]{64}$" } } } }, "400": { "description": "Invalid, duplicate or unsupported request parameters." }, "401": { "description": "Missing, expired or revoked installation credential." }, "404": { "description": "Resource not found or not permitted by current authority." }, "409": { "description": "idempotency_conflict: the key has different input or authority revisions; operation_in_progress: the same command is pending; operation_conflict: native business state rejects the change; outcome_unknown: the native result is uncertain or no longer retained. Keep the same key and input for retries; never automatically create a new key or resubmit the effect.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "title", "status", "code", "request_id" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 409 }, "code": { "type": "string", "enum": [ "idempotency_conflict", "operation_in_progress", "operation_conflict", "outcome_unknown" ] }, "request_id": { "type": "string" } } } } }, "headers": { "X-Gateway-Operation-Id": { "description": "Retained command receipt identifier when command reservation was acknowledged; use operation_get with the original credential and website. Not proof of native success or delivery.", "schema": { "type": "string", "pattern": "^op_[a-f0-9]{64}$" } } } }, "422": { "description": "The requested capability is not available for application installations." }, "429": { "description": "Per-app quota exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Enrollment, native service or required authority is unavailable." } }, "tags": [ "Configuration" ] } }, "/api/v1/ai/features": { "get": { "operationId": "ai_features_list", "summary": "List AI features", "description": "List bounded active-version AI feature metadata for an explicitly granted website. Requires an unrestricted installation policy. Provider credentials, instructions and raw configuration are excluded. Listed features do not grant application execution.", "parameters": [ { "name": "website_id", "in": "query", "required": true, "description": "An explicitly granted website.", "schema": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^aif_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "autopilot", "ask_ai", "copilot", "translation", "language_detection", "spam_checker", "spelling_grammar_check", "rephrase", "chat_summary", "metrics", "scoring", "product_recommendation", "email_autopilot", "voice_autopilot", "citation_summary", "unsupported" ] } } ], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "ai_features_read" ] } ], "x-required-scopes": [ "ai_features_read" ], "x-required-data-access": [], "x-restrictions-supported": false, "x-restriction-dimensions": [], "x-mutation": false, "x-idempotency-required": false, "x-author-mapping-required": false, "responses": { "200": { "description": "Authorized result. Projection depends on current scopes and data policy.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "features", "truncated", "next_cursor" ], "properties": { "features": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "type", "enabled", "version", "application_execution" ], "properties": { "id": { "type": "string", "pattern": "^aif_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, "name": { "type": "string", "maxLength": 200 }, "type": { "type": "string", "enum": [ "autopilot", "ask_ai", "copilot", "translation", "language_detection", "spam_checker", "spelling_grammar_check", "rephrase", "chat_summary", "metrics", "scoring", "product_recommendation", "email_autopilot", "voice_autopilot", "citation_summary", "unsupported" ] }, "enabled": { "type": "boolean" }, "version": { "type": "integer", "minimum": 1, "description": "Latest active version. Send it as expected_version." }, "application_execution": { "type": "object", "required": [ "available" ], "properties": { "available": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "adapter_not_available", "scope_denied" ] }, "context_types": { "type": "array", "items": { "type": "string", "enum": [ "text" ] } } } } } }, "maxItems": 100 }, "truncated": { "type": "boolean", "description": "More rows exist after next_cursor." }, "next_cursor": { "anyOf": [ { "type": "string", "pattern": "^aif_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, { "type": "null" } ] } } } }, "description": "Latest active AI feature metadata, sorted by feature ID." } } } }, "400": { "description": "Invalid, duplicate or unsupported request parameters." }, "401": { "description": "Missing, expired or revoked installation credential." }, "404": { "description": "Resource not found or not permitted by current authority." }, "422": { "description": "The requested capability is not available for application installations." }, "429": { "description": "Per-app quota exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Enrollment, native service or required authority is unavailable." } }, "tags": [ "AI features" ] } }, "/api/v1/ai/features/{feature_id}": { "get": { "operationId": "ai_feature_get", "summary": "Get an AI feature", "description": "Read closed active-version AI feature metadata by its stable website-owned feature ID. Requires an unrestricted installation policy. Application execution availability is reported separately; this read invokes no provider or configured function.", "parameters": [ { "name": "feature_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^aif_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" } }, { "name": "website_id", "in": "query", "required": false, "description": "Optional; if present must match the resource owner.", "schema": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" } } ], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "ai_features_read" ] } ], "x-required-scopes": [ "ai_features_read" ], "x-required-data-access": [], "x-restrictions-supported": false, "x-restriction-dimensions": [], "x-mutation": false, "x-idempotency-required": false, "x-author-mapping-required": false, "responses": { "200": { "description": "Authorized result. Projection depends on current scopes and data policy.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "feature" ], "properties": { "feature": { "type": "object", "required": [ "id", "name", "type", "enabled", "version", "application_execution" ], "properties": { "id": { "type": "string", "pattern": "^aif_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, "name": { "type": "string", "maxLength": 200 }, "type": { "type": "string", "enum": [ "autopilot", "ask_ai", "copilot", "translation", "language_detection", "spam_checker", "spelling_grammar_check", "rephrase", "chat_summary", "metrics", "scoring", "product_recommendation", "email_autopilot", "voice_autopilot", "citation_summary", "unsupported" ] }, "enabled": { "type": "boolean" }, "version": { "type": "integer", "minimum": 1, "description": "Latest active version. Send it as expected_version." }, "application_execution": { "type": "object", "required": [ "available" ], "properties": { "available": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "adapter_not_available", "scope_denied" ] }, "context_types": { "type": "array", "items": { "type": "string", "enum": [ "text" ] } } } } } } } } }, "description": "Latest active metadata for one AI feature." } } } }, "400": { "description": "Invalid, duplicate or unsupported request parameters." }, "401": { "description": "Missing, expired or revoked installation credential." }, "404": { "description": "Resource not found or not permitted by current authority." }, "422": { "description": "The requested capability is not available for application installations." }, "429": { "description": "Per-app quota exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Enrollment, native service or required authority is unavailable." } }, "tags": [ "AI features" ] } }, "/api/v1/ai/features/{feature_id}/execute": { "post": { "operationId": "ai_feature_execute", "summary": "Run an AI feature", "description": "Execute a version-bound AI feature using only a supplied typed text context and an unrestricted installation policy. Currently supports configured Lingua.NET language detection only. No live conversation, operator, AI session, provider or configured function is invoked. Read native feature metadata for current adapter availability. Results are retained for 24 hours. A permanent content-free tombstone prevents the same key from creating a new effect after result expiry. Reuse the same key and identical input when retrying. Changed input or policy/revisions conflict. Current policy is checked before result reuse. An unknown outcome returns 409 outcome_unknown; never retry with a new key automatically.", "parameters": [ { "name": "feature_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^aif_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" } }, { "name": "website_id", "in": "query", "required": false, "description": "Optional; if present must match the resource owner.", "schema": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "A stable key for this intended effect. Reuse the same key and input for retries; never automatically replace it after an unknown outcome.", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]+$" } } ], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "ai_features_read", "ai_execute" ] } ], "x-required-scopes": [ "ai_features_read", "ai_execute" ], "x-required-data-access": [], "x-restrictions-supported": false, "x-restriction-dimensions": [], "x-mutation": true, "x-idempotency-required": true, "x-author-mapping-required": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "expected_version", "context" ], "properties": { "expected_version": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "context": { "type": "object", "additionalProperties": false, "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string", "minLength": 1, "maxLength": 4000 }, "default_language": { "type": "string", "pattern": "^[a-z]{2}$", "minLength": 2, "maxLength": 2 } } } } } } } }, "responses": { "200": { "description": "Authorized result. Projection depends on current scopes and data policy.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "feature_id", "version", "type", "output" ], "properties": { "feature_id": { "type": "string", "pattern": "^aif_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, "version": { "type": "integer", "minimum": 1 }, "type": { "const": "language_detection" }, "output": { "type": "object", "required": [ "language" ], "properties": { "language": { "anyOf": [ { "type": "string", "pattern": "^[a-z]{2}$", "description": "Two-letter language code, or null when undetermined." }, { "type": "null" } ] } } } } } }, "description": "The result of running offline language detection on the supplied text." } } }, "headers": { "X-Gateway-Operation-Id": { "description": "Retained command receipt identifier when command reservation was acknowledged; use operation_get with the original credential and website. Not proof of native success or delivery.", "schema": { "type": "string", "pattern": "^op_[a-f0-9]{64}$" } } } }, "400": { "description": "Invalid, duplicate or unsupported request parameters." }, "401": { "description": "Missing, expired or revoked installation credential." }, "404": { "description": "Resource not found or not permitted by current authority." }, "409": { "description": "idempotency_conflict: the key has different input or authority revisions; operation_in_progress: the same command is pending; operation_conflict: native business state rejects the change; outcome_unknown: the native result is uncertain or no longer retained. Keep the same key and input for retries; never automatically create a new key or resubmit the effect.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "title", "status", "code", "request_id" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 409 }, "code": { "type": "string", "enum": [ "idempotency_conflict", "operation_in_progress", "operation_conflict", "outcome_unknown" ] }, "request_id": { "type": "string" } } } } }, "headers": { "X-Gateway-Operation-Id": { "description": "Retained command receipt identifier when command reservation was acknowledged; use operation_get with the original credential and website. Not proof of native success or delivery.", "schema": { "type": "string", "pattern": "^op_[a-f0-9]{64}$" } } } }, "422": { "description": "The requested capability is not available for application installations." }, "429": { "description": "Per-app quota exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Enrollment, native service or required authority is unavailable." } }, "tags": [ "AI features" ] } }, "/api/v1/analytics/ai-conversations/summary": { "get": { "operationId": "ai_conversation_summary", "summary": "Get the AI conversation summary", "description": "Summarize AI-evidenced conversations for an explicitly granted website and a bounded historical period. Current channel, team and subsite restrictions apply. Content-derived, language and operator measures can be unavailable under the current data policy. This does not cover all conversations.", "parameters": [ { "name": "website_id", "in": "query", "required": true, "description": "An explicitly granted website.", "schema": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" } }, { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "today", "last-7-days", "last-month", "date" ] } }, { "name": "start", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" } }, { "name": "end", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" } }, { "name": "timezone", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[A-Za-z0-9_+/-]+$" } } ], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "reports_read", "conversation_read" ] } ], "x-required-scopes": [ "reports_read", "conversation_read" ], "x-required-data-access": [], "x-restrictions-supported": true, "x-restriction-dimensions": [ "channel_ids", "team_ids", "subsite_ids" ], "x-mutation": false, "x-idempotency-required": false, "x-author-mapping-required": false, "responses": { "200": { "description": "Authorized result. Projection depends on current scopes and data policy.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "meta", "headline", "summary" ], "properties": { "meta": { "type": "object", "required": [ "coverage", "restriction_dimensions", "data_access" ], "properties": { "coverage": { "const": "ai_evidenced_conversations" }, "range": { "type": "string", "enum": [ "today", "last-7-days", "last-month", "date" ] }, "start": { "type": "string" }, "end": { "type": "string" }, "time_zone": { "type": "string", "description": "The website IANA time zone." }, "generated_at": { "type": "string" }, "source": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "truncated": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "cache_seconds": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "restriction_dimensions": { "type": "array", "items": { "type": "string" }, "description": "Installation restriction dimensions applied before aggregation." }, "data_access": { "type": "object", "required": [ "content_derived_measures", "language_labels", "operator_labels" ], "properties": { "content_derived_measures": { "type": "boolean" }, "language_labels": { "type": "boolean" }, "operator_labels": { "type": "boolean" } } } } }, "website": { "type": "object", "required": [], "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } }, "headline": { "type": "object", "required": [], "properties": { "ai_conversations": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "ai_touched_visitors": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "ai_assisted_conversations": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "ai_customer_facing_conversations": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "human_escalations": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } }, "summary": { "type": "object", "required": [ "series", "metrics", "ratings", "outcomes", "duration_by_platform" ], "properties": { "series": { "type": "object", "required": [ "volume", "volume_hourly", "platform", "topics", "language", "sentiment", "resolution", "operators" ], "properties": { "volume": { "anyOf": [ { "type": "array", "items": { "type": "array", "prefixItems": [ { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, { "type": "integer", "minimum": 0 } ], "items": false, "minItems": 2, "maxItems": 2 }, "description": "Conversation volume by day. Each bucket is a [label, count] pair. null when the credential lacks the required access." }, { "type": "null" } ] }, "volume_hourly": { "anyOf": [ { "type": "array", "items": { "type": "array", "prefixItems": [ { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, { "type": "integer", "minimum": 0 } ], "items": false, "minItems": 2, "maxItems": 2 }, "description": "Conversation volume by hour. Each bucket is a [label, count] pair. null when the credential lacks the required access." }, { "type": "null" } ] }, "platform": { "anyOf": [ { "type": "array", "items": { "type": "array", "prefixItems": [ { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, { "type": "integer", "minimum": 0 } ], "items": false, "minItems": 2, "maxItems": 2 }, "description": "Volume by platform. Each bucket is a [label, count] pair. null when the credential lacks the required access." }, { "type": "null" } ] }, "topics": { "anyOf": [ { "type": "array", "items": { "type": "array", "prefixItems": [ { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, { "type": "integer", "minimum": 0 } ], "items": false, "minItems": 2, "maxItems": 2 }, "description": "Needs content access. Each bucket is a [label, count] pair. null when the credential lacks the required access." }, { "type": "null" } ] }, "language": { "anyOf": [ { "type": "array", "items": { "type": "array", "prefixItems": [ { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, { "type": "integer", "minimum": 0 } ], "items": false, "minItems": 2, "maxItems": 2 }, "description": "Needs PII access. Each bucket is a [label, count] pair. null when the credential lacks the required access." }, { "type": "null" } ] }, "sentiment": { "anyOf": [ { "type": "array", "items": { "type": "array", "prefixItems": [ { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, { "type": "integer", "minimum": 0 } ], "items": false, "minItems": 2, "maxItems": 2 }, "description": "Needs content access. Each bucket is a [label, count] pair. null when the credential lacks the required access." }, { "type": "null" } ] }, "resolution": { "anyOf": [ { "type": "array", "items": { "type": "array", "prefixItems": [ { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, { "type": "integer", "minimum": 0 } ], "items": false, "minItems": 2, "maxItems": 2 }, "description": "Needs content access. Each bucket is a [label, count] pair. null when the credential lacks the required access." }, { "type": "null" } ] }, "operators": { "anyOf": [ { "type": "array", "items": { "type": "array", "prefixItems": [ { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, { "type": "integer", "minimum": 0 } ], "items": false, "minItems": 2, "maxItems": 2 }, "description": "Needs directory_read and PII access. Each bucket is a [label, count] pair. null when the credential lacks the required access." }, { "type": "null" } ] } } }, "metrics": { "type": "object", "required": [], "properties": { "message_count": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "visitor_message_count": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "bot_message_count": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "operator_message_count": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "first_response_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "first_response_count": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "speed_response_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "speed_response_count": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "average_response_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "duration_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "classified_count": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "resolved_count": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "first_contact_count": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "first_contact_resolved": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "sentiment_average": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "confidence_average": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "confidence_count": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } }, "ratings": { "anyOf": [ { "type": "array", "items": { "type": "array", "prefixItems": [ { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, { "type": "integer", "minimum": 0 } ], "items": false, "minItems": 2, "maxItems": 2 }, "description": "Star ratings. Needs content access. Each bucket is a [label, count] pair. null when the credential lacks the required access." }, { "type": "null" } ] }, "outcomes": { "anyOf": [ { "type": "array", "items": { "type": "array", "prefixItems": [ { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, { "type": "integer", "minimum": 0 } ], "items": false, "minItems": 2, "maxItems": 2 }, "description": "Outcomes. Needs content access. Each bucket is a [label, count] pair. null when the credential lacks the required access." }, { "type": "null" } ] }, "duration_by_platform": { "type": "array", "items": { "type": "object", "required": [ "platform" ], "properties": { "platform": { "type": "string" }, "conversation_count": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "sample_count": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "average_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } } } } } } } }, "description": "Aggregates over AI-evidenced conversations only. Content-derived measures are null, never zero, without the required access." } } } }, "400": { "description": "Invalid, duplicate or unsupported request parameters." }, "401": { "description": "Missing, expired or revoked installation credential." }, "404": { "description": "Resource not found or not permitted by current authority." }, "422": { "description": "The requested capability is not available for application installations." }, "429": { "description": "Per-app quota exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Enrollment, native service or required authority is unavailable." } }, "tags": [ "Reporting" ] } }, "/api/v1/dashboard/visitors/{visitor_id}": { "get": { "operationId": "visitor", "summary": "Get a visitor", "description": "Read stored visitor identity and optional nickname without requiring AI activity. Unrestricted installation policy required. Nickname requires PII permission and scope; contact enrichment, tracking and live state are excluded.", "parameters": [ { "name": "visitor_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^vis_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" } }, { "name": "website_id", "in": "query", "required": false, "description": "Optional; if present must match the resource owner.", "schema": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" } } ], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "conversation_read" ] } ], "x-required-scopes": [ "conversation_read" ], "x-required-data-access": [], "x-restrictions-supported": false, "x-restriction-dimensions": [], "x-mutation": false, "x-idempotency-required": false, "x-author-mapping-required": false, "responses": { "200": { "description": "Authorized result. Projection depends on current scopes and data policy.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "visitor", "coverage" ], "properties": { "visitor": { "type": "object", "additionalProperties": false, "required": [ "id", "nickname" ], "properties": { "id": { "type": "string", "maxLength": 100, "pattern": "^vis_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, "nickname": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] } } }, "coverage": { "const": "persisted_visitor_metadata" } } } } } } } }, "400": { "description": "Invalid, duplicate or unsupported request parameters." }, "401": { "description": "Missing, expired or revoked installation credential." }, "404": { "description": "Resource not found or not permitted by current authority." }, "422": { "description": "The requested capability is not available for application installations." }, "429": { "description": "Per-app quota exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Enrollment, native service or required authority is unavailable." } }, "tags": [ "Visitors" ] } }, "/api/v1/dashboard/visitors/{visitor_id}/conversations": { "get": { "operationId": "visitor_conversations", "summary": "List visitor conversations", "description": "Read a visitor's authorized conversation history.", "parameters": [ { "name": "visitor_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^vis_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" } }, { "name": "website_id", "in": "query", "required": false, "description": "Optional; if present must match the resource owner.", "schema": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(?:con_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}|[A-Za-z0-9+/]{2,26}={0,2})$", "maxLength": 100, "description": "Continue at the last delivered owned resource ID. Existing canonical base64 positive signed-64-bit numeric history cursors are also accepted for transcript and visitor history." } } ], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "conversation_read" ] } ], "x-required-scopes": [ "conversation_read" ], "x-required-data-access": [], "x-restrictions-supported": true, "x-restriction-dimensions": [ "channel_ids", "team_ids", "subsite_ids" ], "x-mutation": false, "x-idempotency-required": false, "x-author-mapping-required": false, "responses": { "200": { "description": "Authorized result. Projection depends on current scopes and data policy.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "data", "next_cursor", "coverage" ], "properties": { "data": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "id", "visitor_id", "operator_id", "status", "platform", "started_at", "active", "subject" ], "properties": { "id": { "type": "string", "maxLength": 100, "pattern": "^con_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, "visitor_id": { "type": "string", "maxLength": 100, "pattern": "^vis_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, "operator_id": { "anyOf": [ { "type": "string", "maxLength": 100, "pattern": "^opr_[0-9]{1,20}_[1-9][0-9]{0,9}$" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "unassigned", "open", "pending", "closed", "resolved", "onhold", "unknown" ] }, "platform": { "type": "string", "enum": [ "chat", "email", "voice", "sms", "messenger", "salesforce", "zendesk", "facebook", "line", "whatsapp", "twitter", "wechat", "apple_messages", "qr_code", "google_business_messages", "instagram", "kakao_talk", "viber", "unknown" ] }, "started_at": { "type": "string", "format": "date-time", "maxLength": 40 }, "active": { "type": "boolean" }, "subject": { "anyOf": [ { "type": "string", "maxLength": 4000 }, { "type": "null" } ] } } } }, "next_cursor": { "anyOf": [ { "type": "string", "maxLength": 100, "pattern": "^con_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, { "type": "null" } ] }, "coverage": { "const": "persisted_conversations" } } } } } } } }, "400": { "description": "Invalid, duplicate or unsupported request parameters." }, "401": { "description": "Missing, expired or revoked installation credential." }, "404": { "description": "Resource not found or not permitted by current authority." }, "422": { "description": "The requested capability is not available for application installations." }, "429": { "description": "Per-app quota exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Enrollment, native service or required authority is unavailable." } }, "tags": [ "Visitors" ] } }, "/api/v1/conversations/{conversation_id}": { "get": { "operationId": "conversation", "summary": "Get a conversation", "description": "Read an authorized conversation with its permitted data projection.", "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^con_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" } }, { "name": "website_id", "in": "query", "required": false, "description": "Optional; if present must match the resource owner.", "schema": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" } } ], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "conversation_read" ] } ], "x-required-scopes": [ "conversation_read" ], "x-required-data-access": [], "x-restrictions-supported": true, "x-restriction-dimensions": [ "channel_ids", "team_ids", "subsite_ids" ], "x-mutation": false, "x-idempotency-required": false, "x-author-mapping-required": false, "responses": { "200": { "description": "Authorized result. Projection depends on current scopes and data policy.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "conversation", "coverage" ], "properties": { "conversation": { "type": "object", "additionalProperties": false, "required": [ "id", "visitor_id", "operator_id", "status", "platform", "started_at", "active", "subject" ], "properties": { "id": { "type": "string", "maxLength": 100, "pattern": "^con_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, "visitor_id": { "type": "string", "maxLength": 100, "pattern": "^vis_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, "operator_id": { "anyOf": [ { "type": "string", "maxLength": 100, "pattern": "^opr_[0-9]{1,20}_[1-9][0-9]{0,9}$" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "unassigned", "open", "pending", "closed", "resolved", "onhold", "unknown" ] }, "platform": { "type": "string", "enum": [ "chat", "email", "voice", "sms", "messenger", "salesforce", "zendesk", "facebook", "line", "whatsapp", "twitter", "wechat", "apple_messages", "qr_code", "google_business_messages", "instagram", "kakao_talk", "viber", "unknown" ] }, "started_at": { "type": "string", "format": "date-time", "maxLength": 40 }, "active": { "type": "boolean" }, "subject": { "anyOf": [ { "type": "string", "maxLength": 4000 }, { "type": "null" } ] } } }, "coverage": { "const": "persisted_conversations" } } } } } } } }, "400": { "description": "Invalid, duplicate or unsupported request parameters." }, "401": { "description": "Missing, expired or revoked installation credential." }, "404": { "description": "Resource not found or not permitted by current authority." }, "422": { "description": "The requested capability is not available for application installations." }, "429": { "description": "Per-app quota exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Enrollment, native service or required authority is unavailable." } }, "tags": [ "Conversations" ] } }, "/api/v1/conversations/{conversation_id}/contacts": { "get": { "operationId": "conversation_contacts", "summary": "List contacts linked to a conversation", "description": "Page current contact IDs linked to the selected stored conversation visitor. Unrestricted policy required; excludes erased/foreign links and profiles, with no inferred primary or remote CRM.", "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^con_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" } }, { "name": "website_id", "in": "query", "required": false, "description": "Optional; if present must match the resource owner.", "schema": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^ctc_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$", "maxLength": 100, "description": "Continue at the last delivered owned resource ID. Existing canonical base64 positive signed-64-bit numeric history cursors are also accepted for transcript and visitor history." } } ], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "conversation_read", "contact_read", "contact_read_pii" ] } ], "x-required-scopes": [ "conversation_read", "contact_read", "contact_read_pii" ], "x-required-data-access": [ "pii" ], "x-restrictions-supported": false, "x-restriction-dimensions": [], "x-mutation": false, "x-idempotency-required": false, "x-author-mapping-required": false, "responses": { "200": { "description": "Authorized result. Projection depends on current scopes and data policy.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "data", "next_cursor", "coverage", "conversation_id" ], "properties": { "data": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "maxLength": 100, "pattern": "^ctc_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" } } } }, "next_cursor": { "anyOf": [ { "type": "string", "maxLength": 100, "pattern": "^ctc_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, { "type": "null" } ] }, "coverage": { "const": "persisted_conversation_contact_links" }, "conversation_id": { "type": "string", "maxLength": 100, "pattern": "^con_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" } } } } } } } }, "400": { "description": "Invalid, duplicate or unsupported request parameters." }, "401": { "description": "Missing, expired or revoked installation credential." }, "404": { "description": "Resource not found or not permitted by current authority." }, "422": { "description": "The requested capability is not available for application installations." }, "429": { "description": "Per-app quota exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Enrollment, native service or required authority is unavailable." } }, "tags": [ "Conversations" ] } }, "/api/v1/files/{file_id}/content": { "get": { "operationId": "file_content", "summary": "Read file content", "description": "Read up to65536 file bytes for an exact permitted message as base64. Requires file/transcript grants and restrictions; internal notes need opt-in. Every range is reauthorized; pin the returned version for continuation. No storage URL, upload or automatic paging.", "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^fil_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" } }, { "name": "website_id", "in": "query", "required": false, "description": "Optional; if present must match the resource owner.", "schema": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" } }, { "name": "conversation_id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^con_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$", "maxLength": 100 } }, { "name": "message_id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^msg_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$", "maxLength": 100 } }, { "name": "include_internal", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "description": "Explicitly include stored internal messages. Requires internal_notes_read and the internal_notes data flag in addition to all transcript grants. Default is public messages only." } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,18})$", "maxLength": 19, "default": "0", "description": "Canonical signed64 decimal byte offset; a positive offset requires expected_version from the preceding range." } }, { "name": "length", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 65536, "default": 65536 } }, { "name": "expected_version", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^sha256_[a-f0-9]{64}$", "maxLength": 71, "description": "Pin the file version for every continuation. A changed version is unavailable; explicitly restart at offset zero to choose a new version." } }, { "name": "Accept", "in": "header", "required": false, "description": "JSON by default. application/octet-stream selects bounded raw bytes for the same query offset/length/version. Quality weights are supported.", "schema": { "type": "string", "maxLength": 1024 } }, { "name": "Range", "in": "header", "required": false, "description": "One canonical closed bytes=start-end range of at most65536 bytes, requiring binary Accept. Query offset/length must agree. Suffix, open and multiple ranges are unsupported. Positive start requires expected_version or If-Match.", "schema": { "type": "string", "maxLength": 45, "pattern": "^bytes=(?:0|[1-9][0-9]{0,18})-(?:0|[1-9][0-9]{0,18})$" } }, { "name": "If-Match", "in": "header", "required": false, "description": "One quoted opaque file version from ETag. Intersects expected_version when both are present. Weak, wildcard and multiple tags are unsupported. An authorized version mismatch returns412 without content.", "schema": { "type": "string", "maxLength": 73, "pattern": "^\"sha256_[a-f0-9]{64}\"$" } } ], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "file_read", "conversation_read", "message_content_read", "contact_read_pii" ] } ], "x-required-scopes": [ "file_read", "conversation_read", "message_content_read", "contact_read_pii" ], "x-required-data-access": [ "message_content", "pii" ], "x-restrictions-supported": true, "x-restriction-dimensions": [ "channel_ids", "team_ids", "subsite_ids" ], "x-mutation": false, "x-idempotency-required": false, "x-author-mapping-required": false, "x-conditional-permissions": [ { "parameter": "include_internal", "value": true, "required_scopes": [ "internal_notes_read" ], "required_data_access": [ "internal_notes" ] } ], "responses": { "200": { "description": "Authorized result. Projection depends on current scopes and data policy.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "conversation_id", "message_id", "visibility", "file", "offset", "bytes_read", "content_base64", "next_offset", "version", "sha256", "coverage" ], "properties": { "conversation_id": { "type": "string", "maxLength": 100, "pattern": "^con_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, "message_id": { "type": "string", "maxLength": 100, "pattern": "^msg_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, "visibility": { "type": "string", "enum": [ "public", "internal" ] }, "file": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "content_type", "size_bytes" ], "properties": { "id": { "type": "string", "maxLength": 100, "pattern": "^fil_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, "name": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ] }, "content_type": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9!#$&^_.+-]*/[a-z0-9][a-z0-9!#$&^_.+-]*$" }, "size_bytes": { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,18})$", "maxLength": 19 } } }, "offset": { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,18})$", "maxLength": 19 }, "bytes_read": { "type": "integer", "minimum": 0, "maximum": 65536 }, "content_base64": { "type": "string", "maxLength": 87384, "contentEncoding": "base64" }, "next_offset": { "anyOf": [ { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,18})$", "maxLength": 19 }, { "type": "null" } ] }, "version": { "type": "string", "pattern": "^sha256_[a-f0-9]{64}$", "maxLength": 71 }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$", "maxLength": 64 }, "coverage": { "const": "stored_attachment_content_range" } } } } } }, "application/octet-stream": { "schema": { "type": "string", "format": "binary", "maxLength": 65536 } } }, "headers": { "ETag": { "description": "Binary only: quoted opaque version; pass its unquoted value as expected_version on continuation.", "schema": { "type": "string" } }, "X-Gateway-File-Offset": { "description": "Binary only: selected decimal byte offset.", "schema": { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,18})$" } }, "X-Gateway-File-Size": { "description": "Binary only: exact decimal total file size.", "schema": { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,18})$" } }, "X-Gateway-Next-Offset": { "description": "Binary only: continue at this decimal offset; absent at EOF.", "schema": { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,18})$" } }, "X-Gateway-Content-SHA256": { "description": "Binary only: SHA256 of the selected bytes.", "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } } }, "206": { "description": "The verified requested bounded HTTP byte range; actual end is clipped at file EOF.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary", "maxLength": 65536 } } }, "headers": { "ETag": { "description": "Binary only: quoted opaque version; pass its unquoted value as expected_version on continuation.", "schema": { "type": "string" } }, "X-Gateway-File-Offset": { "description": "Binary only: selected decimal byte offset.", "schema": { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,18})$" } }, "X-Gateway-File-Size": { "description": "Binary only: exact decimal total file size.", "schema": { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,18})$" } }, "X-Gateway-Next-Offset": { "description": "Binary only: continue at this decimal offset; absent at EOF.", "schema": { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,18})$" } }, "X-Gateway-Content-SHA256": { "description": "Binary only: SHA256 of the selected bytes.", "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "Content-Range": { "schema": { "type": "string", "pattern": "^bytes [0-9]+-[0-9]+/[0-9]+$" } } } }, "400": { "description": "Invalid, duplicate or unsupported request parameters." }, "401": { "description": "Missing, expired or revoked installation credential." }, "404": { "description": "Resource not found or not permitted by current authority." }, "406": { "description": "No acceptable JSON or binary representation. Errors always use problem JSON." }, "409": { "description": "Explicit expected_version no longer matches the authorized file; no content." }, "412": { "description": "The supplied If-Match file version no longer matches; no content." }, "416": { "description": "The requested offset has no authorized bytes. An empty-file HTTP range includes Content-Range: bytes */0; no content or file headers." }, "422": { "description": "The requested capability is not available for application installations." }, "429": { "description": "Per-app quota exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Enrollment, native service or required authority is unavailable." } }, "tags": [ "Files" ] } }, "/api/v1/files/{file_id}": { "get": { "operationId": "file_get", "summary": "Get file metadata", "description": "Read metadata for one file linked to an exact permitted conversation message. Requires all file/transcript grants and restrictions; internal messages need notes opt-in. Storage URLs and download/upload are unavailable.", "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^fil_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" } }, { "name": "website_id", "in": "query", "required": false, "description": "Optional; if present must match the resource owner.", "schema": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" } }, { "name": "conversation_id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^con_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$", "maxLength": 100 } }, { "name": "message_id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^msg_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$", "maxLength": 100 } }, { "name": "include_internal", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "description": "Explicitly include stored internal messages. Requires internal_notes_read and the internal_notes data flag in addition to all transcript grants. Default is public messages only." } } ], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "file_read", "conversation_read", "message_content_read", "contact_read_pii" ] } ], "x-required-scopes": [ "file_read", "conversation_read", "message_content_read", "contact_read_pii" ], "x-required-data-access": [ "message_content", "pii" ], "x-restrictions-supported": true, "x-restriction-dimensions": [ "channel_ids", "team_ids", "subsite_ids" ], "x-mutation": false, "x-idempotency-required": false, "x-author-mapping-required": false, "x-conditional-permissions": [ { "parameter": "include_internal", "value": true, "required_scopes": [ "internal_notes_read" ], "required_data_access": [ "internal_notes" ] } ], "responses": { "200": { "description": "Authorized result. Projection depends on current scopes and data policy.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "conversation_id", "message_id", "visibility", "file", "download_available", "coverage" ], "properties": { "conversation_id": { "type": "string", "maxLength": 100, "pattern": "^con_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, "message_id": { "type": "string", "maxLength": 100, "pattern": "^msg_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, "visibility": { "type": "string", "enum": [ "public", "internal" ] }, "file": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "content_type", "size_bytes" ], "properties": { "id": { "type": "string", "maxLength": 100, "pattern": "^fil_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, "name": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ] }, "content_type": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9!#$&^_.+-]*/[a-z0-9][a-z0-9!#$&^_.+-]*$" }, "size_bytes": { "anyOf": [ { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,18})$", "maxLength": 19 }, { "type": "null" } ] } } }, "download_available": { "const": false }, "coverage": { "const": "persisted_message_attachment_metadata" } } } } } } } }, "400": { "description": "Invalid, duplicate or unsupported request parameters." }, "401": { "description": "Missing, expired or revoked installation credential." }, "404": { "description": "Resource not found or not permitted by current authority." }, "422": { "description": "The requested capability is not available for application installations." }, "429": { "description": "Per-app quota exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Enrollment, native service or required authority is unavailable." } }, "tags": [ "Files" ] } }, "/api/v1/conversations/{conversation_id}/messages/{message_id}/attachments": { "get": { "operationId": "conversation_message_attachments", "summary": "List message attachments", "description": "Read bounded stored attachment metadata for an exact permitted conversation message. Requires explicit file_read and transcript grants. Internal messages require notes opt-in. Returns basename, MIME and decimal size only; download/upload are unavailable.", "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^con_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" } }, { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^msg_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" } }, { "name": "website_id", "in": "query", "required": false, "description": "Optional; if present must match the resource owner.", "schema": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^fil_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$", "maxLength": 100, "description": "Continue at the last delivered owned resource ID. Existing canonical base64 positive signed-64-bit numeric history cursors are also accepted for transcript and visitor history." } }, { "name": "include_internal", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "description": "Explicitly include stored internal messages. Requires internal_notes_read and the internal_notes data flag in addition to all transcript grants. Default is public messages only." } } ], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "file_read", "conversation_read", "message_content_read", "contact_read_pii" ] } ], "x-required-scopes": [ "file_read", "conversation_read", "message_content_read", "contact_read_pii" ], "x-required-data-access": [ "message_content", "pii" ], "x-restrictions-supported": true, "x-restriction-dimensions": [ "channel_ids", "team_ids", "subsite_ids" ], "x-mutation": false, "x-idempotency-required": false, "x-author-mapping-required": false, "x-conditional-permissions": [ { "parameter": "include_internal", "value": true, "required_scopes": [ "internal_notes_read" ], "required_data_access": [ "internal_notes" ] } ], "responses": { "200": { "description": "Authorized result. Projection depends on current scopes and data policy.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "conversation_id", "message_id", "visibility", "files", "next_cursor", "download_available", "coverage" ], "properties": { "conversation_id": { "type": "string", "maxLength": 100, "pattern": "^con_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, "message_id": { "type": "string", "maxLength": 100, "pattern": "^msg_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, "visibility": { "type": "string", "enum": [ "public", "internal" ] }, "files": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "content_type", "size_bytes" ], "properties": { "id": { "type": "string", "maxLength": 100, "pattern": "^fil_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, "name": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ] }, "content_type": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9!#$&^_.+-]*/[a-z0-9][a-z0-9!#$&^_.+-]*$" }, "size_bytes": { "anyOf": [ { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,18})$", "maxLength": 19 }, { "type": "null" } ] } } } }, "next_cursor": { "anyOf": [ { "type": "string", "maxLength": 100, "pattern": "^fil_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, { "type": "null" } ] }, "download_available": { "const": false }, "coverage": { "const": "persisted_message_attachment_metadata" } } } } } } } }, "400": { "description": "Invalid, duplicate or unsupported request parameters." }, "401": { "description": "Missing, expired or revoked installation credential." }, "404": { "description": "Resource not found or not permitted by current authority." }, "422": { "description": "The requested capability is not available for application installations." }, "429": { "description": "Per-app quota exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Enrollment, native service or required authority is unavailable." } }, "tags": [ "Files" ] } }, "/api/v1/conversations/{conversation_id}/messages/{message_id}": { "get": { "operationId": "conversation_message", "summary": "Get a message", "description": "Read one stored message belonging to an exact conversation. Existing transcript grants and restrictions apply; internal messages require explicit notes opt-in.", "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^con_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" } }, { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^msg_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" } }, { "name": "website_id", "in": "query", "required": false, "description": "Optional; if present must match the resource owner.", "schema": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" } }, { "name": "include_internal", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "description": "Explicitly include stored internal messages. Requires internal_notes_read and the internal_notes data flag in addition to all transcript grants. Default is public messages only." } } ], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "conversation_read", "message_content_read", "contact_read_pii" ] } ], "x-required-scopes": [ "conversation_read", "message_content_read", "contact_read_pii" ], "x-required-data-access": [ "message_content", "pii" ], "x-restrictions-supported": true, "x-restriction-dimensions": [ "channel_ids", "team_ids", "subsite_ids" ], "x-mutation": false, "x-idempotency-required": false, "x-author-mapping-required": false, "x-conditional-permissions": [ { "parameter": "include_internal", "value": true, "required_scopes": [ "internal_notes_read" ], "required_data_access": [ "internal_notes" ] } ], "responses": { "200": { "description": "Authorized result. Projection depends on current scopes and data policy.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "message", "content_included", "coverage" ], "properties": { "message": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "delivery_status", "id", "conversation_id", "occurred_at", "sender_type", "sender_name", "visibility", "content_type", "content", "content_included", "content_truncated" ], "properties": { "delivery_status": { "type": "string", "enum": [ "pending", "sent", "error", "read", "sending", "unknown" ] }, "id": { "type": "string", "maxLength": 100, "pattern": "^msg_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, "conversation_id": { "type": "string", "maxLength": 100, "pattern": "^con_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, "occurred_at": { "type": "string", "format": "date-time", "maxLength": 40 }, "sender_type": { "type": "string", "enum": [ "visitor", "operator", "system", "unknown" ] }, "sender_name": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "visibility": { "type": "string", "enum": [ "public", "internal" ] }, "content_type": { "type": "string", "enum": [ "text/plain", "text/html", "text/markdown", "text/inside.markdown", "text/inside.legacy" ] }, "content": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "content_included": { "const": true }, "content_truncated": { "type": "boolean" } } }, { "type": "object", "additionalProperties": false, "required": [ "delivery_status", "id", "conversation_id", "occurred_at", "sender_type", "sender_name", "visibility", "content_type", "content", "content_included", "content_truncated" ], "properties": { "delivery_status": { "type": "string", "enum": [ "pending", "sent", "error", "read", "sending", "unknown" ] }, "id": { "type": "string", "maxLength": 100, "pattern": "^msg_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, "conversation_id": { "type": "string", "maxLength": 100, "pattern": "^con_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, "occurred_at": { "type": "string", "format": "date-time", "maxLength": 40 }, "sender_type": { "type": "string", "enum": [ "visitor", "operator", "system", "unknown" ] }, "sender_name": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "visibility": { "type": "string", "enum": [ "public", "internal" ] }, "content_type": { "const": "unsupported" }, "content": { "type": "null" }, "content_included": { "const": false }, "content_truncated": { "const": false } } } ] }, "content_included": { "const": true }, "coverage": { "type": "string", "enum": [ "persisted_public_messages", "persisted_permitted_messages" ] } } } } } } } }, "400": { "description": "Invalid, duplicate or unsupported request parameters." }, "401": { "description": "Missing, expired or revoked installation credential." }, "404": { "description": "Resource not found or not permitted by current authority." }, "422": { "description": "The requested capability is not available for application installations." }, "429": { "description": "Per-app quota exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Enrollment, native service or required authority is unavailable." } }, "tags": [ "Conversations" ] } }, "/api/v1/conversations/{conversation_id}/messages": { "get": { "operationId": "conversation_messages", "summary": "List conversation messages", "description": "Read persisted public transcript messages by default. Content and PII access are both required. Explicit include_internal=true additionally requires internal_notes_read and the internal_notes data flag; returns public/internal visibility labels.", "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^con_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" } }, { "name": "website_id", "in": "query", "required": false, "description": "Optional; if present must match the resource owner.", "schema": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(?:msg_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}|[A-Za-z0-9+/]{2,26}={0,2})$", "maxLength": 100, "description": "Continue at the last delivered owned resource ID. Existing canonical base64 positive signed-64-bit numeric history cursors are also accepted for transcript and visitor history." } }, { "name": "include_internal", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "description": "Explicitly include stored internal messages. Requires internal_notes_read and the internal_notes data flag in addition to all transcript grants. Default is public messages only." } } ], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "conversation_read", "message_content_read", "contact_read_pii" ] } ], "x-required-scopes": [ "conversation_read", "message_content_read", "contact_read_pii" ], "x-required-data-access": [ "message_content", "pii" ], "x-restrictions-supported": true, "x-restriction-dimensions": [ "channel_ids", "team_ids", "subsite_ids" ], "x-mutation": false, "x-idempotency-required": false, "x-author-mapping-required": false, "x-conditional-permissions": [ { "parameter": "include_internal", "value": true, "required_scopes": [ "internal_notes_read" ], "required_data_access": [ "internal_notes" ] } ], "responses": { "200": { "description": "Authorized result. Projection depends on current scopes and data policy.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "data", "next_cursor", "coverage", "content_included" ], "properties": { "data": { "type": "array", "maxItems": 100, "items": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "delivery_status", "id", "conversation_id", "occurred_at", "sender_type", "sender_name", "visibility", "content_type", "content", "content_included", "content_truncated" ], "properties": { "delivery_status": { "type": "string", "enum": [ "pending", "sent", "error", "read", "sending", "unknown" ] }, "id": { "type": "string", "maxLength": 100, "pattern": "^msg_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, "conversation_id": { "type": "string", "maxLength": 100, "pattern": "^con_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, "occurred_at": { "type": "string", "format": "date-time", "maxLength": 40 }, "sender_type": { "type": "string", "enum": [ "visitor", "operator", "system", "unknown" ] }, "sender_name": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "visibility": { "type": "string", "enum": [ "public", "internal" ] }, "content_type": { "type": "string", "enum": [ "text/plain", "text/html", "text/markdown", "text/inside.markdown", "text/inside.legacy" ] }, "content": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "content_included": { "const": true }, "content_truncated": { "type": "boolean" } } }, { "type": "object", "additionalProperties": false, "required": [ "delivery_status", "id", "conversation_id", "occurred_at", "sender_type", "sender_name", "visibility", "content_type", "content", "content_included", "content_truncated" ], "properties": { "delivery_status": { "type": "string", "enum": [ "pending", "sent", "error", "read", "sending", "unknown" ] }, "id": { "type": "string", "maxLength": 100, "pattern": "^msg_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, "conversation_id": { "type": "string", "maxLength": 100, "pattern": "^con_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, "occurred_at": { "type": "string", "format": "date-time", "maxLength": 40 }, "sender_type": { "type": "string", "enum": [ "visitor", "operator", "system", "unknown" ] }, "sender_name": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "visibility": { "type": "string", "enum": [ "public", "internal" ] }, "content_type": { "const": "unsupported" }, "content": { "type": "null" }, "content_included": { "const": false }, "content_truncated": { "const": false } } } ] } }, "next_cursor": { "anyOf": [ { "type": "string", "maxLength": 100, "pattern": "^msg_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, { "type": "null" } ] }, "coverage": { "type": "string", "enum": [ "persisted_public_messages", "persisted_permitted_messages" ] }, "content_included": { "const": true } } } } } } } }, "400": { "description": "Invalid, duplicate or unsupported request parameters." }, "401": { "description": "Missing, expired or revoked installation credential." }, "404": { "description": "Resource not found or not permitted by current authority." }, "422": { "description": "The requested capability is not available for application installations." }, "429": { "description": "Per-app quota exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Enrollment, native service or required authority is unavailable." } }, "tags": [ "Conversations" ] } }, "/api/v1/visitors/{visitor_id}/notes": { "get": { "operationId": "visitor_notes", "summary": "List visitor notes", "description": "Read a bounded descending page of active stored visitor notes, including notes from website-owned visitors linked through an active contact, without AI eligibility. Requires unrestricted policy and notes, content and PII access. Attachments and reminders are excluded.", "parameters": [ { "name": "visitor_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^vis_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" } }, { "name": "website_id", "in": "query", "required": false, "description": "Optional; if present must match the resource owner.", "schema": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,9}$", "maxLength": 10, "description": "Continue before the last delivered positive native note ID; maximum is 2147483647. The selected visitor and current website policy remain authoritative." } } ], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "conversation_read", "visitor_notes_read", "contact_read_pii" ] } ], "x-required-scopes": [ "conversation_read", "visitor_notes_read", "contact_read_pii" ], "x-required-data-access": [ "message_content", "pii", "internal_notes" ], "x-restrictions-supported": false, "x-restriction-dimensions": [], "x-mutation": false, "x-idempotency-required": false, "x-author-mapping-required": false, "responses": { "200": { "description": "Authorized result. Projection depends on current scopes and data policy.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "visitor_id", "notes", "next_cursor", "coverage" ], "properties": { "visitor_id": { "type": "string", "maxLength": 100, "pattern": "^vis_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" }, "notes": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "id", "note_id", "text", "title", "author", "created_at", "text_truncated" ], "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,9}$", "maxLength": 10 }, "note_id": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "text": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string", "maxLength": 240 }, { "type": "null" } ] }, "author": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time", "maxLength": 40 }, { "type": "null" } ] }, "text_truncated": { "type": "boolean" } } } }, "next_cursor": { "anyOf": [ { "type": "string", "pattern": "^[1-9][0-9]{0,9}$", "maxLength": 10 }, { "type": "null" } ] }, "coverage": { "const": "persisted_visitor_notes" } } } } } } } }, "400": { "description": "Invalid, duplicate or unsupported request parameters." }, "401": { "description": "Missing, expired or revoked installation credential." }, "404": { "description": "Resource not found or not permitted by current authority." }, "422": { "description": "The requested capability is not available for application installations." }, "429": { "description": "Per-app quota exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Enrollment, native service or required authority is unavailable." } }, "tags": [ "Visitors" ] }, "post": { "operationId": "visitor_note_add", "summary": "Add a visitor note", "description": "Add a visitor note using the newest persisted conversation, including non-AI conversations, with an enabled native author mapped to this exact website. Requires an unrestricted installation policy. Visitors without a stored conversation are unavailable. Results are retained for 24 hours. A permanent content-free tombstone prevents the same key from creating a new effect after result expiry. Reuse the same key and identical input when retrying. Changed input or policy/revisions conflict. Current policy is checked before result reuse. An unknown outcome returns 409 outcome_unknown; never retry with a new key automatically.", "parameters": [ { "name": "visitor_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^vis_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" } }, { "name": "website_id", "in": "query", "required": false, "description": "Optional; if present must match the resource owner.", "schema": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "A stable key for this intended effect. Reuse the same key and input for retries; never automatically replace it after an unknown outcome.", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]+$" } } ], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "conversation_read", "visitor_notes_write", "message_content_read", "contact_read_pii" ] } ], "x-required-scopes": [ "conversation_read", "visitor_notes_write", "message_content_read", "contact_read_pii" ], "x-required-data-access": [ "message_content", "pii", "internal_notes" ], "x-restrictions-supported": false, "x-restriction-dimensions": [], "x-mutation": true, "x-idempotency-required": true, "x-author-mapping-required": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "text" ], "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 4000, "description": "Nonempty after trimming; maximum length is 4000 UTF-16 code units." } } } } } }, "responses": { "200": { "description": "Authorized result. Projection depends on current scopes and data policy.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "success", "visitor_id", "note" ], "properties": { "success": { "const": true }, "visitor_id": { "type": "string", "pattern": "^vis_" }, "note": { "type": "object", "required": [ "id", "note_id", "text", "title", "author", "created_at" ], "properties": { "id": { "type": "string" }, "note_id": { "type": "integer" }, "text": { "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "author": { "anyOf": [ { "type": "string", "description": "The mapped native operator." }, { "type": "null" } ] }, "created_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 UTC." }, { "type": "null" } ] } } } } } }, "description": "The stored note, attributed to the mapped native operator." } } }, "headers": { "X-Gateway-Operation-Id": { "description": "Retained command receipt identifier when command reservation was acknowledged; use operation_get with the original credential and website. Not proof of native success or delivery.", "schema": { "type": "string", "pattern": "^op_[a-f0-9]{64}$" } } } }, "400": { "description": "Invalid, duplicate or unsupported request parameters." }, "401": { "description": "Missing, expired or revoked installation credential." }, "404": { "description": "Resource not found or not permitted by current authority." }, "409": { "description": "idempotency_conflict: the key has different input or authority revisions; operation_in_progress: the same command is pending; operation_conflict: native business state rejects the change; outcome_unknown: the native result is uncertain or no longer retained. Keep the same key and input for retries; never automatically create a new key or resubmit the effect.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "title", "status", "code", "request_id" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 409 }, "code": { "type": "string", "enum": [ "idempotency_conflict", "operation_in_progress", "operation_conflict", "outcome_unknown" ] }, "request_id": { "type": "string" } } } } }, "headers": { "X-Gateway-Operation-Id": { "description": "Retained command receipt identifier when command reservation was acknowledged; use operation_get with the original credential and website. Not proof of native success or delivery.", "schema": { "type": "string", "pattern": "^op_[a-f0-9]{64}$" } } } }, "422": { "description": "The requested capability is not available for application installations." }, "429": { "description": "Per-app quota exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Enrollment, native service or required authority is unavailable." } }, "tags": [ "Visitors" ] } }, "/api/v1/conversations/{conversation_id}/disposition": { "post": { "operationId": "conversation_disposition_set", "summary": "Set a conversation disposition", "description": "Set a configured disposition on an ordinary persisted conversation by its string value with an enabled native author mapped to this exact website. Native execution is denied on Salesforce-integrated websites; disposition IDs are unsupported. Results are retained for 24 hours. A permanent content-free tombstone prevents the same key from creating a new effect after result expiry. Reuse the same key and identical input when retrying. Changed input or policy/revisions conflict. Current policy is checked before result reuse. An unknown outcome returns 409 outcome_unknown; never retry with a new key automatically.", "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^con_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$" } }, { "name": "website_id", "in": "query", "required": false, "description": "Optional; if present must match the resource owner.", "schema": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "A stable key for this intended effect. Reuse the same key and input for retries; never automatically replace it after an unknown outcome.", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]+$" } } ], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "conversation_read", "conversation_update" ] } ], "x-required-scopes": [ "conversation_read", "conversation_update" ], "x-required-data-access": [], "x-restrictions-supported": true, "x-restriction-dimensions": [ "channel_ids", "team_ids", "subsite_ids" ], "x-mutation": true, "x-idempotency-required": true, "x-author-mapping-required": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "disposition" ], "properties": { "disposition": { "type": "string", "minLength": 1, "maxLength": 200, "description": "A configured disposition string, nonempty after trimming; maximum length is 200 UTF-16 code units." } } } } } }, "responses": { "200": { "description": "Authorized result. Projection depends on current scopes and data policy.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "success", "conversation_id", "dispositions" ], "properties": { "success": { "const": true }, "conversation_id": { "type": "string", "pattern": "^con_" }, "dispositions": { "type": "array", "items": { "type": "string" } } } } }, "description": "The disposition now set on the conversation." } } }, "headers": { "X-Gateway-Operation-Id": { "description": "Retained command receipt identifier when command reservation was acknowledged; use operation_get with the original credential and website. Not proof of native success or delivery.", "schema": { "type": "string", "pattern": "^op_[a-f0-9]{64}$" } } } }, "400": { "description": "Invalid, duplicate or unsupported request parameters." }, "401": { "description": "Missing, expired or revoked installation credential." }, "404": { "description": "Resource not found or not permitted by current authority." }, "409": { "description": "idempotency_conflict: the key has different input or authority revisions; operation_in_progress: the same command is pending; operation_conflict: native business state rejects the change; outcome_unknown: the native result is uncertain or no longer retained. Keep the same key and input for retries; never automatically create a new key or resubmit the effect.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "title", "status", "code", "request_id" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 409 }, "code": { "type": "string", "enum": [ "idempotency_conflict", "operation_in_progress", "operation_conflict", "outcome_unknown" ] }, "request_id": { "type": "string" } } } } }, "headers": { "X-Gateway-Operation-Id": { "description": "Retained command receipt identifier when command reservation was acknowledged; use operation_get with the original credential and website. Not proof of native success or delivery.", "schema": { "type": "string", "pattern": "^op_[a-f0-9]{64}$" } } } }, "422": { "description": "The requested capability is not available for application installations." }, "429": { "description": "Per-app quota exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Enrollment, native service or required authority is unavailable." } }, "tags": [ "Conversations" ] } }, "/api/v1/operators": { "get": { "operationId": "operators", "summary": "List operators", "description": "List the website's permitted operator directory.", "parameters": [ { "name": "website_id", "in": "query", "required": true, "description": "An explicitly granted website.", "schema": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" } } ], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "directory_read", "contact_read_pii" ] } ], "x-required-scopes": [ "directory_read", "contact_read_pii" ], "x-required-data-access": [ "pii" ], "x-restrictions-supported": true, "x-restriction-dimensions": [ "channel_ids" ], "x-mutation": false, "x-idempotency-required": false, "x-author-mapping-required": false, "responses": { "200": { "description": "Authorized result. Projection depends on current scopes and data policy.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "pattern": "^opr_" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "available": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "connected": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "channel_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "channel_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "channel_number": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "active_conversations": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "is_bot": { "type": "boolean" }, "look": { "anyOf": [ { "type": "object", "description": "Sanitised avatar settings." }, { "type": "null" } ] } } } } } } }, "description": "Operators visible to this installation. Channel restrictions apply." } } } }, "400": { "description": "Invalid, duplicate or unsupported request parameters." }, "401": { "description": "Missing, expired or revoked installation credential." }, "404": { "description": "Resource not found or not permitted by current authority." }, "422": { "description": "The requested capability is not available for application installations." }, "429": { "description": "Per-app quota exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Enrollment, native service or required authority is unavailable." } }, "tags": [ "Directory and catalogues" ] } }, "/api/v1/dispositions": { "get": { "operationId": "dispositions", "summary": "List dispositions", "description": "List the website disposition catalogue. Requires an unrestricted installation policy.", "parameters": [ { "name": "website_id", "in": "query", "required": true, "description": "An explicitly granted website.", "schema": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" } }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string" } } ], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "conversation_read" ] } ], "x-required-scopes": [ "conversation_read" ], "x-required-data-access": [], "x-restrictions-supported": false, "x-restriction-dimensions": [], "x-mutation": false, "x-idempotency-required": false, "x-author-mapping-required": false, "responses": { "200": { "description": "Authorized result. Projection depends on current scopes and data policy.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "language", "dispositions" ], "properties": { "language": { "type": "string" }, "dispositions": { "type": "array", "items": { "type": "object", "required": [ "id", "disposition" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "disposition": { "type": "string", "description": "The value to send to conversation_disposition_set." }, "category_name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } } }, "description": "The configured disposition catalogue, localised to language when available." } } } }, "400": { "description": "Invalid, duplicate or unsupported request parameters." }, "401": { "description": "Missing, expired or revoked installation credential." }, "404": { "description": "Resource not found or not permitted by current authority." }, "422": { "description": "The requested capability is not available for application installations." }, "429": { "description": "Per-app quota exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Enrollment, native service or required authority is unavailable." } }, "tags": [ "Directory and catalogues" ] } }, "/api/v1/saved_responses": { "get": { "operationId": "saved_responses", "summary": "List saved responses", "description": "Read bounded localized global saved responses. Private operator/team/subsite entries are excluded. Unrestricted policy required; no visitor substitution, scripts or remote requests.", "parameters": [ { "name": "website_id", "in": "query", "required": true, "description": "An explicitly granted website.", "schema": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" } }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[a-zA-Z]{2,3}(?:-[a-zA-Z0-9]{2,8}){0,3}$", "maxLength": 35, "description": "Requested locale. Defaults to en; fallback follows native website language configuration." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "maxLength": 19, "description": "Continue before the last delivered positive saved-response ID (maximum9223372036854775807). The selected website remains authoritative." } } ], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "conversation_read" ] } ], "x-required-scopes": [ "conversation_read" ], "x-required-data-access": [], "x-restrictions-supported": false, "x-restriction-dimensions": [], "x-mutation": false, "x-idempotency-required": false, "x-author-mapping-required": false, "responses": { "200": { "description": "Authorized result. Projection depends on current scopes and data policy.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "language", "scope", "saved_responses", "next_cursor", "coverage" ], "properties": { "language": { "type": "string", "pattern": "^[a-z]{2,3}(?:-[a-z0-9]{2,8}){0,3}$", "maxLength": 35 }, "scope": { "const": "website_global" }, "saved_responses": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "id", "label", "content", "content_truncated", "category_name", "shortcut", "platform_id" ], "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "maxLength": 19 }, "label": { "type": "string", "maxLength": 240 }, "content": { "type": "string", "maxLength": 32768 }, "content_truncated": { "type": "boolean" }, "category_name": { "type": "string", "minLength": 1, "maxLength": 240 }, "shortcut": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "platform_id": { "type": "integer", "minimum": -1, "maximum": 2147483647 } } } }, "next_cursor": { "anyOf": [ { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "maxLength": 19 }, { "type": "null" } ] }, "coverage": { "const": "website_global_saved_responses" } } } } } } } }, "400": { "description": "Invalid, duplicate or unsupported request parameters." }, "401": { "description": "Missing, expired or revoked installation credential." }, "404": { "description": "Resource not found or not permitted by current authority." }, "422": { "description": "The requested capability is not available for application installations." }, "429": { "description": "Per-app quota exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Enrollment, native service or required authority is unavailable." } }, "tags": [ "Directory and catalogues" ] } }, "/api/v1/saved_links": { "get": { "operationId": "saved_links", "summary": "List saved links", "description": "Read a bounded descending catalogue of static website-global saved links with safe HTTP(S) URLs. Unrestricted installation policy required. Private operator, subsite, dynamic and scripted links are excluded before pagination. No visitor context, custom scripts or remote requests are invoked.", "parameters": [ { "name": "website_id", "in": "query", "required": true, "description": "An explicitly granted website.", "schema": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "maxLength": 19, "description": "Continue before the last delivered positive native saved-link ID (maximum9223372036854775807). The selected website remains authoritative." } } ], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "conversation_read" ] } ], "x-required-scopes": [ "conversation_read" ], "x-required-data-access": [], "x-restrictions-supported": false, "x-restriction-dimensions": [], "x-mutation": false, "x-idempotency-required": false, "x-author-mapping-required": false, "responses": { "200": { "description": "Authorized result. Projection depends on current scopes and data policy.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "scope", "saved_links", "next_cursor", "coverage" ], "properties": { "scope": { "const": "website_global" }, "saved_links": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "id", "label", "url" ], "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "maxLength": 19 }, "label": { "type": "string", "maxLength": 240 }, "url": { "type": "string", "format": "uri", "pattern": "^[Hh][Tt][Tt][Pp][Ss]?://", "maxLength": 2048 } } } }, "next_cursor": { "anyOf": [ { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "maxLength": 19 }, { "type": "null" } ] }, "coverage": { "const": "website_global_static_saved_links" } } } } } } } }, "400": { "description": "Invalid, duplicate or unsupported request parameters." }, "401": { "description": "Missing, expired or revoked installation credential." }, "404": { "description": "Resource not found or not permitted by current authority." }, "422": { "description": "The requested capability is not available for application installations." }, "429": { "description": "Per-app quota exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Enrollment, native service or required authority is unavailable." } }, "tags": [ "Directory and catalogues" ] } }, "/api/v1/offers": { "get": { "operationId": "offers", "summary": "List offers", "description": "List website offers. Requires an unrestricted installation policy.", "parameters": [ { "name": "website_id", "in": "query", "required": true, "description": "An explicitly granted website.", "schema": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" } } ], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "conversation_read" ] } ], "x-required-scopes": [ "conversation_read" ], "x-required-data-access": [], "x-restrictions-supported": false, "x-restriction-dimensions": [], "x-mutation": false, "x-idempotency-required": false, "x-author-mapping-required": false, "responses": { "200": { "description": "Authorized result. Projection depends on current scopes and data policy.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "offers" ], "properties": { "offers": { "type": "array", "items": { "type": "object", "required": [ "id", "label" ], "properties": { "id": { "type": "string" }, "offer_id": { "type": "integer" }, "label": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnail_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "content_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 UTC, or null when the offer has no expiry." }, { "type": "null" } ] }, "category_name": { "type": "string" } } } } } } }, "description": "Unexpired website offers." } } } }, "400": { "description": "Invalid, duplicate or unsupported request parameters." }, "401": { "description": "Missing, expired or revoked installation credential." }, "404": { "description": "Resource not found or not permitted by current authority." }, "422": { "description": "The requested capability is not available for application installations." }, "429": { "description": "Per-app quota exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Enrollment, native service or required authority is unavailable." } }, "tags": [ "Directory and catalogues" ] } }, "/api/v1/channels": { "get": { "operationId": "channels", "summary": "List channels", "description": "List the website's permitted channels.", "parameters": [ { "name": "website_id", "in": "query", "required": true, "description": "An explicitly granted website.", "schema": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" } } ], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "live_read" ] } ], "x-required-scopes": [ "live_read" ], "x-required-data-access": [], "x-restrictions-supported": true, "x-restriction-dimensions": [ "channel_ids" ], "x-mutation": false, "x-idempotency-required": false, "x-author-mapping-required": false, "responses": { "200": { "description": "Authorized result. Projection depends on current scopes and data policy.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "channels" ], "properties": { "channels": { "type": "array", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "pattern": "^chn_" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } } }, "description": "Channels visible to this installation. Channel restrictions apply." } } } }, "400": { "description": "Invalid, duplicate or unsupported request parameters." }, "401": { "description": "Missing, expired or revoked installation credential." }, "404": { "description": "Resource not found or not permitted by current authority." }, "422": { "description": "The requested capability is not available for application installations." }, "429": { "description": "Per-app quota exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Enrollment, native service or required authority is unavailable." } }, "tags": [ "Directory and catalogues" ] } }, "/api/v1/teams": { "get": { "operationId": "teams", "summary": "List teams", "description": "List the website's permitted teams.", "parameters": [ { "name": "website_id", "in": "query", "required": true, "description": "An explicitly granted website.", "schema": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" } } ], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "live_read" ] } ], "x-required-scopes": [ "live_read" ], "x-required-data-access": [], "x-restrictions-supported": true, "x-restriction-dimensions": [ "team_ids" ], "x-mutation": false, "x-idempotency-required": false, "x-author-mapping-required": false, "responses": { "200": { "description": "Authorized result. Projection depends on current scopes and data policy.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "teams" ], "properties": { "teams": { "type": "array", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "pattern": "^team_" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } } }, "description": "Teams visible to this installation. Team restrictions apply." } } } }, "400": { "description": "Invalid, duplicate or unsupported request parameters." }, "401": { "description": "Missing, expired or revoked installation credential." }, "404": { "description": "Resource not found or not permitted by current authority." }, "422": { "description": "The requested capability is not available for application installations." }, "429": { "description": "Per-app quota exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Enrollment, native service or required authority is unavailable." } }, "tags": [ "Directory and catalogues" ] } }, "/api/v1/subscriptions": { "get": { "operationId": "subscriptions_list", "description": "List at most20 subscriptions owned by the current installation. No wildcard website expansion.", "parameters": [], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "website_read", "event_read" ] } ], "x-required-scopes": [ "website_read", "event_read" ], "x-required-data-access": [], "x-restriction-dimensions": [], "x-native-command": false, "responses": { "200": { "description": "Current installation-authorized thin metadata. Cursors contain independent per-website positions; no total order is promised.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "subscriptions" ], "properties": { "subscriptions": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "subscription_id", "website_ids", "event_types", "revision", "status", "payload_mode", "delivery", "created_at", "updated_at" ], "properties": { "subscription_id": { "type": "string", "pattern": "^sub_[a-f0-9]{32}$" }, "website_ids": { "type": "array", "items": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" }, "minItems": 1, "maxItems": 50, "uniqueItems": true }, "event_types": { "type": "array", "items": { "type": "string", "enum": [ "conversation.changed", "conversation.removed", "conversation.snapshot", "conversation.gap", "conversation.heartbeat", "visitor.changed", "visitor.removed", "visitor.snapshot", "visitor.gap", "visitor.heartbeat", "operator.changed", "operator.removed", "operator.snapshot", "operator.gap", "operator.heartbeat", "queue.changed", "queue.removed", "queue.snapshot", "queue.gap", "queue.heartbeat", "website.changed", "website.removed", "website.snapshot", "website.gap", "website.heartbeat", "privacy.changed", "privacy.removed", "privacy.snapshot", "privacy.gap", "privacy.heartbeat", "capture.changed", "capture.removed", "capture.snapshot", "capture.gap", "capture.heartbeat" ] }, "description": "Concrete event types; family wildcards are expanded." }, "revision": { "type": "integer", "minimum": 1, "description": "Send as If-Match: \"\" to replace or delete." }, "status": { "const": "active" }, "payload_mode": { "const": "thin" }, "delivery": { "type": "object", "additionalProperties": false, "required": [ "mode" ], "properties": { "mode": { "const": "pull" } } }, "created_at": { "type": "integer", "description": "Unix seconds." }, "updated_at": { "type": "integer", "description": "Unix seconds." } } }, "maxItems": 20 } } } } } }, "400": { "description": "Malformed, duplicate, unsupported input or invalid cursor signature." }, "401": { "description": "Expired, revoked or changed credential authority." }, "404": { "description": "Subscription or website not granted; restriction filters and human consent credentials are unavailable for this feed." }, "409": { "description": "Changed subscription revision, concurrent mutation, inventory limit, or replay_expired requiring reconciliation." }, "429": { "description": "Application request quota exceeded." }, "503": { "description": "Event family held, corrupt subscription or unavailable journal/control observations." } }, "tags": [ "Event subscriptions" ], "summary": "List subscriptions" }, "post": { "operationId": "subscription_create", "description": "Create a thin pull subscription; maximum20 per installation. This does not start webhooks or socket connections. An authenticated app socket can separately attach a reader to this same thin pull subscription. With an Idempotency-Key, the same input and effective authority reuse the original result for 24h. Changed input conflicts; changed/deleted targets and expired access withhold saved results. Without a key each request is a new effect. After 24h a key can start a new effect; reconcile before retrying beyond the window.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[\\x21-\\x7e]{1,128}$" } } ], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "website_read", "event_read" ] } ], "x-required-scopes": [ "website_read", "event_read" ], "x-required-data-access": [], "x-restriction-dimensions": [], "x-native-command": false, "x-idempotency-window-seconds": 86400, "responses": { "200": { "description": "Current installation-authorized thin metadata. Cursors contain independent per-website positions; no total order is promised.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "subscription", "cursor" ], "properties": { "subscription": { "type": "object", "additionalProperties": false, "required": [ "subscription_id", "website_ids", "event_types", "revision", "status", "payload_mode", "delivery", "created_at", "updated_at" ], "properties": { "subscription_id": { "type": "string", "pattern": "^sub_[a-f0-9]{32}$" }, "website_ids": { "type": "array", "items": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" }, "minItems": 1, "maxItems": 50, "uniqueItems": true }, "event_types": { "type": "array", "items": { "type": "string", "enum": [ "conversation.changed", "conversation.removed", "conversation.snapshot", "conversation.gap", "conversation.heartbeat", "visitor.changed", "visitor.removed", "visitor.snapshot", "visitor.gap", "visitor.heartbeat", "operator.changed", "operator.removed", "operator.snapshot", "operator.gap", "operator.heartbeat", "queue.changed", "queue.removed", "queue.snapshot", "queue.gap", "queue.heartbeat", "website.changed", "website.removed", "website.snapshot", "website.gap", "website.heartbeat", "privacy.changed", "privacy.removed", "privacy.snapshot", "privacy.gap", "privacy.heartbeat", "capture.changed", "capture.removed", "capture.snapshot", "capture.gap", "capture.heartbeat" ] }, "description": "Concrete event types; family wildcards are expanded." }, "revision": { "type": "integer", "minimum": 1, "description": "Send as If-Match: \"\" to replace or delete." }, "status": { "const": "active" }, "payload_mode": { "const": "thin" }, "delivery": { "type": "object", "additionalProperties": false, "required": [ "mode" ], "properties": { "mode": { "const": "pull" } } }, "created_at": { "type": "integer", "description": "Unix seconds." }, "updated_at": { "type": "integer", "description": "Unix seconds." } } }, "cursor": { "type": "string", "description": "Opaque signed cursor. Pass it unchanged as after on the next events request." } } } } } }, "201": { "description": "Subscription, revision1 and HMAC-authenticated initial cursor.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "subscription", "cursor" ], "properties": { "subscription": { "type": "object", "additionalProperties": false, "required": [ "subscription_id", "website_ids", "event_types", "revision", "status", "payload_mode", "delivery", "created_at", "updated_at" ], "properties": { "subscription_id": { "type": "string", "pattern": "^sub_[a-f0-9]{32}$" }, "website_ids": { "type": "array", "items": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" }, "minItems": 1, "maxItems": 50, "uniqueItems": true }, "event_types": { "type": "array", "items": { "type": "string", "enum": [ "conversation.changed", "conversation.removed", "conversation.snapshot", "conversation.gap", "conversation.heartbeat", "visitor.changed", "visitor.removed", "visitor.snapshot", "visitor.gap", "visitor.heartbeat", "operator.changed", "operator.removed", "operator.snapshot", "operator.gap", "operator.heartbeat", "queue.changed", "queue.removed", "queue.snapshot", "queue.gap", "queue.heartbeat", "website.changed", "website.removed", "website.snapshot", "website.gap", "website.heartbeat", "privacy.changed", "privacy.removed", "privacy.snapshot", "privacy.gap", "privacy.heartbeat", "capture.changed", "capture.removed", "capture.snapshot", "capture.gap", "capture.heartbeat" ] }, "description": "Concrete event types; family wildcards are expanded." }, "revision": { "type": "integer", "minimum": 1, "description": "Send as If-Match: \"\" to replace or delete." }, "status": { "const": "active" }, "payload_mode": { "const": "thin" }, "delivery": { "type": "object", "additionalProperties": false, "required": [ "mode" ], "properties": { "mode": { "const": "pull" } } }, "created_at": { "type": "integer", "description": "Unix seconds." }, "updated_at": { "type": "integer", "description": "Unix seconds." } } }, "cursor": { "type": "string", "description": "Opaque signed cursor. Pass it unchanged as after on the next events request." } } } } } }, "400": { "description": "Malformed, duplicate, unsupported input or invalid cursor signature." }, "401": { "description": "Expired, revoked or changed credential authority." }, "404": { "description": "Subscription or website not granted; restriction filters and human consent credentials are unavailable for this feed." }, "409": { "description": "Changed subscription revision, concurrent mutation, inventory limit, or replay_expired requiring reconciliation." }, "422": { "description": "Full payloads or other delivery modes are unavailable." }, "429": { "description": "Application request quota exceeded." }, "503": { "description": "Event family held, corrupt subscription or unavailable journal/control observations." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "website_ids", "event_types", "payload_mode", "delivery", "start" ], "properties": { "website_ids": { "type": "array", "minItems": 1, "maxItems": 50, "uniqueItems": true, "items": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" } }, "event_types": { "type": "array", "minItems": 1, "maxItems": 35, "uniqueItems": true, "items": { "type": "string", "enum": [ "conversation.changed", "conversation.removed", "conversation.snapshot", "conversation.gap", "conversation.heartbeat", "visitor.changed", "visitor.removed", "visitor.snapshot", "visitor.gap", "visitor.heartbeat", "operator.changed", "operator.removed", "operator.snapshot", "operator.gap", "operator.heartbeat", "queue.changed", "queue.removed", "queue.snapshot", "queue.gap", "queue.heartbeat", "website.changed", "website.removed", "website.snapshot", "website.gap", "website.heartbeat", "privacy.changed", "privacy.removed", "privacy.snapshot", "privacy.gap", "privacy.heartbeat", "capture.changed", "capture.removed", "capture.snapshot", "capture.gap", "capture.heartbeat", "conversation.*", "visitor.*", "operator.*", "queue.*", "website.*", "privacy.*", "capture.*" ] } }, "payload_mode": { "type": "string", "const": "thin" }, "delivery": { "type": "object", "additionalProperties": false, "required": [ "mode" ], "properties": { "mode": { "const": "pull" } } }, "start": { "type": "string", "enum": [ "beginning", "retained" ], "description": "beginning starts at cursor zero and reports any retention gap. retained explicitly starts immediately before the oldest retained receipt; reconcile current REST resources before resetting after an expired cursor." } } } } } }, "tags": [ "Event subscriptions" ], "summary": "Create a subscription" } }, "/api/v1/subscriptions/{subscription_id}": { "get": { "operationId": "subscription_get", "description": "Read this installation subscription. Signing keys are never disclosed.", "parameters": [ { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^sub_[a-f0-9]{32}$" } } ], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "website_read", "event_read" ] } ], "x-required-scopes": [ "website_read", "event_read" ], "x-required-data-access": [], "x-restriction-dimensions": [], "x-native-command": false, "responses": { "200": { "description": "Current installation-authorized thin metadata. Cursors contain independent per-website positions; no total order is promised.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "subscription" ], "properties": { "subscription": { "type": "object", "additionalProperties": false, "required": [ "subscription_id", "website_ids", "event_types", "revision", "status", "payload_mode", "delivery", "created_at", "updated_at" ], "properties": { "subscription_id": { "type": "string", "pattern": "^sub_[a-f0-9]{32}$" }, "website_ids": { "type": "array", "items": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" }, "minItems": 1, "maxItems": 50, "uniqueItems": true }, "event_types": { "type": "array", "items": { "type": "string", "enum": [ "conversation.changed", "conversation.removed", "conversation.snapshot", "conversation.gap", "conversation.heartbeat", "visitor.changed", "visitor.removed", "visitor.snapshot", "visitor.gap", "visitor.heartbeat", "operator.changed", "operator.removed", "operator.snapshot", "operator.gap", "operator.heartbeat", "queue.changed", "queue.removed", "queue.snapshot", "queue.gap", "queue.heartbeat", "website.changed", "website.removed", "website.snapshot", "website.gap", "website.heartbeat", "privacy.changed", "privacy.removed", "privacy.snapshot", "privacy.gap", "privacy.heartbeat", "capture.changed", "capture.removed", "capture.snapshot", "capture.gap", "capture.heartbeat" ] }, "description": "Concrete event types; family wildcards are expanded." }, "revision": { "type": "integer", "minimum": 1, "description": "Send as If-Match: \"\" to replace or delete." }, "status": { "const": "active" }, "payload_mode": { "const": "thin" }, "delivery": { "type": "object", "additionalProperties": false, "required": [ "mode" ], "properties": { "mode": { "const": "pull" } } }, "created_at": { "type": "integer", "description": "Unix seconds." }, "updated_at": { "type": "integer", "description": "Unix seconds." } } } } } } } }, "400": { "description": "Malformed, duplicate, unsupported input or invalid cursor signature." }, "401": { "description": "Expired, revoked or changed credential authority." }, "404": { "description": "Subscription or website not granted; restriction filters and human consent credentials are unavailable for this feed." }, "409": { "description": "Changed subscription revision, concurrent mutation, inventory limit, or replay_expired requiring reconciliation." }, "429": { "description": "Application request quota exceeded." }, "503": { "description": "Event family held, corrupt subscription or unavailable journal/control observations." } }, "tags": [ "Event subscriptions" ], "summary": "Get a subscription" }, "patch": { "operationId": "subscription_replace", "description": "Replace the complete website/type definition with a matching If-Match revision and explicit new boundary. Old cursors return subscription_revision_changed. With an Idempotency-Key, the same input and effective authority reuse the original result for 24h. Changed input conflicts; changed/deleted targets and expired access withhold saved results. Without a key each request is a new effect. After 24h a key can start a new effect; reconcile before retrying beyond the window.", "parameters": [ { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^sub_[a-f0-9]{32}$" } }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[\\x21-\\x7e]{1,128}$" } } ], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "website_read", "event_read" ] } ], "x-required-scopes": [ "website_read", "event_read" ], "x-required-data-access": [], "x-restriction-dimensions": [], "x-native-command": false, "x-idempotency-window-seconds": 86400, "responses": { "200": { "description": "Current installation-authorized thin metadata. Cursors contain independent per-website positions; no total order is promised.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "subscription", "cursor" ], "properties": { "subscription": { "type": "object", "additionalProperties": false, "required": [ "subscription_id", "website_ids", "event_types", "revision", "status", "payload_mode", "delivery", "created_at", "updated_at" ], "properties": { "subscription_id": { "type": "string", "pattern": "^sub_[a-f0-9]{32}$" }, "website_ids": { "type": "array", "items": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" }, "minItems": 1, "maxItems": 50, "uniqueItems": true }, "event_types": { "type": "array", "items": { "type": "string", "enum": [ "conversation.changed", "conversation.removed", "conversation.snapshot", "conversation.gap", "conversation.heartbeat", "visitor.changed", "visitor.removed", "visitor.snapshot", "visitor.gap", "visitor.heartbeat", "operator.changed", "operator.removed", "operator.snapshot", "operator.gap", "operator.heartbeat", "queue.changed", "queue.removed", "queue.snapshot", "queue.gap", "queue.heartbeat", "website.changed", "website.removed", "website.snapshot", "website.gap", "website.heartbeat", "privacy.changed", "privacy.removed", "privacy.snapshot", "privacy.gap", "privacy.heartbeat", "capture.changed", "capture.removed", "capture.snapshot", "capture.gap", "capture.heartbeat" ] }, "description": "Concrete event types; family wildcards are expanded." }, "revision": { "type": "integer", "minimum": 1, "description": "Send as If-Match: \"\" to replace or delete." }, "status": { "const": "active" }, "payload_mode": { "const": "thin" }, "delivery": { "type": "object", "additionalProperties": false, "required": [ "mode" ], "properties": { "mode": { "const": "pull" } } }, "created_at": { "type": "integer", "description": "Unix seconds." }, "updated_at": { "type": "integer", "description": "Unix seconds." } } }, "cursor": { "type": "string", "description": "Opaque signed cursor. Pass it unchanged as after on the next events request." } } } } } }, "400": { "description": "Malformed, duplicate, unsupported input or invalid cursor signature." }, "401": { "description": "Expired, revoked or changed credential authority." }, "404": { "description": "Subscription or website not granted; restriction filters and human consent credentials are unavailable for this feed." }, "409": { "description": "Changed subscription revision, concurrent mutation, inventory limit, or replay_expired requiring reconciliation." }, "429": { "description": "Application request quota exceeded." }, "503": { "description": "Event family held, corrupt subscription or unavailable journal/control observations." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "website_ids", "event_types", "payload_mode", "delivery", "start" ], "properties": { "website_ids": { "type": "array", "minItems": 1, "maxItems": 50, "uniqueItems": true, "items": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" } }, "event_types": { "type": "array", "minItems": 1, "maxItems": 35, "uniqueItems": true, "items": { "type": "string", "enum": [ "conversation.changed", "conversation.removed", "conversation.snapshot", "conversation.gap", "conversation.heartbeat", "visitor.changed", "visitor.removed", "visitor.snapshot", "visitor.gap", "visitor.heartbeat", "operator.changed", "operator.removed", "operator.snapshot", "operator.gap", "operator.heartbeat", "queue.changed", "queue.removed", "queue.snapshot", "queue.gap", "queue.heartbeat", "website.changed", "website.removed", "website.snapshot", "website.gap", "website.heartbeat", "privacy.changed", "privacy.removed", "privacy.snapshot", "privacy.gap", "privacy.heartbeat", "capture.changed", "capture.removed", "capture.snapshot", "capture.gap", "capture.heartbeat", "conversation.*", "visitor.*", "operator.*", "queue.*", "website.*", "privacy.*", "capture.*" ] } }, "payload_mode": { "type": "string", "const": "thin" }, "delivery": { "type": "object", "additionalProperties": false, "required": [ "mode" ], "properties": { "mode": { "const": "pull" } } }, "start": { "type": "string", "enum": [ "beginning", "retained" ], "description": "beginning starts at cursor zero and reports any retention gap. retained explicitly starts immediately before the oldest retained receipt; reconcile current REST resources before resetting after an expired cursor." } } } } } }, "tags": [ "Event subscriptions" ], "summary": "Replace a subscription" }, "delete": { "operationId": "subscription_delete", "description": "Delete this installation subscription at its matching revision. Existing cursors become unavailable. With an Idempotency-Key, the same input and effective authority reuse the original result for 24h. Changed input conflicts; changed/deleted targets and expired access withhold saved results. Without a key each request is a new effect. After 24h a key can start a new effect; reconcile before retrying beyond the window.", "parameters": [ { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^sub_[a-f0-9]{32}$" } }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[\\x21-\\x7e]{1,128}$" } } ], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "website_read", "event_read" ] } ], "x-required-scopes": [ "website_read", "event_read" ], "x-required-data-access": [], "x-restriction-dimensions": [], "x-native-command": false, "x-idempotency-window-seconds": 86400, "responses": { "200": { "description": "Current installation-authorized thin metadata. Cursors contain independent per-website positions; no total order is promised.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "deleted" ], "properties": { "deleted": { "const": true } } } } } }, "400": { "description": "Malformed, duplicate, unsupported input or invalid cursor signature." }, "401": { "description": "Expired, revoked or changed credential authority." }, "404": { "description": "Subscription or website not granted; restriction filters and human consent credentials are unavailable for this feed." }, "409": { "description": "Changed subscription revision, concurrent mutation, inventory limit, or replay_expired requiring reconciliation." }, "429": { "description": "Application request quota exceeded." }, "503": { "description": "Event family held, corrupt subscription or unavailable journal/control observations." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "tags": [ "Event subscriptions" ], "summary": "Delete a subscription" } }, "/api/v1/events": { "get": { "operationId": "events_pull", "description": "Pull up to100 payload-free journal receipts, scanning at most100 stored records across at most50 websites. Filtering may produce an empty page with has_more=true; continue with next_cursor. Pauses withhold the whole page and consume no cursor. Detailed message/AI events and resource IDs are not captured by this thin coarse feed.", "parameters": [ { "name": "subscription_id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^sub_[a-f0-9]{32}$" } }, { "name": "after", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 12000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "website_read", "event_read" ] } ], "x-required-scopes": [ "website_read", "event_read" ], "x-required-data-access": [], "x-restriction-dimensions": [], "x-native-command": false, "responses": { "200": { "description": "Current installation-authorized thin metadata. Cursors contain independent per-website positions; no total order is promised.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "subscription_id", "revision", "events", "next_cursor", "has_more", "retention", "coverage" ], "properties": { "subscription_id": { "type": "string", "pattern": "^sub_[a-f0-9]{32}$" }, "revision": { "type": "integer", "minimum": 1 }, "events": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "event_id", "event_type", "website_id", "cursor", "occurred_at", "recorded_at" ], "properties": { "event_id": { "type": "string", "pattern": "^evt_[a-f0-9]{64}$", "description": "Deduplicate on this value." }, "event_type": { "type": "string", "enum": [ "conversation.changed", "conversation.removed", "conversation.snapshot", "conversation.gap", "conversation.heartbeat", "visitor.changed", "visitor.removed", "visitor.snapshot", "visitor.gap", "visitor.heartbeat", "operator.changed", "operator.removed", "operator.snapshot", "operator.gap", "operator.heartbeat", "queue.changed", "queue.removed", "queue.snapshot", "queue.gap", "queue.heartbeat", "website.changed", "website.removed", "website.snapshot", "website.gap", "website.heartbeat", "privacy.changed", "privacy.removed", "privacy.snapshot", "privacy.gap", "privacy.heartbeat", "capture.changed", "capture.removed", "capture.snapshot", "capture.gap", "capture.heartbeat" ] }, "website_id": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" }, "cursor": { "type": "integer", "minimum": 0, "description": "Position within this website journal." }, "occurred_at": { "type": "integer", "description": "Unix milliseconds." }, "recorded_at": { "type": "integer", "description": "Unix milliseconds." } } }, "maxItems": 100 }, "next_cursor": { "type": "string", "description": "Opaque signed cursor. Pass it unchanged as after on the next events request." }, "has_more": { "type": "boolean", "description": "Keep pulling while true, even when events is empty." }, "retention": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "website_id", "retained_from", "accepted_cursor" ], "properties": { "website_id": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" }, "retained_from": { "type": "integer" }, "accepted_cursor": { "type": "integer" } } } }, "coverage": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "website_id", "coverage" ], "properties": { "website_id": { "type": "string", "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" }, "coverage": { "type": "string", "enum": [ "stored_events_only", "unreported" ] } } } } } } } } }, "400": { "description": "Malformed, duplicate, unsupported input or invalid cursor signature." }, "401": { "description": "Expired, revoked or changed credential authority." }, "404": { "description": "Subscription or website not granted; restriction filters and human consent credentials are unavailable for this feed." }, "409": { "description": "Changed subscription revision, concurrent mutation, inventory limit, or replay_expired requiring reconciliation." }, "429": { "description": "Application request quota exceeded." }, "503": { "description": "Event family held, corrupt subscription or unavailable journal/control observations." } }, "tags": [ "Event subscriptions" ], "summary": "Pull events" } }, "/api/v1/realtime/sessions": { "post": { "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "website_read", "event_read" ] } ], "x-required-scopes": [ "website_read", "event_read" ], "x-required-data-access": [], "responses": { "201": { "description": "Origin-bound single-use ticket. Authenticate the socket first frame within5s. Idle reconnect window2min, authority recheck15s.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "session_id", "ticket", "expires_at" ], "properties": { "session_id": { "type": "string", "pattern": "^app_[a-f0-9]{64}_[a-f0-9]{32}$" }, "ticket": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$", "description": "Single-use first-frame secret. Never put it in the URL or logs." }, "expires_at": { "type": "integer", "minimum": 1, "description": "Unix seconds; at most30s and never after the original credential deadline." } } } } } }, "400": { "description": "Closed request body or parameters are invalid." }, "401": { "description": "Original REST credential or current authority is invalid." }, "403": { "description": "Origin rejected." }, "404": { "description": "Session is absent or not owned by the same exact credential/grant and origin." }, "409": { "description": "Installation session or pending socket capacity reached." }, "429": { "description": "App/ingress quota exceeded; observe Retry-After." }, "503": { "description": "Required service/authority/storage is unavailable." } }, "operationId": "realtime_session_create", "description": "Create an app-only socket session, bounded to20 per installation. No human cookie, native operator or richer subscription projection. Changed authorization requires a new session.", "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Exact canonical HTTPS origin bound to this session. Local loopback HTTP is allowed only in the local environment. Browser REST CORS is restricted to configured UI origins.", "schema": { "type": "string", "maxLength": 2048 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "website_ids" ], "properties": { "website_ids": { "type": "array", "minItems": 1, "maxItems": 50, "uniqueItems": true, "items": { "type": "string", "maxLength": 100, "pattern": "^web_[0-9]{1,20}_[1-9][0-9]{0,18}$" } } } } } } }, "tags": [ "Realtime" ], "summary": "Create a realtime session" } }, "/api/v1/realtime/sessions/{session_id}/tickets": { "post": { "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "website_read", "event_read" ] } ], "x-required-scopes": [ "website_read", "event_read" ], "x-required-data-access": [], "responses": { "200": { "description": "Origin-bound single-use ticket. Authenticate the socket first frame within5s. Idle reconnect window2min, authority recheck15s.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "session_id", "ticket", "expires_at" ], "properties": { "session_id": { "type": "string", "pattern": "^app_[a-f0-9]{64}_[a-f0-9]{32}$" }, "ticket": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$", "description": "Single-use first-frame secret. Never put it in the URL or logs." }, "expires_at": { "type": "integer", "minimum": 1, "description": "Unix seconds; at most30s and never after the original credential deadline." } } } } } }, "400": { "description": "Closed request body or parameters are invalid." }, "401": { "description": "Original REST credential or current authority is invalid." }, "403": { "description": "Origin rejected." }, "404": { "description": "Session is absent or not owned by the same exact credential/grant and origin." }, "409": { "description": "Installation session or pending socket capacity reached." }, "429": { "description": "App/ingress quota exceeded; observe Retry-After." }, "503": { "description": "Required service/authority/storage is unavailable." } }, "operationId": "realtime_session_ticket", "description": "Replace the unused ticket using the exact original credential/grant and Origin. A valid reconnect replaces the prior authenticated socket epoch.", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^app_[a-f0-9]{64}_[a-f0-9]{32}$" } }, { "name": "Origin", "in": "header", "required": true, "description": "Exact canonical HTTPS origin bound to this session. Local loopback HTTP is allowed only in the local environment. Browser REST CORS is restricted to configured UI origins.", "schema": { "type": "string", "maxLength": 2048 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "tags": [ "Realtime" ], "summary": "Issue a reconnect ticket" } }, "/api/v1/realtime/sessions/{session_id}": { "delete": { "security": [ { "installation_token": [] }, { "oauth_client_credentials": [ "website_read", "event_read" ] } ], "x-required-scopes": [ "website_read", "event_read" ], "x-required-data-access": [], "responses": { "204": { "description": "Session closed." }, "400": { "description": "Closed request body or parameters are invalid." }, "401": { "description": "Original REST credential or current authority is invalid." }, "403": { "description": "Origin rejected." }, "404": { "description": "Session is absent or not owned by the same exact credential/grant and origin." }, "409": { "description": "Installation session or pending socket capacity reached." }, "429": { "description": "App/ingress quota exceeded; observe Retry-After." }, "503": { "description": "Required service/authority/storage is unavailable." } }, "operationId": "realtime_session_delete", "description": "Close this app session and release its capacity. No body.", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^app_[a-f0-9]{64}_[a-f0-9]{32}$" } }, { "name": "Origin", "in": "header", "required": true, "description": "Exact canonical HTTPS origin bound to this session. Local loopback HTTP is allowed only in the local environment. Browser REST CORS is restricted to configured UI origins.", "schema": { "type": "string", "maxLength": 2048 } } ], "tags": [ "Realtime" ], "summary": "Close a realtime session" } }, "/api/v1/realtime/sessions/{session_id}/socket": { "get": { "security": [], "x-required-scopes": [ "website_read", "event_read" ], "x-required-data-access": [], "responses": { "101": { "description": "WebSocket accepted; first-frame ticket authentication is still required." }, "400": { "description": "Closed request body or parameters are invalid." }, "401": { "description": "Original REST credential or current authority is invalid." }, "403": { "description": "Origin rejected." }, "404": { "description": "Session is absent or not owned by the same exact credential/grant and origin." }, "409": { "description": "Installation session or pending socket capacity reached." }, "426": { "description": "WebSocket upgrade required." }, "429": { "description": "App/ingress quota exceeded; observe Retry-After." }, "503": { "description": "Required service/authority/storage is unavailable." } }, "operationId": "realtime_session_socket", "description": "Ticket-authenticated WebSocket upgrade. No query/bearer/cookie. First text frame is {type:auth,ticket} within5s; auth.ok confirms authentication. Supports ping/pong and up to20 owned thin pull readers. subscription.open {subscription_id,cursor} emits subscription.page with at most25 coarse receipts; subscription.ack must match its next_cursor exactly within30s of emission; subscription.close removes the reader. Reconnect replays from the last acknowledged cursor. Pauses/quota withhold pages and retry; retention gaps require reconciliation. Poll15s, one pending page per reader,64KiB frames.", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^app_[a-f0-9]{64}_[a-f0-9]{32}$" } }, { "name": "Origin", "in": "header", "required": true, "description": "Exact canonical HTTPS origin bound to this session. Local loopback HTTP is allowed only in the local environment. Browser REST CORS is restricted to configured UI origins.", "schema": { "type": "string", "maxLength": 2048 } }, { "name": "Upgrade", "in": "header", "required": true, "schema": { "type": "string", "const": "websocket" } } ], "tags": [ "Realtime" ], "summary": "Open the realtime socket" } }, "/api/v1/context": { "get": { "operationId": "installation_context", "description": "Read current installation context and available guide names. No native/customer read; website inventory requires website_read. No query parameters.", "parameters": [], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [] } ], "x-required-scopes": [], "x-required-data-access": [], "x-mutation": false, "responses": { "200": { "description": "Current grant metadata or permitted guidance; every subsequent action rechecks authority.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "principal", "environment", "organization_id", "app_id", "installation_id", "scopes", "website_ids", "data_access", "restrictions", "authority_expires_at", "guides" ], "properties": { "principal": { "const": "app_installation", "type": "string" }, "environment": { "type": "string" }, "organization_id": { "type": "string" }, "app_id": { "type": "string" }, "installation_id": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "website_ids": { "type": "array", "items": { "type": "string" } }, "data_access": { "type": "object", "additionalProperties": false, "required": [ "message_content", "pii", "internal_notes" ], "properties": { "message_content": { "type": "boolean" }, "pii": { "type": "boolean" }, "internal_notes": { "type": "boolean" } } }, "restrictions": { "type": "object", "additionalProperties": false, "properties": { "channel_ids": { "type": "array", "items": { "type": "string" } }, "team_ids": { "type": "array", "items": { "type": "string" } }, "subsite_ids": { "type": "array", "items": { "type": "string" } } } }, "authority_expires_at": { "type": "integer", "minimum": 1 }, "guides": { "type": "array", "items": { "type": "string", "enum": [ "overview", "investigation", "contacts", "reporting", "configuration", "agent_tasks", "event_recovery" ] } } } } } } }, "400": { "description": "Unsupported input." }, "401": { "description": "Missing, expired or changed installation authority." }, "404": { "description": "Guide unavailable under current grants." }, "429": { "description": "Shared application quota exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } } }, "tags": [ "Discovery" ], "summary": "Get installation context" } }, "/api/v1/guides/{guide}": { "get": { "operationId": "installation_guide_read", "description": "Read one guide permitted by current installation grants. Shared quotas and final current-authority checks apply. Guidance supplies no permission lease or native-read result. No query parameters.", "parameters": [ { "name": "guide", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "overview", "investigation", "contacts", "reporting", "configuration", "agent_tasks", "event_recovery" ] } } ], "security": [ { "installation_token": [] }, { "oauth_client_credentials": [] } ], "x-required-scopes": [], "x-required-data-access": [], "x-mutation": false, "responses": { "200": { "description": "Current grant metadata or permitted guidance; every subsequent action rechecks authority.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "guide", "mime_type", "content", "coverage" ], "properties": { "guide": { "type": "string", "enum": [ "overview", "investigation", "contacts", "reporting", "configuration", "agent_tasks", "event_recovery" ] }, "mime_type": { "type": "string", "const": "text/markdown" }, "content": { "type": "string", "maxLength": 65536 }, "coverage": { "type": "string", "const": "current_installation_guidance" } } } } } }, "400": { "description": "Unsupported input." }, "401": { "description": "Missing, expired or changed installation authority." }, "404": { "description": "Guide unavailable under current grants." }, "429": { "description": "Shared application quota exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } } }, "tags": [ "Discovery" ], "summary": "Read a guide" } } } }