{ "openapi": "3.1.0", "info": { "title": "Laleo Chat API", "version": "2026.05.20.35", "description": "API for Laleo Chat widgets, live website visitors, visitor analytics, chat history, call history, account usage, signed webhooks, CRM automation, and MCP-compatible agent tooling." }, "servers": [ { "url": "https://laleo.chat" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Widgets", "description": "Website widgets and install snippets" }, { "name": "Visitors", "description": "Live visitor presence and activity" }, { "name": "Analytics", "description": "Visitor intelligence, pages, IPs, browsers, operating systems, messages, and calls" }, { "name": "Calls", "description": "Browser, SIP, PSTN, and inbound call records" }, { "name": "Contacts", "description": "Lead records, visitor-session identity reconciliation, and CRM-ready contact timelines" }, { "name": "Webhooks", "description": "Signed outbound event delivery" }, { "name": "Account", "description": "Usage, plan, limits, and PSTN minutes" }, { "name": "MCP", "description": "MCP-compatible JSON-RPC tool endpoint" }, { "name": "WordPress", "description": "WordPress plugin OTP setup, site registration, and update metadata" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "Laleo PAT" } }, "schemas": { "Widget": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "websiteUrl": { "type": "string", "format": "uri" }, "enabledChat": { "type": "boolean" }, "enabledVoice": { "type": "boolean" }, "enabledVideo": { "type": "boolean" }, "callRoutingMode": { "type": "string", "enum": [ "webrtc", "service_queue", "sip_peer", "sip_direct", "pstn" ] }, "callConnectBehavior": { "type": "string", "enum": [ "auto", "confirm", "direct_bridge" ] }, "routedCallHoldMode": { "type": "string", "enum": [ "hold_music", "silent_connect" ] }, "styleTheme": { "type": "string", "enum": [ "laleo", "concierge", "minimal" ] }, "styleLayout": { "type": "string", "enum": [ "classic", "concierge", "compact" ] }, "styleSize": { "type": "string", "enum": [ "compact", "normal", "large" ] }, "stylePosition": { "type": "string", "enum": [ "bottom_right", "bottom_left" ] }, "styleAccentColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "styleHeaderColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "styleSurfaceColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "styleTextColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "launcherLabel": { "type": "string" }, "headerTitle": { "type": "string" }, "headerSubtitle": { "type": "string" }, "connectedVisitors": { "type": "integer" }, "totalVisitors": { "type": "integer" }, "snippet": { "type": "string" } }, "additionalProperties": true }, "Visitor": { "type": "object", "properties": { "visitorId": { "type": "string" }, "temporaryExtension": { "type": "string" }, "channelNumber": { "type": "string" }, "currentUrl": { "type": "string" }, "pageTitle": { "type": "string" }, "referrer": { "type": "string" }, "ip": { "type": "string" }, "browserName": { "type": "string" }, "osName": { "type": "string" }, "deviceType": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true }, "firstSeenAt": { "type": "string", "format": "date-time" }, "lastSeenAt": { "type": "string", "format": "date-time" }, "lastActivityAt": { "type": "string", "format": "date-time", "description": "Last counted visitor action such as arrival, pageview, scroll, or click." }, "currentSessionStartedAt": { "type": "string", "format": "date-time", "description": "Start time for the current browser-tab session." }, "currentPageStartedAt": { "type": "string", "format": "date-time", "description": "When the visitor arrived on the current page URL." }, "lastInteractionAt": { "type": "string", "format": "date-time", "description": "Last counted site interaction, not a heartbeat." }, "sessionEventCount": { "type": "integer", "description": "Counted arrival, pageview, click, scroll, input, and change events for the current browser session." } }, "additionalProperties": true }, "Webhook": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "widgetIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "active": { "type": "boolean" }, "secretLastFour": { "type": "string" }, "secret": { "type": "string", "description": "Only returned on create or rotate." } }, "additionalProperties": true }, "Contact": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "displayName": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "hintName": { "type": "string" }, "companyName": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "visitorSessionCount": { "type": "integer" }, "firstContactedAt": { "type": "string", "format": "date-time" }, "lastContactedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "ContactInput": { "type": "object", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "hintName": { "type": "string" }, "companyName": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "lead", "customer", "archived" ] }, "email": { "type": "string" }, "phone": { "type": "string" } }, "additionalProperties": false }, "WebhookInput": { "type": "object", "required": [ "url" ], "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "visitor.connected", "chat.message.created", "call.requested", "call.delivery_started", "call.delivery_failed", "call.unavailable", "call.answered", "call.ended", "call.missed", "callback.submitted", "usage.updated", "webhook.test" ] } }, "widgetIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "active": { "type": "boolean" } }, "additionalProperties": false }, "MessageInput": { "type": "object", "required": [ "visitorId", "body" ], "properties": { "visitorId": { "type": "string" }, "body": { "type": "string", "maxLength": 4000 } }, "additionalProperties": false }, "ConversationLinkInput": { "type": "object", "properties": { "callId": { "type": "string", "description": "Optional call ID to focus if the visitor has an active call." }, "autoCall": { "type": "string", "enum": [ "voice", "video" ], "description": "Optional hint for the full Laleo console to begin an operator-originated browser call." } }, "additionalProperties": false }, "CallRecording": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "widgetId": { "type": "string", "format": "uuid" }, "visitorId": { "type": "string" }, "callId": { "type": "string" }, "source": { "type": "string", "enum": [ "api", "browser", "dashboard", "freeswitch", "sip", "pstn", "worker" ] }, "mediaKind": { "type": "string", "enum": [ "audio" ] }, "status": { "type": "string", "enum": [ "uploading", "uploaded", "processing", "ready", "queued", "waiting_model", "failed", "deleted" ] }, "mimeType": { "type": "string" }, "totalBytes": { "type": "integer" }, "durationSeconds": { "type": "integer" }, "transcriptStatus": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "finalizedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": true } } }, "paths": { "/api/v1/widgets": { "get": { "tags": [ "Widgets" ], "operationId": "listWidgets", "summary": "List accessible widgets", "description": "Requires widgets:read scope. Returns widget configuration, permissions, install snippets, and live visitor counts.", "responses": { "200": { "description": "Widgets", "content": { "application/json": { "schema": { "type": "object", "properties": { "widgets": { "type": "array", "items": { "$ref": "#/components/schemas/Widget" } } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/wordpress/auth/request-otp": { "post": { "tags": [ "WordPress" ], "operationId": "requestWordPressPluginOtp", "summary": "Send an email OTP for WordPress plugin setup", "description": "Used by the Laleo WordPress plugin. Creates a free Laleo user if needed, then sends an OTP to connect the WordPress site.", "x-openai-isConsequential": true, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "siteUrl" ], "properties": { "email": { "type": "string", "format": "email" }, "siteName": { "type": "string" }, "siteUrl": { "type": "string", "format": "uri" }, "wpVersion": { "type": "string" }, "pluginVersion": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "OTP sent", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid email", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/wordpress/auth/verify": { "post": { "tags": [ "WordPress" ], "operationId": "verifyWordPressPluginOtp", "summary": "Verify a WordPress plugin OTP and connect the site", "description": "Returns a revocable WordPress plugin PAT. If the account already has widgets, returns candidate widgets plus a suggested domain match so the plugin can select an existing widget or create a new one. If no widgets exist yet, creates the first widget for the WordPress site.", "x-openai-isConsequential": true, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "code", "siteUrl" ], "properties": { "email": { "type": "string", "format": "email" }, "code": { "type": "string" }, "siteName": { "type": "string" }, "siteUrl": { "type": "string", "format": "uri" }, "wpVersion": { "type": "string" }, "pluginVersion": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Connected WordPress plugin", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Invalid or expired OTP", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/wordpress-plugin/update.json": { "get": { "tags": [ "WordPress" ], "operationId": "getWordPressPluginUpdateInfo", "summary": "Get WordPress ZIP update metadata", "security": [], "responses": { "200": { "description": "Plugin update metadata", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/widgets/{id}/live-visitors": { "get": { "tags": [ "Visitors" ], "operationId": "listLiveVisitors", "summary": "List online visitors for a widget", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Widget UUID" } ], "responses": { "200": { "description": "Live visitors", "content": { "application/json": { "schema": { "type": "object", "properties": { "visitors": { "type": "array", "items": { "$ref": "#/components/schemas/Visitor" } } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/widgets/{id}/visitors": { "get": { "tags": [ "Visitors" ], "operationId": "listVisitors", "summary": "List recent visitors for a widget", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Widget UUID" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "maximum": 500 } } ], "responses": { "200": { "description": "Visitors", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/widgets/{id}/visitors/{visitorId}": { "get": { "tags": [ "Visitors" ], "operationId": "getVisitor", "summary": "Get one visitor session", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Widget UUID" }, { "name": "visitorId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Visitor", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/widgets/{id}/visitors/{visitorId}/contact": { "get": { "tags": [ "Contacts" ], "operationId": "getVisitorContact", "summary": "Get the contact attached to a visitor", "description": "Returns the visitor's current lead/contact link plus identity hints gathered from callback forms and site-passed visitor context.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Widget UUID" }, { "name": "visitorId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Visitor contact", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "post": { "tags": [ "Contacts" ], "operationId": "tagVisitorContact", "summary": "Attach or create a contact for a visitor", "description": "Operators with widget conversation access can attach a visitor to an existing contactId, or provide name/email/phone/company fields to create or reconcile a contact from the live session.", "x-openai-isConsequential": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Widget UUID" }, { "name": "visitorId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contactId": { "type": "string", "format": "uuid" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "hintName": { "type": "string" }, "companyName": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" } } } } } }, "responses": { "201": { "description": "Attached visitor contact", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/widgets/{id}/activity": { "get": { "tags": [ "Analytics" ], "operationId": "listWidgetActivity", "summary": "List visitor activity events", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Widget UUID" }, { "name": "visitorId", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "maximum": 500 } } ], "responses": { "200": { "description": "Activity events", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/widgets/{id}/analytics": { "get": { "tags": [ "Analytics" ], "operationId": "getWidgetAnalytics", "summary": "Get visitor intelligence for a widget", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Widget UUID" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 80, "maximum": 300 } }, { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "ip", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Analytics", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/widgets/{id}/campaign-aliases": { "get": { "tags": [ "Analytics" ], "operationId": "listCampaignAliases", "summary": "List human-readable campaign tag aliases", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Widget UUID" } ], "responses": { "200": { "description": "Campaign aliases", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "patch": { "tags": [ "Analytics" ], "operationId": "setCampaignAliases", "summary": "Create, update, or clear campaign tag aliases", "description": "Requires widgets:write scope and widget management permission. Send an empty alias to remove that alias.", "x-openai-isConsequential": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Widget UUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "aliases": { "type": "array", "items": { "type": "object", "required": [ "tagKey", "tagValue", "alias" ], "properties": { "tagKey": { "type": "string" }, "tagValue": { "type": "string" }, "alias": { "type": "string" } } } } } } } } }, "responses": { "200": { "description": "Updated campaign aliases", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/widgets/{id}/calls-waiting": { "get": { "tags": [ "Calls" ], "operationId": "listCallsWaiting", "summary": "List browser and trusted SIP calls waiting for an operator", "description": "Returns visitor-originated browser calls that are still waiting or being answered, plus trusted SIP calls waiting to bridge to a live visitor.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Widget UUID" } ], "responses": { "200": { "description": "Calls waiting", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/widgets/{id}/calls": { "get": { "tags": [ "Calls" ], "operationId": "listWidgetCalls", "summary": "List browser, SIP, PSTN, and inbound call records", "description": "Returns call events plus SIP/PSTN attempts. Routed attempts include carrier RTP fields and browser ICE media fields when WebRTC getStats reporting has been observed.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Widget UUID" }, { "name": "visitorId", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "maximum": 500 } } ], "responses": { "200": { "description": "Calls", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/widgets/{id}/call-recordings": { "get": { "tags": [ "Calls" ], "operationId": "listWidgetCallRecordings", "summary": "List call recordings and transcription status", "description": "Returns audio call recordings for a widget. Recording access requires a paid account approved by Laleo admin and widget call permission.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Widget UUID" }, { "name": "visitorId", "in": "query", "schema": { "type": "string" } }, { "name": "callId", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "maximum": 500 } } ], "responses": { "200": { "description": "Call recordings", "content": { "application/json": { "schema": { "type": "object", "properties": { "recordings": { "type": "array", "items": { "$ref": "#/components/schemas/CallRecording" } } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/widgets/{id}/call-recordings/{recordingId}": { "get": { "tags": [ "Calls" ], "operationId": "getWidgetCallRecording", "summary": "Get a call recording with chunks and transcripts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Widget UUID" }, { "name": "recordingId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Call recording", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/widgets/{id}/call-recordings/{recordingId}/download": { "get": { "tags": [ "Calls" ], "operationId": "downloadWidgetCallRecording", "summary": "Download a call recording audio file", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Widget UUID" }, { "name": "recordingId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Recording audio file", "content": { "audio/mpeg": { "schema": { "type": "string", "format": "binary" } }, "audio/webm": { "schema": { "type": "string", "format": "binary" } }, "audio/wav": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/widgets/{id}/callbacks": { "get": { "tags": [ "Visitors" ], "operationId": "listVisitorCallbacks", "summary": "List visitor callback forms and voice notes", "description": "Returns missed-call contact forms and optional voice-note payloads for one visitor or the whole widget.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Widget UUID" }, { "name": "visitorId", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 80, "maximum": 200 } } ], "responses": { "200": { "description": "Callbacks", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/widgets/{id}/messages": { "get": { "tags": [ "Visitors" ], "operationId": "listWidgetMessages", "summary": "List chat messages", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Widget UUID" }, { "name": "visitorId", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 300, "maximum": 500 } } ], "responses": { "200": { "description": "Messages", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "post": { "tags": [ "Visitors" ], "operationId": "sendVisitorMessage", "summary": "Send a chat message to a visitor", "description": "Requires messages:write scope and chat permission for the widget. The message is stored and delivered immediately if the visitor is online.", "x-openai-isConsequential": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Widget UUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageInput" } } } }, "responses": { "201": { "description": "Created message", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/widgets/{id}/visitors/{visitorId}/notes": { "get": { "tags": [ "Contacts" ], "operationId": "listVisitorNotes", "summary": "List internal notes for a visitor", "description": "Returns team/private notes attached to this visitor session and reconciled contact.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Widget UUID" }, { "name": "visitorId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Visitor notes", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "post": { "tags": [ "Contacts" ], "operationId": "createVisitorNote", "summary": "Create an internal note for a visitor", "description": "Requires messages:write scope and widget conversation access. Notes are account-scoped and are never exposed to the website visitor.", "x-openai-isConsequential": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Widget UUID" }, { "name": "visitorId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "body" ], "properties": { "body": { "type": "string", "maxLength": 3000 }, "visibility": { "type": "string", "enum": [ "team", "private" ], "default": "team" }, "pinned": { "type": "boolean", "default": false } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Created note", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/widgets/{id}/visitors/{visitorId}/conversation-link": { "post": { "tags": [ "Visitors" ], "operationId": "createVisitorConversationLink", "summary": "Create a secure conversation action link", "description": "Creates a 24-hour link that signs the operator into the dashboard and opens the selected visitor conversation.", "x-openai-isConsequential": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Widget UUID" }, { "name": "visitorId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationLinkInput" } } } }, "responses": { "201": { "description": "Conversation link", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/widgets/{id}/visitors/{visitorId}/direct-navigate": { "post": { "tags": [ "Visitors" ], "operationId": "directVisitorNavigate", "summary": "Push an online visitor to a page", "description": "Requires messages:write scope and widget conversation access. The visitor must be online. Use saved site-directory entries or pass a custom URL/path.", "x-openai-isConsequential": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Widget UUID" }, { "name": "visitorId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "Absolute URL or same-site path." }, "path": { "type": "string", "description": "Optional same-site path alias." }, "title": { "type": "string", "maxLength": 120 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Navigation sent", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/widgets/{id}/site-directory": { "get": { "tags": [ "Widgets" ], "operationId": "listWidgetSiteDirectory", "summary": "List saved Direct User pages for a widget", "description": "Returns manually saved and sitemap-imported pages that operators can use to direct a visitor around the site.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Widget UUID" } ], "responses": { "200": { "description": "Site directory", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "post": { "tags": [ "Widgets" ], "operationId": "createWidgetSiteDirectoryEntry", "summary": "Create or update a Direct User page", "description": "Requires widgets:write scope and widget management permission.", "x-openai-isConsequential": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Widget UUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "title": { "type": "string", "maxLength": 120 }, "url": { "type": "string" }, "favorite": { "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Directory entry", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/widgets/{id}/site-directory/import-sitemap": { "post": { "tags": [ "Widgets" ], "operationId": "importWidgetSiteDirectoryFromSitemap", "summary": "Import Direct User pages from the widget site's sitemap", "description": "Requires widgets:write scope and widget management permission. Imports canonical sitemap URLs as favorite Direct User entries.", "x-openai-isConsequential": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Widget UUID" } ], "responses": { "200": { "description": "Imported site directory", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/widgets/{id}/site-directory/{entryId}": { "patch": { "tags": [ "Widgets" ], "operationId": "updateWidgetSiteDirectoryEntry", "summary": "Update a Direct User page", "x-openai-isConsequential": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Widget UUID" }, { "name": "entryId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 120 }, "url": { "type": "string" }, "favorite": { "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Updated directory entry", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "delete": { "tags": [ "Widgets" ], "operationId": "deleteWidgetSiteDirectoryEntry", "summary": "Delete a Direct User page", "x-openai-isConsequential": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Widget UUID" }, { "name": "entryId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted directory entry", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/account/usage": { "get": { "tags": [ "Account" ], "operationId": "getAccountUsage", "summary": "Get account plan limits and usage", "responses": { "200": { "description": "Account usage", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/contacts": { "get": { "tags": [ "Contacts" ], "operationId": "listContacts", "summary": "List reconciled Contacts and Leads", "description": "Returns account-scoped leads reconciled from visitor identity, callback forms, normalized emails/phones, and attached visitor sessions.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } }, { "name": "q", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Contacts", "content": { "application/json": { "schema": { "type": "object", "properties": { "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "post": { "tags": [ "Contacts" ], "operationId": "createContact", "summary": "Create a manual Contact or Lead", "description": "Requires widgets:write scope and account owner/admin access.", "x-openai-isConsequential": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactInput" } } } }, "responses": { "201": { "description": "Created contact", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/contacts/{contactId}": { "get": { "tags": [ "Contacts" ], "operationId": "getContact", "summary": "Get a Contact or Lead timeline", "description": "Returns one contact with normalized emails, phones, attached visitor sessions, notes, callback forms/voice notes, call history, SIP/PSTN attempts, and unified chat messages.", "parameters": [ { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Contact or Lead UUID" } ], "responses": { "200": { "description": "Contact detail", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "patch": { "tags": [ "Contacts" ], "operationId": "updateContact", "summary": "Edit a Contact or Lead", "description": "Requires widgets:write scope and account owner/admin access.", "x-openai-isConsequential": true, "parameters": [ { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Contact or Lead UUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactInput" } } } }, "responses": { "200": { "description": "Updated contact", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/contacts/{contactId}/emails": { "post": { "tags": [ "Contacts" ], "operationId": "addContactEmail", "summary": "Add an email address to a Contact or Lead", "x-openai-isConsequential": true, "parameters": [ { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Contact or Lead UUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string" }, "label": { "type": "string" }, "isPrimary": { "type": "boolean" } } } } } }, "responses": { "201": { "description": "Added email", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/contacts/{contactId}/emails/{emailId}": { "delete": { "tags": [ "Contacts" ], "operationId": "deleteContactEmail", "summary": "Remove an email address from a Contact or Lead", "x-openai-isConsequential": true, "parameters": [ { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Contact or Lead UUID" }, { "name": "emailId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Removed email", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/contacts/{contactId}/phones": { "post": { "tags": [ "Contacts" ], "operationId": "addContactPhone", "summary": "Add a phone number to a Contact or Lead", "x-openai-isConsequential": true, "parameters": [ { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Contact or Lead UUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phone" ], "properties": { "phone": { "type": "string" }, "label": { "type": "string" }, "isPrimary": { "type": "boolean" } } } } } }, "responses": { "201": { "description": "Added phone", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/contacts/{contactId}/phones/{phoneId}": { "delete": { "tags": [ "Contacts" ], "operationId": "deleteContactPhone", "summary": "Remove a phone number from a Contact or Lead", "x-openai-isConsequential": true, "parameters": [ { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Contact or Lead UUID" }, { "name": "phoneId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Removed phone", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/contacts/{contactId}/visitor-sessions": { "post": { "tags": [ "Contacts" ], "operationId": "attachContactVisitorSession", "summary": "Attach a visitor session to a Contact or Lead", "description": "Accepts a widgetId plus visitorId or temporary channel number. Requires widgets:write scope and account owner/admin access.", "x-openai-isConsequential": true, "parameters": [ { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Contact or Lead UUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "widgetId", "visitorId" ], "properties": { "widgetId": { "type": "string", "format": "uuid" }, "visitorId": { "type": "string" } } } } } }, "responses": { "201": { "description": "Attached visitor session", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/contacts/{contactId}/visitor-sessions/{linkId}": { "delete": { "tags": [ "Contacts" ], "operationId": "detachContactVisitorSession", "summary": "Detach a visitor session from a Contact or Lead", "x-openai-isConsequential": true, "parameters": [ { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Contact or Lead UUID" }, { "name": "linkId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Detached visitor session", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/contacts/{contactId}/merge": { "post": { "tags": [ "Contacts" ], "operationId": "mergeContact", "summary": "Merge a duplicate Contact or Lead into this target", "description": "Moves emails, phones, visitor sessions, identities, notes, messages, callbacks, and call history into the target contact, records a merge event, and deletes the source contact.", "x-openai-isConsequential": true, "parameters": [ { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Contact or Lead UUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "sourceContactId" ], "properties": { "sourceContactId": { "type": "string", "format": "uuid" }, "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "Merged contact", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/webhooks": { "get": { "tags": [ "Webhooks" ], "operationId": "listWebhooks", "summary": "List account webhooks", "responses": { "200": { "description": "Webhooks", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "post": { "tags": [ "Webhooks" ], "operationId": "createWebhook", "summary": "Create a signed webhook endpoint", "description": "Requires webhooks:write scope. The secret is returned only once.", "x-openai-isConsequential": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInput" } } } }, "responses": { "201": { "description": "Created webhook", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/webhooks/{id}": { "patch": { "tags": [ "Webhooks" ], "operationId": "updateWebhook", "summary": "Update a webhook", "x-openai-isConsequential": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Webhook UUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInput" } } } }, "responses": { "200": { "description": "Updated webhook", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "delete": { "tags": [ "Webhooks" ], "operationId": "deleteWebhook", "summary": "Delete a webhook", "x-openai-isConsequential": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Webhook UUID" } ], "responses": { "200": { "description": "Deleted webhook", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/webhooks/{id}/test": { "post": { "tags": [ "Webhooks" ], "operationId": "testWebhook", "summary": "Send a test event to a webhook", "x-openai-isConsequential": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Webhook UUID" } ], "responses": { "202": { "description": "Queued test delivery", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/webhooks/{id}/deliveries": { "get": { "tags": [ "Webhooks" ], "operationId": "listWebhookDeliveries", "summary": "List recent webhook delivery attempts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Webhook UUID" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } } ], "responses": { "200": { "description": "Webhook deliveries", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/mcp": { "post": { "tags": [ "MCP" ], "operationId": "mcpJsonRpc", "summary": "MCP-compatible JSON-RPC endpoint", "description": "Use JSON-RPC methods initialize, tools/list, and tools/call with an OAuth bearer token or Laleo PAT.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "JSON-RPC response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Token scope or widget permission is missing", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } } } }