{ "openapi": "3.1.0", "info": { "title": "LetsBot API", "version": "1.0.0", "description": "The LetsBot developer API (`/api/v1`): send WhatsApp messages, templates and interactive messages, manage chats,\ngroups and Live Chat contacts, and read the message archive.\n\n**Authentication.** `Authorization: Bearer `. Requires an active subscription with the API Access\nadd-on (or an active trial).\n\n**Always send `Accept: application/json`.** Without it some refusals (framework validation, a locked\nworkspace) answer with an HTML redirect instead of JSON.\n\n**Request bodies.** Documented as JSON; `application/x-www-form-urlencoded` and `multipart/form-data` with the same\nfield names are also accepted (Laravel reads all three). No endpoint takes a file upload: media is passed by URL.\n\n**Success is not only the HTTP status.** Most endpoints pass the connection gateway's answer through unchanged;\ncheck `success` in the body. Many endpoints answer a validation failure with **HTTP 202** and\n`{\"Status\": 0, \"Message\": ...}` (a historic contract kept for existing integrations). Treat a 2xx whose body has\n`success: false` or a falsy `Status` as a failure.\n\n**Strict validation (recommended for new integrations).** Send `X-LetsBot-Validation: strict` on a request (the\nRFC 7240 form `Prefer: validation=strict` is accepted too) and a validation failure answers **HTTP 422** with\n`{\"message\": ..., \"errors\": {\"\": [...]}}` — every failing field, always JSON. Without the header nothing\nchanges.\n\n**Rate limits.** 1000 requests per minute per channel (`429` + `Retry-After`). A workspace can also set a daily\nlimit on API sends (`429 automation_daily_limit_reached`).\n\n**Idempotency.** Every send endpoint (marked `x-letsbot-send: true`) accepts an `Idempotency-Key` header; see the\nparameter for the exact replay rules.\n\n**Webhooks** (configured in the panel, not through this API) are POSTed as `{\"event\": , \"data\": {...}}`\nwith a `Signature` header: hex HMAC-SHA256 of the raw body keyed with the literal string `Letsbot`, the same for\nevery workspace. It is not a secret and proves nothing about the sender; authenticate webhooks with a custom\nheader you configure on the webhook instead.\n\nSource of truth: this file must list exactly the live `/api/v1` routes (`OpenApiRouteParityTest`).\n", "contact": { "name": "LetsBot support", "email": "support@letsbot.net", "url": "https://letsbot.net/developers/api" } }, "servers": [ { "url": "https://letsbot.net/api/v1", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Messages", "description": "Send text, replies, reactions, mentions, lists; read and delete messages." }, { "name": "Media", "description": "Send files, images, audio, video, GIFs, voice notes, locations, contact cards and catalogs by URL." }, { "name": "Interactive", "description": "Buttons, button templates and Messenger/Instagram carousels." }, { "name": "Templates", "description": "Pre-approved WhatsApp template messages (official Cloud API channels only)." }, { "name": "Chats", "description": "Chat list, conversations and chat state (read, archive, mute, pin, typing)." }, { "name": "Contacts", "description": "Contacts, Live Chat labels and team-member assignment." }, { "name": "Groups", "description": "Create and manage WhatsApp groups." }, { "name": "Invites", "description": "Group invite codes and links." }, { "name": "User", "description": "Profile, status, presence, picture and blocking." }, { "name": "Instance", "description": "Connection (instance) status, presence and settings." }, { "name": "Products", "description": "Catalog products, collections and orders." }, { "name": "Orders", "description": "Record orders from your own store system (not Salla / Zid) to start the order journey and send the invoice." }, { "name": "Session", "description": "QR linking and session state (QR-linked channels)." }, { "name": "Archive", "description": "The message archive by date, inbound and outbound." }, { "name": "Zapier integration", "description": "The workspace Zapier / Make / n8n surface at https://{workspace}.letsbot.net/api (NOT /api/v1), authenticated with `X-Zapier-Api-Key`. Its operations carry their own `servers` and `security`." }, { "name": "CRM", "description": "The public CRM API at https://{workspace}.letsbot.net/api/v1/crm — contacts, companies, deals, tasks, activities, quotes, products and REST-hook webhooks. Workspace API key (`X-Zapier-Api-Key`) with the `crm` scope ticked; the key acts for the whole workspace. Envelope `{success, data, meta?}` / `{success: false, error, code, errors?}`; 120 requests per minute per key." } ], "paths": { "/button": { "post": { "operationId": "sendButtons", "tags": [ "Interactive" ], "summary": "Send a buttons message", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.\n\nSend endpoint: accepts `Idempotency-Key` and counts towards the workspace's optional daily API send limit.", "x-letsbot-send": true, "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/Phone" }, "body": { "type": "string" }, "title": { "type": "string" }, "footer": { "type": "string" }, "buttons": { "type": "array", "items": { "$ref": "#/components/schemas/Button" }, "minItems": 1 }, "caption": { "type": "string" } }, "required": [ "phone", "body", "title", "footer", "buttons" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "X-LetsBot-Automation-Limit": { "$ref": "#/components/headers/AutomationLimit" }, "X-LetsBot-Automation-Used": { "$ref": "#/components/headers/AutomationUsed" }, "X-LetsBot-Automation-Resets-At": { "$ref": "#/components/headers/AutomationResetsAt" } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/SendConflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); the Idempotency-Key was already used for a different request; WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/SendTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/button/document": { "post": { "operationId": "sendButtonsWithDocument", "tags": [ "Interactive" ], "summary": "Send buttons with a document header", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.\n\nSend endpoint: accepts `Idempotency-Key` and counts towards the workspace's optional daily API send limit.", "x-letsbot-send": true, "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/Phone" }, "caption": { "type": "string" }, "document": { "type": "string", "format": "uri", "description": "Public URL (Laravel `url` rule)." }, "fileName": { "type": "string" }, "buttons": { "type": "array", "items": { "$ref": "#/components/schemas/Button" }, "minItems": 1 }, "footer": { "type": "string" } }, "required": [ "phone", "caption", "document", "buttons" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "X-LetsBot-Automation-Limit": { "$ref": "#/components/headers/AutomationLimit" }, "X-LetsBot-Automation-Used": { "$ref": "#/components/headers/AutomationUsed" }, "X-LetsBot-Automation-Resets-At": { "$ref": "#/components/headers/AutomationResetsAt" } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/SendConflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); the Idempotency-Key was already used for a different request; WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/SendTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/button/document/template": { "post": { "operationId": "sendButtonsTemplateWithDocument", "tags": [ "Interactive" ], "summary": "Send a buttons template with a document", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.\n\nSend endpoint: accepts `Idempotency-Key` and counts towards the workspace's optional daily API send limit.", "x-letsbot-send": true, "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/Phone" }, "caption": { "type": "string", "description": "Message body text." }, "buttons": { "type": "array", "items": { "$ref": "#/components/schemas/Button" }, "minItems": 1 }, "title": { "type": "string" }, "footer": { "type": "string" }, "document": { "type": "string", "format": "uri", "description": "Public URL (Laravel `url` rule)." }, "fileName": { "type": "string" } }, "required": [ "phone", "caption", "buttons", "document" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "X-LetsBot-Automation-Limit": { "$ref": "#/components/headers/AutomationLimit" }, "X-LetsBot-Automation-Used": { "$ref": "#/components/headers/AutomationUsed" }, "X-LetsBot-Automation-Resets-At": { "$ref": "#/components/headers/AutomationResetsAt" } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/SendConflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); the Idempotency-Key was already used for a different request; WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/SendTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/button/image": { "post": { "operationId": "sendButtonsWithImage", "tags": [ "Interactive" ], "summary": "Send buttons with an image header", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.\n\nSend endpoint: accepts `Idempotency-Key` and counts towards the workspace's optional daily API send limit.", "x-letsbot-send": true, "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/Phone" }, "caption": { "type": "string" }, "image": { "type": "string", "format": "uri", "description": "Public URL (Laravel `url` rule)." }, "buttons": { "type": "array", "items": { "$ref": "#/components/schemas/Button" }, "minItems": 1 }, "footer": { "type": "string" } }, "required": [ "phone", "caption", "image", "buttons" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "X-LetsBot-Automation-Limit": { "$ref": "#/components/headers/AutomationLimit" }, "X-LetsBot-Automation-Used": { "$ref": "#/components/headers/AutomationUsed" }, "X-LetsBot-Automation-Resets-At": { "$ref": "#/components/headers/AutomationResetsAt" } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/SendConflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); the Idempotency-Key was already used for a different request; WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/SendTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/button/image/template": { "post": { "operationId": "sendButtonsTemplateWithImage", "tags": [ "Interactive" ], "summary": "Send a buttons template with an image", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.\n\nSend endpoint: accepts `Idempotency-Key` and counts towards the workspace's optional daily API send limit.", "x-letsbot-send": true, "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/Phone" }, "caption": { "type": "string", "description": "Message body text." }, "buttons": { "type": "array", "items": { "$ref": "#/components/schemas/Button" }, "minItems": 1 }, "title": { "type": "string" }, "footer": { "type": "string" }, "image": { "type": "string", "format": "uri", "description": "Public URL (Laravel `url` rule)." } }, "required": [ "phone", "caption", "buttons", "image" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "X-LetsBot-Automation-Limit": { "$ref": "#/components/headers/AutomationLimit" }, "X-LetsBot-Automation-Used": { "$ref": "#/components/headers/AutomationUsed" }, "X-LetsBot-Automation-Resets-At": { "$ref": "#/components/headers/AutomationResetsAt" } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/SendConflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); the Idempotency-Key was already used for a different request; WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/SendTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/button/location": { "post": { "operationId": "sendButtonsWithLocation", "tags": [ "Interactive" ], "summary": "Send buttons with a location header", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.\n\nSend endpoint: accepts `Idempotency-Key` and counts towards the workspace's optional daily API send limit.", "x-letsbot-send": true, "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/Phone" }, "caption": { "type": "string" }, "lat": { "type": [ "number", "string" ], "description": "Decimal degrees." }, "lng": { "type": [ "number", "string" ], "description": "Decimal degrees." }, "buttons": { "type": "array", "items": { "$ref": "#/components/schemas/Button" }, "minItems": 1 }, "footer": { "type": "string" } }, "required": [ "phone", "caption", "lat", "lng", "buttons" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "X-LetsBot-Automation-Limit": { "$ref": "#/components/headers/AutomationLimit" }, "X-LetsBot-Automation-Used": { "$ref": "#/components/headers/AutomationUsed" }, "X-LetsBot-Automation-Resets-At": { "$ref": "#/components/headers/AutomationResetsAt" } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/SendConflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); the Idempotency-Key was already used for a different request; WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/SendTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/button/location/template": { "post": { "operationId": "sendButtonsTemplateWithLocation", "tags": [ "Interactive" ], "summary": "Send a buttons template with a location", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.\n\nSend endpoint: accepts `Idempotency-Key` and counts towards the workspace's optional daily API send limit.", "x-letsbot-send": true, "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/Phone" }, "caption": { "type": "string", "description": "Message body text." }, "buttons": { "type": "array", "items": { "$ref": "#/components/schemas/Button" }, "minItems": 1 }, "title": { "type": "string" }, "footer": { "type": "string" }, "lat": { "type": [ "number", "string" ], "description": "Decimal degrees." }, "lng": { "type": [ "number", "string" ], "description": "Decimal degrees." } }, "required": [ "phone", "caption", "lat", "lng", "buttons" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "X-LetsBot-Automation-Limit": { "$ref": "#/components/headers/AutomationLimit" }, "X-LetsBot-Automation-Used": { "$ref": "#/components/headers/AutomationUsed" }, "X-LetsBot-Automation-Resets-At": { "$ref": "#/components/headers/AutomationResetsAt" } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/SendConflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); the Idempotency-Key was already used for a different request; WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/SendTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/button/template": { "post": { "operationId": "sendButtonsTemplate", "tags": [ "Interactive" ], "summary": "Send a buttons template message", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.\n\nSend endpoint: accepts `Idempotency-Key` and counts towards the workspace's optional daily API send limit.", "x-letsbot-send": true, "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/Phone" }, "body": { "type": "string" }, "title": { "type": "string" }, "footer": { "type": "string" }, "buttons": { "type": "array", "items": { "$ref": "#/components/schemas/Button" }, "minItems": 1 } }, "required": [ "phone", "body", "title", "footer", "buttons" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "X-LetsBot-Automation-Limit": { "$ref": "#/components/headers/AutomationLimit" }, "X-LetsBot-Automation-Used": { "$ref": "#/components/headers/AutomationUsed" }, "X-LetsBot-Automation-Resets-At": { "$ref": "#/components/headers/AutomationResetsAt" } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/SendConflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); the Idempotency-Key was already used for a different request; WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/SendTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/button/video": { "post": { "operationId": "sendButtonsWithVideo", "tags": [ "Interactive" ], "summary": "Send buttons with a video header", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.\n\nSend endpoint: accepts `Idempotency-Key` and counts towards the workspace's optional daily API send limit.", "x-letsbot-send": true, "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/Phone" }, "caption": { "type": "string" }, "video": { "type": "string", "format": "uri", "description": "Public URL (Laravel `url` rule)." }, "buttons": { "type": "array", "items": { "$ref": "#/components/schemas/Button" }, "minItems": 1 }, "footer": { "type": "string" } }, "required": [ "phone", "caption", "video", "buttons" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "X-LetsBot-Automation-Limit": { "$ref": "#/components/headers/AutomationLimit" }, "X-LetsBot-Automation-Used": { "$ref": "#/components/headers/AutomationUsed" }, "X-LetsBot-Automation-Resets-At": { "$ref": "#/components/headers/AutomationResetsAt" } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/SendConflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); the Idempotency-Key was already used for a different request; WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/SendTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/button/video/template": { "post": { "operationId": "sendButtonsTemplateWithVideo", "tags": [ "Interactive" ], "summary": "Send a buttons template with a video", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.\n\nSend endpoint: accepts `Idempotency-Key` and counts towards the workspace's optional daily API send limit.", "x-letsbot-send": true, "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/Phone" }, "caption": { "type": "string", "description": "Message body text." }, "buttons": { "type": "array", "items": { "$ref": "#/components/schemas/Button" }, "minItems": 1 }, "title": { "type": "string" }, "footer": { "type": "string" }, "video": { "type": "string", "format": "uri", "description": "Public URL (Laravel `url` rule)." } }, "required": [ "phone", "caption", "buttons", "video" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "X-LetsBot-Automation-Limit": { "$ref": "#/components/headers/AutomationLimit" }, "X-LetsBot-Automation-Used": { "$ref": "#/components/headers/AutomationUsed" }, "X-LetsBot-Automation-Resets-At": { "$ref": "#/components/headers/AutomationResetsAt" } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/SendConflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); the Idempotency-Key was already used for a different request; WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/SendTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/carousel": { "post": { "operationId": "sendCarousel", "tags": [ "Interactive" ], "summary": "Send a carousel (Messenger / Instagram)", "description": "Meta generic template. Resolves the workspace's Messenger/Instagram channel by `platform`, not the API key's WhatsApp channel. Refusals (no such channel connected) come back as HTTP 200 `{\"Status\": 0, \"Message\": ...}`.\n\nThe 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.\n\nSend endpoint: accepts `Idempotency-Key` and counts towards the workspace's optional daily API send limit.", "x-letsbot-send": true, "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "recipient": { "type": "string", "description": "Page-scoped id (PSID) or Instagram-scoped id (IGSID)." }, "platform": { "type": [ "string", "null" ], "enum": [ "messenger", "instagram", null ], "default": "messenger" }, "cards": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "$ref": "#/components/schemas/CarouselCard" } } }, "required": [ "recipient", "cards" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarouselResponse" } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "X-LetsBot-Automation-Limit": { "$ref": "#/components/headers/AutomationLimit" }, "X-LetsBot-Automation-Used": { "$ref": "#/components/headers/AutomationUsed" }, "X-LetsBot-Automation-Resets-At": { "$ref": "#/components/headers/AutomationResetsAt" } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/SendConflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); the Idempotency-Key was already used for a different request; WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/SendTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/chat/archive": { "post": { "operationId": "archiveChat", "tags": [ "Chats" ], "summary": "Archive a chat", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.", "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/Phone" } }, "required": [ "phone" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/chat/conversation": { "get": { "operationId": "getConversation", "tags": [ "Chats" ], "summary": "Get a chat's conversation", "description": "Reads the connection gateway's store — QR (WhatsApp Web) numbers only. On an official (Cloud API) number it answers `409` with `error_code: USE_MESSAGES_ARCHIVE` and a ready-made `use.example` URL for `GET /messages`.\n\nThe 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.", "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" }, { "name": "phone", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/Phone" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 25 } }, { "name": "cursorId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Message id to page back from." }, { "name": "cursorFromMe", "in": "query", "required": false, "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/UseMessagesArchiveConflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/chat/list": { "get": { "operationId": "getChatList", "tags": [ "Chats" ], "summary": "List chats", "description": "**Official (Cloud API) numbers:** served from the workspace — every conversation with a message, newest `last_message_date` first, with keyset pagination (`ArchiveChatPage`).\n\n**QR (WhatsApp Web) numbers:** the connection gateway's answer passed through as-is (`GatewayResponse`). Check `success`.", "parameters": [ { "name": "platform", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Default the platform of the calling channel; a platform name or `all`. Official numbers only." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Official numbers only." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "`next_cursor` from the previous page, unchanged. Official numbers only." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ArchiveChatPage" }, { "$ref": "#/components/schemas/GatewayResponse" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetaRejection" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/chat/mute": { "post": { "operationId": "muteChat", "tags": [ "Chats" ], "summary": "Mute a chat", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.", "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/PhoneDigits" }, "duration": { "type": [ "integer", "string" ], "description": "Numeric duration." } }, "required": [ "phone", "duration" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/chat/pin": { "post": { "operationId": "pinChat", "tags": [ "Chats" ], "summary": "Pin a chat", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.", "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/Phone" } }, "required": [ "phone" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/chat/read": { "post": { "operationId": "readChat", "tags": [ "Chats" ], "summary": "Mark a chat read", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.", "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/Phone" } }, "required": [ "phone" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/chat/recording": { "post": { "operationId": "setRecording", "tags": [ "Chats" ], "summary": "Show 'recording…' in a chat", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.", "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chat": { "type": "string", "description": "Phone number or JID." } }, "required": [ "chat" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/chat/typing": { "post": { "operationId": "setTyping", "tags": [ "Chats" ], "summary": "Show 'typing…' in a chat", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.", "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chat": { "type": "string", "description": "Phone number or JID." } }, "required": [ "chat" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/chat/unarchive": { "post": { "operationId": "unarchiveChat", "tags": [ "Chats" ], "summary": "Unarchive a chat", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.", "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/Phone" } }, "required": [ "phone" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/chat/unmute": { "post": { "operationId": "unmuteChat", "tags": [ "Chats" ], "summary": "Unmute a chat", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.", "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/Phone" } }, "required": [ "phone" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/chat/unpin": { "post": { "operationId": "unpinChat", "tags": [ "Chats" ], "summary": "Unpin a chat", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.", "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/Phone" } }, "required": [ "phone" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/chat/unread": { "post": { "operationId": "unreadChat", "tags": [ "Chats" ], "summary": "Mark a chat unread", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.", "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/Phone" } }, "required": [ "phone" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/check/phone": { "post": { "operationId": "checkPhone", "tags": [ "Chats" ], "summary": "Check whether a number is on WhatsApp", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.", "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/Phone" } }, "required": [ "phone" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/contacts": { "get": { "operationId": "getContacts", "tags": [ "Contacts" ], "summary": "List contacts", "description": "**Official (Cloud API) numbers:** served from the workspace's own contacts — search, an incremental-sync filter (`updated_since`) and keyset pagination (`next_cursor`). The body says `\"source\": \"archive\"` (`ArchiveContactPage`).\n\n**QR (WhatsApp Web) numbers:** the connection gateway's answer passed through as-is (`GatewayResponse`); the query parameters below do not apply there. Check `success`.\n\nContacts are workspace-wide: one customer is one contact whichever number they wrote to.", "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 100 }, "description": "Matches name, saved name, WhatsApp profile name or number. Official numbers only." }, { "name": "phone", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 32 }, "description": "One contact by number. Official numbers only." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 40 }, "description": "`YYYY-MM-DD` or an ISO-8601 datetime, read in `timezone`. Only contacts created or changed since then. Official numbers only." }, { "name": "timezone", "in": "query", "required": false, "schema": { "type": "string", "default": "UTC" }, "description": "IANA zone used to read `updated_since`. Returned timestamps are UTC." }, { "name": "include_groups", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "0", "1", "true", "false" ] }, "description": "`1` also returns WhatsApp groups. Official numbers only." }, { "name": "platform", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Default the platform of the calling channel; a platform name (`messenger`, `instagram`, ...) or `all`. Official numbers only." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "`next_cursor` from the previous page, unchanged." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ArchiveContactPage" }, { "$ref": "#/components/schemas/GatewayResponse" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: an invalid parameter or cursor (official numbers, `ArchiveValidationError`); WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ArchiveValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/group/add/participant": { "post": { "operationId": "addGroupParticipant", "tags": [ "Groups" ], "summary": "Add group participants", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.", "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jid": { "type": "string", "description": "Group JID, e.g. `120363000000000000@g.us`." }, "phones": { "type": "array", "items": { "type": [ "string", "integer" ], "description": "Numeric phone." }, "minItems": 1 } }, "required": [ "jid", "phones" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/group/conversation": { "get": { "operationId": "getGroupConversation", "tags": [ "Groups" ], "summary": "Get a group's conversation", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.", "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" }, { "name": "jid", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Group JID, e.g. `120363000000000000@g.us`." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/group/create": { "post": { "operationId": "createGroup", "tags": [ "Groups" ], "summary": "Create a group", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.", "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string" }, "phones": { "type": "array", "items": { "type": [ "string", "integer" ], "description": "Numeric phone." }, "minItems": 1 } }, "required": [ "subject", "phones" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/group/demote/participant": { "post": { "operationId": "demoteGroupParticipant", "tags": [ "Groups" ], "summary": "Demote group admins", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.", "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jid": { "type": "string", "description": "Group JID, e.g. `120363000000000000@g.us`." }, "phones": { "type": "array", "items": { "type": [ "string", "integer" ], "description": "Numeric phone." }, "minItems": 1 } }, "required": [ "jid", "phones" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/group/display/picture": { "get": { "operationId": "getChatDisplayPicture", "tags": [ "Groups" ], "summary": "Get a group's picture", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.", "parameters": [ { "name": "jid", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Group JID, e.g. `120363000000000000@g.us`." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed; WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/group/join": { "post": { "operationId": "joinGroup", "tags": [ "Groups" ], "summary": "Join a group by invite code", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.", "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" } }, "required": [ "code" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/group/list": { "get": { "operationId": "getGroupList", "tags": [ "Groups" ], "summary": "List groups", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetaRejection" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/group/meta/data": { "get": { "operationId": "groupMetadata", "tags": [ "Groups" ], "summary": "Get group metadata", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.", "parameters": [ { "name": "jid", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Group JID, e.g. `120363000000000000@g.us`." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed; WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/group/promote/participant": { "post": { "operationId": "promoteGroupParticipant", "tags": [ "Groups" ], "summary": "Promote participants to admin", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.", "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jid": { "type": "string", "description": "Group JID, e.g. `120363000000000000@g.us`." }, "phones": { "type": "array", "items": { "type": [ "string", "integer" ], "description": "Numeric phone." }, "minItems": 1 } }, "required": [ "jid", "phones" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/group/remove/participant": { "post": { "operationId": "removeGroupParticipant", "tags": [ "Groups" ], "summary": "Remove group participants", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.", "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jid": { "type": "string", "description": "Group JID, e.g. `120363000000000000@g.us`." }, "phones": { "type": "array", "items": { "type": [ "string", "integer" ], "description": "Numeric phone." }, "minItems": 1 } }, "required": [ "jid", "phones" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/group/rename": { "post": { "operationId": "renameGroup", "tags": [ "Groups" ], "summary": "Rename a group", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.", "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jid": { "type": "string", "description": "Group JID, e.g. `120363000000000000@g.us`." }, "subject": { "type": "string" } }, "required": [ "jid", "subject" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/group/set/description": { "post": { "operationId": "setGroupDescription", "tags": [ "Groups" ], "summary": "Set a group's description", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.", "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jid": { "type": "string", "description": "Group JID, e.g. `120363000000000000@g.us`." }, "description": { "type": "string" } }, "required": [ "jid", "description" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/group/set/display/picture": { "post": { "operationId": "setChatDisplayPicture", "tags": [ "Groups" ], "summary": "Set a group's picture", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jid": { "type": "string", "description": "Group JID, e.g. `120363000000000000@g.us`." }, "image": { "type": "string", "description": "Image URL." } }, "required": [ "jid", "image" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed; WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/group/settings": { "post": { "operationId": "groupSettings", "tags": [ "Groups" ], "summary": "Change group settings", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.", "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jid": { "type": "string", "description": "Group JID, e.g. `120363000000000000@g.us`." }, "settings": { "type": "string", "enum": [ "announcement", "not_announcement", "locked", "unlocked" ] } }, "required": [ "settings", "jid" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/instance/query/broadcast": { "post": { "operationId": "queryBroadcast", "tags": [ "Instance" ], "summary": "Query a pending broadcast", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "broadcast": { "type": "string" } }, "required": [ "broadcast" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed; WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/instance/set/presence": { "post": { "operationId": "setPresence", "tags": [ "Instance" ], "summary": "Set presence in a chat", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.", "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/Phone" }, "presence": { "type": "string", "enum": [ "unavailable", "available", "composing", "recording", "paused" ] } }, "required": [ "phone", "presence" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/instance/set/settings": { "post": { "operationId": "setSettings", "tags": [ "Instance" ], "summary": "Set instance settings", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.", "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "markOnlineOnConnect": { "type": "boolean" } }, "required": [ "markOnlineOnConnect" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/instance/set/status": { "post": { "operationId": "setStatus", "tags": [ "Instance" ], "summary": "Set the instance status", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.", "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/instance/status": { "get": { "operationId": "status", "tags": [ "Instance" ], "summary": "Get the connection (instance) status", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetaRejection" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/invite/code": { "post": { "operationId": "inviteCode", "tags": [ "Invites" ], "summary": "Get a group's invite code", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jid": { "type": "string", "description": "Group JID, e.g. `120363000000000000@g.us`." } }, "required": [ "jid" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed; WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/invite/get/info": { "get": { "operationId": "groupGetInviteInfo", "tags": [ "Invites" ], "summary": "Get group info from an invite code", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.", "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" }, { "name": "code", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/invite/revoke/code": { "post": { "operationId": "revokeInviteCode", "tags": [ "Invites" ], "summary": "Revoke a group's invite code", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jid": { "type": "string", "description": "Group JID, e.g. `120363000000000000@g.us`." } }, "required": [ "jid" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed; WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/invite/send/link": { "post": { "operationId": "sendInviteLink", "tags": [ "Invites" ], "summary": "Send a group invite link", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\nSend endpoint: accepts `Idempotency-Key` and counts towards the workspace's optional daily API send limit.", "x-letsbot-send": true, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "type": "string", "description": "Recipient phone number." }, "jid": { "type": "string", "description": "Group JID, e.g. `120363000000000000@g.us`." } }, "required": [ "to", "jid" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "X-LetsBot-Automation-Limit": { "$ref": "#/components/headers/AutomationLimit" }, "X-LetsBot-Automation-Used": { "$ref": "#/components/headers/AutomationUsed" }, "X-LetsBot-Automation-Resets-At": { "$ref": "#/components/headers/AutomationResetsAt" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/SendConflict" }, "422": { "description": "Unprocessable: validation failed; the Idempotency-Key was already used for a different request; WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/SendTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/list/message": { "post": { "operationId": "sendList", "tags": [ "Messages" ], "summary": "Send a list message", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.\n\nSend endpoint: accepts `Idempotency-Key` and counts towards the workspace's optional daily API send limit.", "x-letsbot-send": true, "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/PhoneDigits" }, "body": { "type": "string" }, "title": { "type": "string" }, "footer": { "type": "string" }, "buttonText": { "type": "string", "description": "Label of the button that opens the list." }, "sections": { "type": "array", "items": { "$ref": "#/components/schemas/ListSection" } } }, "required": [ "phone", "body", "title", "footer", "buttonText", "sections" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "X-LetsBot-Automation-Limit": { "$ref": "#/components/headers/AutomationLimit" }, "X-LetsBot-Automation-Used": { "$ref": "#/components/headers/AutomationUsed" }, "X-LetsBot-Automation-Resets-At": { "$ref": "#/components/headers/AutomationResetsAt" } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/SendConflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); the Idempotency-Key was already used for a different request; WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/SendTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/live_chat/contact": { "get": { "operationId": "getContact", "tags": [ "Contacts" ], "summary": "Get a Live Chat contact with its labels and team members", "description": "Runs inside the workspace. When `phone` is given, a contact with chat id `@s.whatsapp.net` is created if it does not exist yet (before validation).", "parameters": [ { "name": "phone", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/Phone" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactValidationError" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/live_chat/labels": { "get": { "operationId": "getLabels", "tags": [ "Contacts" ], "summary": "List labels", "description": "Runs inside the workspace. When `phone` is given, a contact with chat id `@s.whatsapp.net` is created if it does not exist yet (before validation).", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/live_chat/moderators": { "get": { "operationId": "getModerators", "tags": [ "Contacts" ], "summary": "List team members", "description": "Runs inside the workspace. When `phone` is given, a contact with chat id `@s.whatsapp.net` is created if it does not exist yet (before validation).", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModeratorList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/live_chat/set-label": { "post": { "operationId": "setContactLabel", "tags": [ "Contacts" ], "summary": "Add a label to a contact", "description": "Runs inside the workspace. When `phone` is given, a contact with chat id `@s.whatsapp.net` is created if it does not exist yet (before validation). Existing labels are kept.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/Phone" }, "label_id": { "type": "integer" } }, "required": [ "phone", "label_id" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactValidationError" } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/live_chat/set-moderator": { "post": { "operationId": "setContactModerator", "tags": [ "Contacts" ], "summary": "Assign a team member to a contact", "description": "Runs inside the workspace. When `phone` is given, a contact with chat id `@s.whatsapp.net` is created if it does not exist yet (before validation). Existing assignments are kept.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/Phone" }, "moderator_id": { "type": "integer" } }, "required": [ "phone", "moderator_id" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactValidationError" } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/message/delete": { "delete": { "operationId": "deleteMessage", "tags": [ "Messages" ], "summary": "Delete a message for everyone", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.", "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" }, { "name": "phone", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/PhoneDigits" } }, { "name": "messageId", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/message/fetch": { "get": { "operationId": "getMessages", "tags": [ "Messages" ], "summary": "Fetch recent messages from the gateway", "description": "Reads the connection gateway's store (no date filter) — QR (WhatsApp Web) numbers only. On an official (Cloud API) number it answers `409` with `error_code: USE_MESSAGES_ARCHIVE`; read the archive by date with `GET /messages`.\n\nThe 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "minimum": 1 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/UseMessagesArchiveConflict" }, "422": { "description": "Unprocessable: WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetaRejection" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/message/id": { "get": { "operationId": "getMessageByID", "tags": [ "Messages" ], "summary": "Get one message by id", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.", "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" }, { "name": "phone", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/PhoneDigits" } }, { "name": "messageId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The stored message id. An id that is not stored in the workspace is a validation failure on `messageId` (202 by default, 422 in strict mode)." }, { "name": "messageID", "in": "query", "required": false, "deprecated": true, "schema": { "type": "string" }, "description": "Ignored. Earlier documentation asked for the id twice; only `messageId` is read." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/message/send": { "post": { "operationId": "sendMessage", "tags": [ "Messages" ], "summary": "Send a text message", "description": "`pricing_estimate` is added to the response only when the workspace turned the pricing estimate on (official channels).\n\nThe 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.\n\nSend endpoint: accepts `Idempotency-Key` and counts towards the workspace's optional daily API send limit.", "x-letsbot-send": true, "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/Phone" }, "body": { "type": "string", "description": "Message text." } }, "required": [ "phone", "body" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageResponse" } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "X-LetsBot-Automation-Limit": { "$ref": "#/components/headers/AutomationLimit" }, "X-LetsBot-Automation-Used": { "$ref": "#/components/headers/AutomationUsed" }, "X-LetsBot-Automation-Resets-At": { "$ref": "#/components/headers/AutomationResetsAt" } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/SendConflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); the Idempotency-Key was already used for a different request; WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/SendTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/message/send/disappearing": { "post": { "operationId": "sendDisappearingMessage", "tags": [ "Messages" ], "summary": "Send a disappearing text message", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.\n\nSend endpoint: accepts `Idempotency-Key` and counts towards the workspace's optional daily API send limit.", "x-letsbot-send": true, "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/Phone" }, "body": { "type": "string" }, "duration": { "type": "string", "enum": [ "1", "7", "90" ], "description": "Days before the message disappears. Any other value (or none) becomes 7." } }, "required": [ "phone", "body" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "X-LetsBot-Automation-Limit": { "$ref": "#/components/headers/AutomationLimit" }, "X-LetsBot-Automation-Used": { "$ref": "#/components/headers/AutomationUsed" }, "X-LetsBot-Automation-Resets-At": { "$ref": "#/components/headers/AutomationResetsAt" } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/SendConflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); the Idempotency-Key was already used for a different request; WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/SendTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/message/send/forward/message": { "post": { "operationId": "forwardMessage", "tags": [ "Messages" ], "summary": "Forward a stored message to another chat", "description": "An unknown `messageId` is a 422 with `errors.messageId`.\n\nThe 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\nSend endpoint: accepts `Idempotency-Key` and counts towards the workspace's optional daily API send limit.", "x-letsbot-send": true, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/Phone" }, "messageId": { "type": "string", "description": "`message_id` of a message stored in this workspace." } }, "required": [ "phone", "messageId" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "X-LetsBot-Automation-Limit": { "$ref": "#/components/headers/AutomationLimit" }, "X-LetsBot-Automation-Used": { "$ref": "#/components/headers/AutomationUsed" }, "X-LetsBot-Automation-Resets-At": { "$ref": "#/components/headers/AutomationResetsAt" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/SendConflict" }, "422": { "description": "Unprocessable: validation failed; the Idempotency-Key was already used for a different request; WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/SendTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/message/send/mention": { "post": { "operationId": "sendMention", "tags": [ "Messages" ], "summary": "Send a mention", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.\n\nSend endpoint: accepts `Idempotency-Key` and counts towards the workspace's optional daily API send limit.", "x-letsbot-send": true, "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/Phone" }, "mention": { "type": "string", "description": "Number to mention." } }, "required": [ "phone", "mention" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "X-LetsBot-Automation-Limit": { "$ref": "#/components/headers/AutomationLimit" }, "X-LetsBot-Automation-Used": { "$ref": "#/components/headers/AutomationUsed" }, "X-LetsBot-Automation-Resets-At": { "$ref": "#/components/headers/AutomationResetsAt" } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/SendConflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); the Idempotency-Key was already used for a different request; WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/SendTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/message/send/reaction": { "post": { "operationId": "sendReaction", "tags": [ "Messages" ], "summary": "React to a message", "description": "The reaction key is always sent with `fromMe: true` and `remoteJid` = `@s.whatsapp.net` (see the controller).\n\nThe 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.\n\nSend endpoint: accepts `Idempotency-Key` and counts towards the workspace's optional daily API send limit.", "x-letsbot-send": true, "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/PhoneDigits" }, "reaction": { "type": "string", "description": "Emoji, e.g. `👍`. An empty string removes a reaction." }, "messageId": { "type": "string", "description": "WhatsApp message id to react to." } }, "required": [ "phone", "reaction", "messageId" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "X-LetsBot-Automation-Limit": { "$ref": "#/components/headers/AutomationLimit" }, "X-LetsBot-Automation-Used": { "$ref": "#/components/headers/AutomationUsed" }, "X-LetsBot-Automation-Resets-At": { "$ref": "#/components/headers/AutomationResetsAt" } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/SendConflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); the Idempotency-Key was already used for a different request; WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/SendTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/message/send/reply": { "post": { "operationId": "sendReply", "tags": [ "Messages" ], "summary": "Reply to (quote) a message", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.\n\nSend endpoint: accepts `Idempotency-Key` and counts towards the workspace's optional daily API send limit.", "x-letsbot-send": true, "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/PhoneDigits" }, "body": { "type": "string" }, "messageId": { "type": "string", "description": "WhatsApp message id being quoted." } }, "required": [ "phone", "body", "messageId" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageResponse" } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "X-LetsBot-Automation-Limit": { "$ref": "#/components/headers/AutomationLimit" }, "X-LetsBot-Automation-Used": { "$ref": "#/components/headers/AutomationUsed" }, "X-LetsBot-Automation-Resets-At": { "$ref": "#/components/headers/AutomationResetsAt" } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/SendConflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); the Idempotency-Key was already used for a different request; WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/SendTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/message/send/sticker": { "post": { "operationId": "sendSticker", "tags": [ "Messages" ], "summary": "Send a sticker", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.\n\nSend endpoint: accepts `Idempotency-Key` and counts towards the workspace's optional daily API send limit.", "x-letsbot-send": true, "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/PhoneDigits" }, "url": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^[Hh][Tt][Tt][Pp][Ss]?://", "description": "Public http(s) URL the platform downloads server-side." } }, "required": [ "phone", "url" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "X-LetsBot-Automation-Limit": { "$ref": "#/components/headers/AutomationLimit" }, "X-LetsBot-Automation-Used": { "$ref": "#/components/headers/AutomationUsed" }, "X-LetsBot-Automation-Resets-At": { "$ref": "#/components/headers/AutomationResetsAt" } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/SendConflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); the Idempotency-Key was already used for a different request; WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/SendTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/messages": { "get": { "operationId": "index", "tags": [ "Archive" ], "summary": "Read the message archive by date (inbound and outbound)", "description": "Ordered oldest first by `message_date`, then `id`. Keep requesting with `cursor=` until `next_cursor` is `null`. Reactions, internal notes and system alerts are excluded. Reads the whole workspace, so one key returns the messages of every number and channel; `channel` names the channel when the row records it. Pass `channel_id` or `business_phone` to read one number only. WhatsApp messages record their number from 2026-09-30; older history does so only where it could be attributed without guessing (a workspace with a single WhatsApp number), and a row that records no number is never returned under a channel filter. An incoming message that started from a Click-to-WhatsApp ad carries that ad in `referral` (`ad_id`, `headline`, `ctwa_clid`, ...), so leads can be counted per ad.", "parameters": [ { "name": "date_from", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 40 }, "description": "`YYYY-MM-DD` (whole day) or an ISO-8601 datetime (exact, inclusive)." }, { "name": "date_to", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 40 }, "description": "`YYYY-MM-DD` (whole day, so `date_from=date_to` is one day) or an ISO-8601 datetime (exact, inclusive). Must not be before `date_from`." }, { "name": "timezone", "in": "query", "required": false, "schema": { "type": "string", "default": "UTC" }, "description": "IANA zone used to read bare dates and to format `message_date`." }, { "name": "from_me", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "0", "1", "true", "false" ] }, "description": "`1`/`true` outgoing only, `0`/`false` incoming only; omit for both." }, { "name": "sent_by", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/SentBy" } }, { "name": "phone", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 32 }, "description": "Only messages with this customer." }, { "name": "channel_id", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Only messages on this workspace channel — the `channel.id` a message or webhook reports. `422` when no channel with this id exists in the workspace." }, { "name": "business_phone", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only messages on the workspace's WhatsApp number with these digits, international format (`966501234567`; `+`, spaces and dashes are ignored). `422` when no WhatsApp number of the workspace matches. With `channel_id` too, both must name the same number." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "`next_cursor` from the previous page, unchanged." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchivePage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchiveValidationError" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/orders": { "post": { "operationId": "recordOrder", "tags": [ "Orders" ], "summary": "Record an order (order journey + invoice)", "description": "For merchants whose orders live in their own system (not Salla / Zid). Each recorded order starts the order journey: every active automation reminder on «Order placed» (/panel/v2/automation-reminders) goes to this customer N days after `ordered_at` (rating request, discount, marketing…). When the request carries `invoice_url` (https page) or `invoice_pdf_url` (https PDF) the invoice is sent at once, once per order, through the invoices templates (/panel/v2/invoices).\n\nRecording an order sends nothing by itself, so this is not a send endpoint. A customer who never wrote to the business is reached only on an official (Cloud API) number; `journey.reachable` tells you before the first reminder is due.\n\nValidation failures always answer HTTP 422 `{\"Status\": false, \"Message\": ..., \"errors\": {...}}`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "order_id": { "type": "string", "maxLength": 64, "pattern": "^[A-Za-z0-9._\\-]+$", "description": "Your order id. Used again by the cancel endpoint.", "examples": [ "ORD-1042" ] }, "phone": { "$ref": "#/components/schemas/Phone" }, "customer_name": { "type": "string", "maxLength": 191 }, "ordered_at": { "type": "string", "format": "date-time", "description": "Within the last 365 days and not in the future. Defaults to now." }, "total": { "type": "number", "minimum": 0 }, "currency": { "type": "string", "maxLength": 8, "examples": [ "SAR" ] }, "order_url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "https only." }, "store_name": { "type": "string", "maxLength": 191 }, "language": { "type": "string", "enum": [ "ar", "en", "es", "pt" ] }, "invoice_number": { "type": "string", "maxLength": 64 }, "invoice_url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "https invoice page; sends the invoice at once." }, "invoice_pdf_url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "https invoice PDF; sends the invoice at once." }, "products": { "type": "array", "maxItems": 20, "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 191 }, "url": { "type": "string", "format": "uri", "maxLength": 2048 } }, "required": [ "name" ] } } }, "required": [ "order_id", "phone" ] } } } }, "responses": { "201": { "description": "Order recorded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "Status": { "type": "boolean" }, "Message": { "type": "string" }, "order_id": { "type": "string" }, "journey": { "type": "object", "properties": { "recorded": { "type": "boolean" }, "ordered_at": { "type": "string", "format": "date-time" }, "reachable": { "type": "boolean", "description": "false = this customer never wrote to you and your number is QR-linked, so journey messages will not reach them." } } }, "invoice": { "type": "string", "enum": [ "not_requested", "sent", "skipped", "failed", "duplicate", "off" ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "No workspace is linked to this API key." }, "409": { "description": "The workspace is still being prepared. Try again in a few minutes." }, "422": { "description": "Validation failed (`{\"Status\": false, \"Message\": ..., \"errors\": {...}}`), or the phone is not a full international number, or `ordered_at` is out of range." }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "The order could not be recorded. Try again." }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/orders/{orderId}/cancel": { "post": { "operationId": "cancelOrder", "tags": [ "Orders" ], "summary": "Stop the order journey for a cancelled or refunded order", "description": "No further journey messages are sent for this order. Send the customer phone used when the order was recorded.", "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._\\-]{1,64}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/Phone" } }, "required": [ "phone" ] } } } }, "responses": { "200": { "description": "OK. `cancelled` is false when no open order matches this id and phone.", "content": { "application/json": { "schema": { "type": "object", "properties": { "Status": { "type": "boolean" }, "Message": { "type": "string" }, "cancelled": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "No workspace is linked to this API key." }, "422": { "description": "The phone is missing or not a full international number." }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/product": { "post": { "operationId": "getProducts", "tags": [ "Products" ], "summary": "List products", "description": "A read, but routed as POST.\n\nThe 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.", "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/Phone" } }, "required": [ "phone" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/product/create": { "post": { "operationId": "createProduct", "tags": [ "Products" ], "summary": "Create a product", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": "string" }, "price": { "type": "number", "description": "Truncated to an integer (`intval`) before it is sent." }, "currency": { "type": "string" }, "isHidden": { "type": [ "boolean", "integer", "string" ] }, "images": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } } } } }, "required": [ "name", "description", "price", "currency", "isHidden", "images" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed; WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/product/get/collections": { "post": { "operationId": "getCollections", "tags": [ "Products" ], "summary": "List catalog collections", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.", "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/Phone" } }, "required": [ "phone" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/product/get/order": { "post": { "operationId": "getOrder", "tags": [ "Products" ], "summary": "Get an order", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.", "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "orderId": { "type": [ "integer", "string" ], "description": "Numeric order id. Note the casing: `orderId`." }, "orderToken": { "type": "string" } }, "required": [ "orderId", "orderToken" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/product/id": { "get": { "operationId": "getProduct", "tags": [ "Products" ], "summary": "Get a product", "description": "No validation: parameters are passed to the gateway as given.\n\nThe 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.", "parameters": [ { "name": "phone", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Phone" } }, { "name": "productId", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetaRejection" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/qr": { "post": { "operationId": "qr", "tags": [ "Session" ], "summary": "Get the QR code to link a number", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetaRejection" } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/send/audio": { "post": { "operationId": "sendAudio", "tags": [ "Media" ], "summary": "Send an audio file by URL", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.\n\nSend endpoint: accepts `Idempotency-Key` and counts towards the workspace's optional daily API send limit.", "x-letsbot-send": true, "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/PhoneDigits" }, "audio": { "type": "string", "format": "uri", "description": "Public URL of the audio file. On official channels a value that is not a valid URL is silently not sent." } }, "required": [ "phone", "audio" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "X-LetsBot-Automation-Limit": { "$ref": "#/components/headers/AutomationLimit" }, "X-LetsBot-Automation-Used": { "$ref": "#/components/headers/AutomationUsed" }, "X-LetsBot-Automation-Resets-At": { "$ref": "#/components/headers/AutomationResetsAt" } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/SendConflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); the Idempotency-Key was already used for a different request; WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/SendTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/send/buttons": { "post": { "operationId": "sendButtonsAlias", "tags": [ "Interactive" ], "summary": "Send a buttons message", "description": "Alias of `POST /button`: same controller action and body.\n\nThe 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.\n\nSend endpoint: accepts `Idempotency-Key` and counts towards the workspace's optional daily API send limit.", "x-letsbot-send": true, "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/Phone" }, "body": { "type": "string" }, "title": { "type": "string" }, "footer": { "type": "string" }, "buttons": { "type": "array", "items": { "$ref": "#/components/schemas/Button" }, "minItems": 1 }, "caption": { "type": "string" } }, "required": [ "phone", "body", "title", "footer", "buttons" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "X-LetsBot-Automation-Limit": { "$ref": "#/components/headers/AutomationLimit" }, "X-LetsBot-Automation-Used": { "$ref": "#/components/headers/AutomationUsed" }, "X-LetsBot-Automation-Resets-At": { "$ref": "#/components/headers/AutomationResetsAt" } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/SendConflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); the Idempotency-Key was already used for a different request; WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/SendTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/send/contact": { "post": { "operationId": "sendContact", "tags": [ "Media" ], "summary": "Send a contact card", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.\n\nSend endpoint: accepts `Idempotency-Key` and counts towards the workspace's optional daily API send limit.", "x-letsbot-send": true, "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/PhoneDigits" }, "contact": { "type": "string", "description": "Phone number of the contact being shared." }, "name": { "type": "string", "description": "Display name on the card." }, "description": { "type": "string" } }, "required": [ "phone", "contact", "name" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "X-LetsBot-Automation-Limit": { "$ref": "#/components/headers/AutomationLimit" }, "X-LetsBot-Automation-Used": { "$ref": "#/components/headers/AutomationUsed" }, "X-LetsBot-Automation-Resets-At": { "$ref": "#/components/headers/AutomationResetsAt" } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/SendConflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); the Idempotency-Key was already used for a different request; WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/SendTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/send/file": { "post": { "operationId": "sendFile", "tags": [ "Media" ], "summary": "Send a file (document) by URL", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.\n\nSend endpoint: accepts `Idempotency-Key` and counts towards the workspace's optional daily API send limit.", "x-letsbot-send": true, "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/PhoneDigits" }, "url": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^[Hh][Tt][Tt][Pp][Ss]?://", "description": "Public http(s) URL the platform downloads server-side." } }, "required": [ "phone", "url" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "X-LetsBot-Automation-Limit": { "$ref": "#/components/headers/AutomationLimit" }, "X-LetsBot-Automation-Used": { "$ref": "#/components/headers/AutomationUsed" }, "X-LetsBot-Automation-Resets-At": { "$ref": "#/components/headers/AutomationResetsAt" } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/SendConflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); the Idempotency-Key was already used for a different request; WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/SendTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/send/gif": { "post": { "operationId": "sendGif", "tags": [ "Media" ], "summary": "Send a GIF (video) by URL", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.\n\nSend endpoint: accepts `Idempotency-Key` and counts towards the workspace's optional daily API send limit.", "x-letsbot-send": true, "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/PhoneDigits" }, "url": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^[Hh][Tt][Tt][Pp][Ss]?://", "description": "Public http(s) URL the platform downloads server-side." }, "caption": { "type": "string" } }, "required": [ "phone", "url", "caption" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "X-LetsBot-Automation-Limit": { "$ref": "#/components/headers/AutomationLimit" }, "X-LetsBot-Automation-Used": { "$ref": "#/components/headers/AutomationUsed" }, "X-LetsBot-Automation-Resets-At": { "$ref": "#/components/headers/AutomationResetsAt" } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/SendConflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); the Idempotency-Key was already used for a different request; WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/SendTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/send/image": { "post": { "operationId": "sendImage", "tags": [ "Media" ], "summary": "Send an image by URL", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.\n\nSend endpoint: accepts `Idempotency-Key` and counts towards the workspace's optional daily API send limit.", "x-letsbot-send": true, "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/PhoneDigits" }, "url": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^[Hh][Tt][Tt][Pp][Ss]?://", "description": "Public http(s) URL the platform downloads server-side." }, "caption": { "type": "string" } }, "required": [ "phone", "url", "caption" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "X-LetsBot-Automation-Limit": { "$ref": "#/components/headers/AutomationLimit" }, "X-LetsBot-Automation-Used": { "$ref": "#/components/headers/AutomationUsed" }, "X-LetsBot-Automation-Resets-At": { "$ref": "#/components/headers/AutomationResetsAt" } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/SendConflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); the Idempotency-Key was already used for a different request; WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/SendTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/send/location": { "post": { "operationId": "sendLocation", "tags": [ "Media" ], "summary": "Send a location", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.\n\nSend endpoint: accepts `Idempotency-Key` and counts towards the workspace's optional daily API send limit.", "x-letsbot-send": true, "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/PhoneDigits" }, "lat": { "type": [ "number", "string" ], "description": "Decimal degrees." }, "lng": { "type": [ "number", "string" ], "description": "Decimal degrees." } }, "required": [ "phone", "lat", "lng" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "X-LetsBot-Automation-Limit": { "$ref": "#/components/headers/AutomationLimit" }, "X-LetsBot-Automation-Used": { "$ref": "#/components/headers/AutomationUsed" }, "X-LetsBot-Automation-Resets-At": { "$ref": "#/components/headers/AutomationResetsAt" } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/SendConflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); the Idempotency-Key was already used for a different request; WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/SendTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/send/ptt": { "post": { "operationId": "sendPTT", "tags": [ "Media" ], "summary": "Send a voice note (push-to-talk) by URL", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.\n\nSend endpoint: accepts `Idempotency-Key` and counts towards the workspace's optional daily API send limit.", "x-letsbot-send": true, "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/PhoneDigits" }, "url": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^[Hh][Tt][Tt][Pp][Ss]?://", "description": "Public http(s) URL the platform downloads server-side." } }, "required": [ "phone", "url" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "X-LetsBot-Automation-Limit": { "$ref": "#/components/headers/AutomationLimit" }, "X-LetsBot-Automation-Used": { "$ref": "#/components/headers/AutomationUsed" }, "X-LetsBot-Automation-Resets-At": { "$ref": "#/components/headers/AutomationResetsAt" } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/SendConflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); the Idempotency-Key was already used for a different request; WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/SendTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/send/video": { "post": { "operationId": "sendVideo", "tags": [ "Media" ], "summary": "Send a video by URL", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.\n\nSend endpoint: accepts `Idempotency-Key` and counts towards the workspace's optional daily API send limit.", "x-letsbot-send": true, "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/PhoneDigits" }, "url": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^[Hh][Tt][Tt][Pp][Ss]?://", "description": "Public http(s) URL the platform downloads server-side." }, "caption": { "type": "string" } }, "required": [ "phone", "url", "caption" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "X-LetsBot-Automation-Limit": { "$ref": "#/components/headers/AutomationLimit" }, "X-LetsBot-Automation-Used": { "$ref": "#/components/headers/AutomationUsed" }, "X-LetsBot-Automation-Resets-At": { "$ref": "#/components/headers/AutomationResetsAt" } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/SendConflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); the Idempotency-Key was already used for a different request; WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/SendTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/session/find": { "post": { "operationId": "findSession", "tags": [ "Session" ], "summary": "Find the session", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetaRejection" } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/session/status": { "post": { "operationId": "sessionStatus", "tags": [ "Session" ], "summary": "Get the session status", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetaRejection" } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/share/catalog": { "post": { "operationId": "shareCatalog", "tags": [ "Media" ], "summary": "Share a catalog", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.\n\nSend endpoint: accepts `Idempotency-Key` and counts towards the workspace's optional daily API send limit.", "x-letsbot-send": true, "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/Phone" }, "catalog": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" }, "description": { "type": "string" } }, "required": [ "phone", "catalog" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "X-LetsBot-Automation-Limit": { "$ref": "#/components/headers/AutomationLimit" }, "X-LetsBot-Automation-Used": { "$ref": "#/components/headers/AutomationUsed" }, "X-LetsBot-Automation-Resets-At": { "$ref": "#/components/headers/AutomationResetsAt" } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/SendConflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); the Idempotency-Key was already used for a different request; WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/SendTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/template/document": { "post": { "operationId": "sendTemplateWithDocument", "tags": [ "Templates" ], "summary": "Send a template with a document header", "description": "Official (Cloud API) channels only: any other channel gets 400. Media-card carousel templates are refused with 422.\n\nThe 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\nSend endpoint: accepts `Idempotency-Key` and counts towards the workspace's optional daily API send limit.", "x-letsbot-send": true, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "Recipient, international format." }, "template_name": { "type": "string", "maxLength": 512 }, "template_language": { "type": "string", "maxLength": 10, "description": "e.g. `ar`, `en_US`." }, "components": { "$ref": "#/components/schemas/TemplateComponents" } }, "required": [ "phone", "template_name", "template_language" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "X-LetsBot-Automation-Limit": { "$ref": "#/components/headers/AutomationLimit" }, "X-LetsBot-Automation-Used": { "$ref": "#/components/headers/AutomationUsed" }, "X-LetsBot-Automation-Resets-At": { "$ref": "#/components/headers/AutomationResetsAt" } } }, "400": { "description": "The channel is not an official (Cloud API) WhatsApp channel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateRefusal" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/SendConflict" }, "422": { "description": "Unprocessable: validation failed; the template is a media-card carousel, which the API cannot send; the Idempotency-Key was already used for a different request; WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TemplateValidationError" }, { "$ref": "#/components/schemas/TemplateRefusal" }, { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/SendTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/template/image": { "post": { "operationId": "sendTemplateWithImage", "tags": [ "Templates" ], "summary": "Send a template with an image header", "description": "Official (Cloud API) channels only: any other channel gets 400. Media-card carousel templates are refused with 422.\n\nThe 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\nSend endpoint: accepts `Idempotency-Key` and counts towards the workspace's optional daily API send limit.", "x-letsbot-send": true, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "Recipient, international format." }, "template_name": { "type": "string", "maxLength": 512 }, "template_language": { "type": "string", "maxLength": 10, "description": "e.g. `ar`, `en_US`." }, "components": { "$ref": "#/components/schemas/TemplateComponents" } }, "required": [ "phone", "template_name", "template_language" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "X-LetsBot-Automation-Limit": { "$ref": "#/components/headers/AutomationLimit" }, "X-LetsBot-Automation-Used": { "$ref": "#/components/headers/AutomationUsed" }, "X-LetsBot-Automation-Resets-At": { "$ref": "#/components/headers/AutomationResetsAt" } } }, "400": { "description": "The channel is not an official (Cloud API) WhatsApp channel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateRefusal" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/SendConflict" }, "422": { "description": "Unprocessable: validation failed; the template is a media-card carousel, which the API cannot send; the Idempotency-Key was already used for a different request; WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TemplateValidationError" }, { "$ref": "#/components/schemas/TemplateRefusal" }, { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/SendTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/template/send": { "post": { "operationId": "sendWhatsAppTemplate", "tags": [ "Templates" ], "summary": "Send a template message (full featured)", "description": "Official (Cloud API) channels only: any other channel gets 400. Media-card carousel templates are refused with 422.\n\nThe 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\nSend endpoint: accepts `Idempotency-Key` and counts towards the workspace's optional daily API send limit.", "x-letsbot-send": true, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "Recipient, international format." }, "template_name": { "type": "string", "maxLength": 512 }, "template_language": { "type": "string", "maxLength": 10, "description": "e.g. `ar`, `en_US`." }, "components": { "$ref": "#/components/schemas/TemplateComponents" } }, "required": [ "phone", "template_name", "template_language" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "X-LetsBot-Automation-Limit": { "$ref": "#/components/headers/AutomationLimit" }, "X-LetsBot-Automation-Used": { "$ref": "#/components/headers/AutomationUsed" }, "X-LetsBot-Automation-Resets-At": { "$ref": "#/components/headers/AutomationResetsAt" } } }, "400": { "description": "The channel is not an official (Cloud API) WhatsApp channel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateRefusal" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/SendConflict" }, "422": { "description": "Unprocessable: validation failed; the template is a media-card carousel, which the API cannot send; the Idempotency-Key was already used for a different request; WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TemplateValidationError" }, { "$ref": "#/components/schemas/TemplateRefusal" }, { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/SendTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/template/simple": { "post": { "operationId": "sendSimpleTemplate", "tags": [ "Templates" ], "summary": "Send a body-only template", "description": "Official (Cloud API) channels only: any other channel gets 400. Media-card carousel templates are refused with 422. Only `components.body` is sent; other components are ignored.\n\nThe 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\nSend endpoint: accepts `Idempotency-Key` and counts towards the workspace's optional daily API send limit.", "x-letsbot-send": true, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "Recipient, international format." }, "template_name": { "type": "string", "maxLength": 512 }, "template_language": { "type": "string", "maxLength": 10, "description": "e.g. `ar`, `en_US`." }, "components": { "$ref": "#/components/schemas/TemplateComponents" } }, "required": [ "phone", "template_name", "template_language" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "X-LetsBot-Automation-Limit": { "$ref": "#/components/headers/AutomationLimit" }, "X-LetsBot-Automation-Used": { "$ref": "#/components/headers/AutomationUsed" }, "X-LetsBot-Automation-Resets-At": { "$ref": "#/components/headers/AutomationResetsAt" } } }, "400": { "description": "The channel is not an official (Cloud API) WhatsApp channel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateRefusal" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/SendConflict" }, "422": { "description": "Unprocessable: validation failed; the template is a media-card carousel, which the API cannot send; the Idempotency-Key was already used for a different request; WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TemplateValidationError" }, { "$ref": "#/components/schemas/TemplateRefusal" }, { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/SendTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/template/video": { "post": { "operationId": "sendTemplateWithVideo", "tags": [ "Templates" ], "summary": "Send a template with a video header", "description": "Official (Cloud API) channels only: any other channel gets 400. Media-card carousel templates are refused with 422.\n\nThe 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\nSend endpoint: accepts `Idempotency-Key` and counts towards the workspace's optional daily API send limit.", "x-letsbot-send": true, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "Recipient, international format." }, "template_name": { "type": "string", "maxLength": 512 }, "template_language": { "type": "string", "maxLength": 10, "description": "e.g. `ar`, `en_US`." }, "components": { "$ref": "#/components/schemas/TemplateComponents" } }, "required": [ "phone", "template_name", "template_language" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "X-LetsBot-Automation-Limit": { "$ref": "#/components/headers/AutomationLimit" }, "X-LetsBot-Automation-Used": { "$ref": "#/components/headers/AutomationUsed" }, "X-LetsBot-Automation-Resets-At": { "$ref": "#/components/headers/AutomationResetsAt" } } }, "400": { "description": "The channel is not an official (Cloud API) WhatsApp channel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateRefusal" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/SendConflict" }, "422": { "description": "Unprocessable: validation failed; the template is a media-card carousel, which the API cannot send; the Idempotency-Key was already used for a different request; WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TemplateValidationError" }, { "$ref": "#/components/schemas/TemplateRefusal" }, { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/SendTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/user/block": { "post": { "operationId": "blockUser", "tags": [ "User" ], "summary": "Block a number", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.", "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/Phone" } }, "required": [ "phone" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/user/business": { "post": { "operationId": "userBusinessProfile", "tags": [ "User" ], "summary": "Get a number's business profile", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.", "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/Phone" } }, "required": [ "phone" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/user/display/picture": { "get": { "operationId": "userDisplayPicture", "tags": [ "User" ], "summary": "Get a number's profile picture", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.", "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" }, { "name": "phone", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/Phone" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/user/presence": { "post": { "operationId": "userPresence", "tags": [ "User" ], "summary": "Get a number's presence", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.", "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/Phone" } }, "required": [ "phone" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/user/set/display/picture": { "post": { "operationId": "setDisplayPicture", "tags": [ "User" ], "summary": "Set this number's profile picture", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.", "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/Phone", "description": "Required by validation but not used: the picture is set on the connected number." }, "image": { "type": "string", "format": "uri", "description": "Public URL (Laravel `url` rule)." } }, "required": [ "phone", "image" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/user/set/name": { "post": { "operationId": "setProfileName", "tags": [ "User" ], "summary": "Set the profile name", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.", "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/PhoneDigits" }, "name": { "type": "string" } }, "required": [ "phone", "name" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/user/set/status": { "post": { "operationId": "setUserStatus", "tags": [ "User" ], "summary": "Set this number's status (about)", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.", "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/user/status": { "post": { "operationId": "userStatus", "tags": [ "User" ], "summary": "Get a number's status (about)", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.", "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/Phone" } }, "required": [ "phone" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/user/unblock": { "post": { "operationId": "unblockUser", "tags": [ "User" ], "summary": "Unblock a number", "description": "The 200 body is the connection gateway's answer passed through as-is; its exact shape differs between official (Cloud API) and QR-linked channels. Check `success`.\n\n**Validation failures answer HTTP 202** with `{\"Status\": 0, \"Message\": ...}` by default (historic contract). Send `X-LetsBot-Validation: strict` (recommended) or `Prefer: validation=strict` to get HTTP 422 `{\"message\": ..., \"errors\": {...}}` instead.", "x-letsbot-validation": { "default": 202, "strict": 422, "strict-headers": [ "X-LetsBot-Validation: strict", "Prefer: validation=strict" ] }, "parameters": [ { "$ref": "#/components/parameters/ValidationMode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "$ref": "#/components/schemas/Phone" } }, "required": [ "phone" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponse" } } } }, "202": { "$ref": "#/components/responses/LegacyValidationFailure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Unprocessable: validation failed, in strict mode only (`X-LetsBot-Validation: strict`; `LaravelValidationError`); WhatsApp refused the request for a reason the caller must fix.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LaravelValidationError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "423": { "$ref": "#/components/responses/WritesLocked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/LifecycleUnavailable" } } } }, "/user": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "zapierAuthTest", "tags": [ "Zapier integration" ], "summary": "Test the connection (who am I)", "description": "Any valid credential (no scope).", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "responses": { "200": { "description": "The whitelisted profile of the key owner (used as the connection label).", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "locale": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "locale" ] } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" } } } }, "/zapier-integration/notify": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "zapierNotify", "tags": [ "Zapier integration" ], "summary": "Notify yourself with a notification template", "description": "Scope: `notify_self`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "description": "Slug of an active notification template (`events`)." }, "message": { "type": [ "string", "null" ] } }, "required": [ "event" ] } } } }, "responses": { "200": { "description": "Queued.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "automation_budget": { "$ref": "#/components/schemas/ZapierAutomationBudget" } }, "required": [ "success" ] } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" }, "422": { "$ref": "#/components/responses/ZapierFailure" } } } }, "/zapier-integration/notify-phone": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "zapierNotifyPhone", "tags": [ "Zapier integration" ], "summary": "Send a notification template to a phone", "description": "Scope: `notify_phone`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "International format, digits only (e.g. 966501234567)." }, "event": { "type": "string" }, "message": { "type": [ "string", "null" ] } }, "required": [ "phone", "event" ] } } } }, "responses": { "200": { "description": "Queued.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "automation_budget": { "$ref": "#/components/schemas/ZapierAutomationBudget" } }, "required": [ "success" ] } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" }, "422": { "$ref": "#/components/responses/ZapierFailure" } } } }, "/zapier-integration/events": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "zapierEvents", "tags": [ "Zapier integration" ], "summary": "List notification template slugs", "description": "Scope: `read_events`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "responses": { "200": { "description": "OK — a bare JSON array (Zapier performList).", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" } } } }, "/zapier-integration/webhooks/subscribe": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "zapierSubscribe", "tags": [ "Zapier integration" ], "summary": "Subscribe a webhook (REST hook trigger)", "description": "Scope: `manage_subscriptions`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "hookUrl": { "type": "string", "description": "Public HTTPS URL only.", "format": "uri" }, "trigger": { "allOf": [ { "$ref": "#/components/schemas/ZapierTrigger" } ], "description": "Default `new_message_received`." }, "name": { "type": "string", "maxLength": 120 }, "filter": { "type": "string", "description": "Legacy substring filter.", "maxLength": 500 }, "event_filters": { "type": "object", "description": "Per-trigger filters, e.g. `{\"stage_id\": 3}` or `{\"label_id\": 5}`.", "additionalProperties": true }, "source": { "type": "string", "enum": [ "zapier", "make", "n8n", "custom" ], "description": "Which client created it (stored only for workspaces on the integrations area)." } }, "required": [ "hookUrl" ] } } } }, "responses": { "201": { "description": "Created (or re-activated: upsert on trigger + hookUrl + key owner). `secret` signs every delivery: `X-Zapier-Signature: sha256=`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "trigger": { "$ref": "#/components/schemas/ZapierTrigger" }, "url": { "type": "string", "format": "uri" }, "secret": { "type": "string" } }, "required": [ "id", "trigger", "url", "secret" ] } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" }, "422": { "$ref": "#/components/responses/ZapierFailure" } } } }, "/zapier-integration/webhooks/unsubscribe/{id}": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "delete": { "operationId": "zapierUnsubscribe", "tags": [ "Zapier integration" ], "summary": "Unsubscribe a webhook", "description": "Scope: `manage_subscriptions`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Removed (also for an unknown or not-owned id)." }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" } } } }, "/zapier-integration/messages": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "zapierPollMessages", "tags": [ "Zapier integration" ], "summary": "Poll inbound messages", "description": "Scope: `poll_messages`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "parameters": [ { "name": "since", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Return rows with id greater than this cursor." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Default 20, capped at 100." } ], "responses": { "200": { "description": "OK — a bare JSON array (Zapier performList).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ZapierMessage" } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" } } } }, "/zapier-integration/contacts": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "zapierPollContacts", "tags": [ "Zapier integration" ], "summary": "Poll contacts", "description": "Scope: `poll_contacts`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "parameters": [ { "name": "since", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Return rows with id greater than this cursor." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Default 20, capped at 100." } ], "responses": { "200": { "description": "OK — a bare JSON array (Zapier performList).", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "chat_id": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] } } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" } } } }, "/zapier-integration/orders": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "zapierPollOrders", "tags": [ "Zapier integration" ], "summary": "Poll store orders (Salla, Zid, WooCommerce)", "description": "Scope: `poll_orders`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "parameters": [ { "name": "since", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Composite cursor (`_`)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Default 20, capped at 100." } ], "responses": { "200": { "description": "OK — a bare JSON array (Zapier performList).", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "order_id": { "type": "string" }, "source": { "type": "string" }, "status": { "type": "string" }, "total": {}, "currency": {}, "customer_phone": {}, "customer_name": {}, "created_at": { "type": [ "string", "null" ] } } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" } } } }, "/zapier-integration/conversations": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "zapierPollConversations", "tags": [ "Zapier integration" ], "summary": "Poll conversations", "description": "Scope: `poll_messages`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "parameters": [ { "name": "since", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Return rows with id greater than this cursor." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Default 20, capped at 100." } ], "responses": { "200": { "description": "OK — a bare JSON array (Zapier performList).", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "integer" }, "chat_id": { "type": "string" }, "contact_id": { "type": "integer" }, "phone": { "type": "string" }, "name": { "type": "string" }, "agent_id": { "type": [ "integer", "null" ] }, "is_archived": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ] } } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" } } } }, "/zapier-integration/samples/{trigger}": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "zapierSample", "tags": [ "Zapier integration" ], "summary": "Sample payload of a trigger", "description": "Scope: `read_events`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "parameters": [ { "name": "trigger", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ZapierTrigger" } } ], "responses": { "200": { "description": "The payload a real delivery of this trigger carries (flat object, shape per trigger).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" }, "404": { "description": "Unknown trigger.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/zapier-integration/actions/send-text": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "zapierSendText", "tags": [ "Zapier integration" ], "summary": "Send a text message", "description": "Scope: `send_text`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "International format, digits only (e.g. 966501234567)." }, "message": { "type": "string" }, "channel_id": { "type": "integer", "description": "Optional. Send from this channel (an id from `lookup/channels`) instead of the workspace's oldest channel. Omitted, null or empty: the oldest channel, as before. An id that is not one of this workspace's channels answers 422 `channel_not_found` and sends nothing." } }, "required": [ "phone", "message" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "endpoint": { "type": "string" }, "queued_at": { "type": "string", "format": "date-time" }, "pricing_estimate": { "type": "object", "description": "Only when the workspace enabled cost estimates.", "additionalProperties": true }, "automation_budget": { "$ref": "#/components/schemas/ZapierAutomationBudget" } }, "required": [ "endpoint", "queued_at" ] } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" }, "422": { "$ref": "#/components/responses/ZapierFailure" } } } }, "/zapier-integration/actions/send-image": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "zapierSendImage", "tags": [ "Zapier integration" ], "summary": "Send an image", "description": "Scope: `send_media`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "International format, digits only (e.g. 966501234567)." }, "url": { "type": "string", "format": "uri" }, "caption": { "type": [ "string", "null" ] } }, "required": [ "phone", "url" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "endpoint": { "type": "string" }, "queued_at": { "type": "string", "format": "date-time" }, "pricing_estimate": { "type": "object", "description": "Only when the workspace enabled cost estimates.", "additionalProperties": true }, "automation_budget": { "$ref": "#/components/schemas/ZapierAutomationBudget" } }, "required": [ "endpoint", "queued_at" ] } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" }, "422": { "$ref": "#/components/responses/ZapierFailure" } } } }, "/zapier-integration/actions/send-video": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "zapierSendVideo", "tags": [ "Zapier integration" ], "summary": "Send a video", "description": "Scope: `send_media`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "International format, digits only (e.g. 966501234567)." }, "url": { "type": "string", "format": "uri" }, "caption": { "type": [ "string", "null" ] } }, "required": [ "phone", "url" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "endpoint": { "type": "string" }, "queued_at": { "type": "string", "format": "date-time" }, "pricing_estimate": { "type": "object", "description": "Only when the workspace enabled cost estimates.", "additionalProperties": true }, "automation_budget": { "$ref": "#/components/schemas/ZapierAutomationBudget" } }, "required": [ "endpoint", "queued_at" ] } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" }, "422": { "$ref": "#/components/responses/ZapierFailure" } } } }, "/zapier-integration/actions/send-audio": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "zapierSendAudio", "tags": [ "Zapier integration" ], "summary": "Send an audio file", "description": "Scope: `send_media`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "International format, digits only (e.g. 966501234567)." }, "url": { "type": "string", "format": "uri" } }, "required": [ "phone", "url" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "endpoint": { "type": "string" }, "queued_at": { "type": "string", "format": "date-time" }, "pricing_estimate": { "type": "object", "description": "Only when the workspace enabled cost estimates.", "additionalProperties": true }, "automation_budget": { "$ref": "#/components/schemas/ZapierAutomationBudget" } }, "required": [ "endpoint", "queued_at" ] } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" }, "422": { "$ref": "#/components/responses/ZapierFailure" } } } }, "/zapier-integration/actions/send-file": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "zapierSendFile", "tags": [ "Zapier integration" ], "summary": "Send a document", "description": "Scope: `send_media`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "International format, digits only (e.g. 966501234567)." }, "url": { "type": "string", "format": "uri" }, "name": { "type": [ "string", "null" ] }, "caption": { "type": [ "string", "null" ] } }, "required": [ "phone", "url" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "endpoint": { "type": "string" }, "queued_at": { "type": "string", "format": "date-time" }, "pricing_estimate": { "type": "object", "description": "Only when the workspace enabled cost estimates.", "additionalProperties": true }, "automation_budget": { "$ref": "#/components/schemas/ZapierAutomationBudget" } }, "required": [ "endpoint", "queued_at" ] } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" }, "422": { "$ref": "#/components/responses/ZapierFailure" } } } }, "/zapier-integration/actions/send-location": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "zapierSendLocation", "tags": [ "Zapier integration" ], "summary": "Send a location", "description": "Scope: `send_media`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "International format, digits only (e.g. 966501234567)." }, "lat": { "type": "number" }, "lng": { "type": "number" }, "name": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] } }, "required": [ "phone", "lat", "lng" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "endpoint": { "type": "string" }, "queued_at": { "type": "string", "format": "date-time" }, "pricing_estimate": { "type": "object", "description": "Only when the workspace enabled cost estimates.", "additionalProperties": true }, "automation_budget": { "$ref": "#/components/schemas/ZapierAutomationBudget" } }, "required": [ "endpoint", "queued_at" ] } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" }, "422": { "$ref": "#/components/responses/ZapierFailure" } } } }, "/zapier-integration/actions/send-reaction": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "zapierSendReaction", "tags": [ "Zapier integration" ], "summary": "React to a message", "description": "Scope: `send_text`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "International format, digits only (e.g. 966501234567)." }, "message_id": { "type": "string" }, "reaction": { "type": "string" } }, "required": [ "phone", "message_id", "reaction" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "endpoint": { "type": "string" }, "queued_at": { "type": "string", "format": "date-time" }, "pricing_estimate": { "type": "object", "description": "Only when the workspace enabled cost estimates.", "additionalProperties": true }, "automation_budget": { "$ref": "#/components/schemas/ZapierAutomationBudget" } }, "required": [ "endpoint", "queued_at" ] } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" }, "422": { "$ref": "#/components/responses/ZapierFailure" } } } }, "/zapier-integration/actions/send-template": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "zapierSendTemplate", "tags": [ "Zapier integration" ], "summary": "Send a notification template", "description": "Scope: `send_template`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "International format, digits only (e.g. 966501234567)." }, "slug": { "type": "string", "description": "An active template slug (`lookup/templates`)." }, "variables": { "type": "object", "additionalProperties": true }, "header_media_url": { "type": "string", "description": "https only; the template must have an approved media header.", "format": "uri" }, "header_media_filename": { "type": "string", "maxLength": 240 }, "channel_id": { "type": "integer", "description": "Optional. Send from this channel (an id from `lookup/channels`) instead of the workspace's oldest channel. Omitted, null or empty: the oldest channel, as before. An id that is not one of this workspace's channels answers 422 `channel_not_found` and sends nothing." } }, "required": [ "phone", "slug" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "template_id": { "type": "integer" }, "slug": { "type": "string" }, "log_id": { "type": [ "integer", "null" ] }, "automation_budget": { "$ref": "#/components/schemas/ZapierAutomationBudget" } }, "required": [ "template_id", "slug", "log_id" ] } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" }, "404": { "$ref": "#/components/responses/ZapierFailure" }, "422": { "$ref": "#/components/responses/ZapierFailure" } } } }, "/zapier-integration/actions/contacts": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "zapierUpsertContact", "tags": [ "Zapier integration" ], "summary": "Create or update a contact (by phone)", "description": "Scope: `create_contact`. An absent or empty `name` / `email` keeps the value already stored (it used to overwrite it with null).", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "International format, digits only (e.g. 966501234567)." }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" }, "custom_fields": { "type": "object", "description": "`{field_key: value}`. Each value is stored through the same write point and coercion as `contacts/update-field`. Best-effort per field: an unknown key, a value the field's type rejects, a list or object value, or an empty value is skipped (never cleared) without failing the upsert. Use `contacts/update-field` for a strict per-field answer or to clear a field.", "additionalProperties": true } }, "required": [ "phone" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "phone": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "created": { "type": "boolean" } }, "required": [ "id", "phone", "name", "email", "created" ] } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" }, "422": { "$ref": "#/components/responses/ZapierFailure" } } } }, "/zapier-integration/actions/contacts/find-by-phone": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "zapierFindContactByPhone", "tags": [ "Zapier integration" ], "summary": "Find a contact by phone", "description": "Scope: `poll_contacts`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "parameters": [ { "name": "phone", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "phone": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" }, "404": { "$ref": "#/components/responses/ZapierFailure" } } } }, "/zapier-integration/actions/contacts/find-by-email": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "zapierFindContactByEmail", "tags": [ "Zapier integration" ], "summary": "Find a contact by email", "description": "Scope: `poll_contacts`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "parameters": [ { "name": "email", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "phone": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" }, "404": { "$ref": "#/components/responses/ZapierFailure" } } } }, "/zapier-integration/actions/contacts/archive": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "zapierArchiveContact", "tags": [ "Zapier integration" ], "summary": "Archive a contact", "description": "Scope: `update_contact`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "International format, digits only (e.g. 966501234567)." } }, "required": [ "phone" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "phone": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" }, "404": { "$ref": "#/components/responses/ZapierFailure" }, "422": { "$ref": "#/components/responses/ZapierFailure" } } } }, "/zapier-integration/actions/contacts/unarchive": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "zapierUnarchiveContact", "tags": [ "Zapier integration" ], "summary": "Unarchive a contact", "description": "Scope: `update_contact`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "International format, digits only (e.g. 966501234567)." } }, "required": [ "phone" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "phone": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" }, "404": { "$ref": "#/components/responses/ZapierFailure" }, "422": { "$ref": "#/components/responses/ZapierFailure" } } } }, "/zapier-integration/actions/contacts/block": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "zapierBlockContact", "tags": [ "Zapier integration" ], "summary": "Block a contact", "description": "Scope: `update_contact`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "International format, digits only (e.g. 966501234567)." } }, "required": [ "phone" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "phone": { "type": [ "string", "null" ] }, "blocked": { "type": "boolean" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" }, "404": { "$ref": "#/components/responses/ZapierFailure" }, "422": { "$ref": "#/components/responses/ZapierFailure" } } } }, "/zapier-integration/actions/contacts/unblock": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "zapierUnblockContact", "tags": [ "Zapier integration" ], "summary": "Unblock a contact", "description": "Scope: `update_contact`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "International format, digits only (e.g. 966501234567)." } }, "required": [ "phone" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "phone": { "type": [ "string", "null" ] }, "blocked": { "type": "boolean" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" }, "404": { "$ref": "#/components/responses/ZapierFailure" }, "422": { "$ref": "#/components/responses/ZapierFailure" } } } }, "/zapier-integration/actions/contacts/pin": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "zapierPinContact", "tags": [ "Zapier integration" ], "summary": "Pin a contact", "description": "Scope: `update_contact`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "International format, digits only (e.g. 966501234567)." } }, "required": [ "phone" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "phone": { "type": [ "string", "null" ] }, "pinned": { "type": "boolean" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" }, "404": { "$ref": "#/components/responses/ZapierFailure" }, "422": { "$ref": "#/components/responses/ZapierFailure" } } } }, "/zapier-integration/actions/contacts/unpin": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "zapierUnpinContact", "tags": [ "Zapier integration" ], "summary": "Unpin a contact", "description": "Scope: `update_contact`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "International format, digits only (e.g. 966501234567)." } }, "required": [ "phone" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "phone": { "type": [ "string", "null" ] }, "pinned": { "type": "boolean" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" }, "404": { "$ref": "#/components/responses/ZapierFailure" }, "422": { "$ref": "#/components/responses/ZapierFailure" } } } }, "/zapier-integration/actions/contacts/add-label": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "zapierAddLabel", "tags": [ "Zapier integration" ], "summary": "Add a label to a contact (label_id or label_name)", "description": "Scope: `manage_labels`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "International format, digits only (e.g. 966501234567)." }, "label_id": { "type": [ "integer", "null" ] }, "label_name": { "type": [ "string", "null" ] } }, "required": [ "phone" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "phone": { "type": [ "string", "null" ] }, "label_id": { "type": "integer" }, "label": { "type": "string" }, "added": { "type": "boolean" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" }, "404": { "$ref": "#/components/responses/ZapierFailure" }, "422": { "$ref": "#/components/responses/ZapierFailure" } } } }, "/zapier-integration/actions/contacts/remove-label": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "zapierRemoveLabel", "tags": [ "Zapier integration" ], "summary": "Remove a label from a contact", "description": "Scope: `manage_labels`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "International format, digits only (e.g. 966501234567)." }, "label_id": { "type": [ "integer", "null" ] }, "label_name": { "type": [ "string", "null" ] } }, "required": [ "phone" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "phone": { "type": [ "string", "null" ] }, "label_id": { "type": "integer" }, "label": { "type": "string" }, "removed": { "type": "boolean" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" }, "404": { "$ref": "#/components/responses/ZapierFailure" }, "422": { "$ref": "#/components/responses/ZapierFailure" } } } }, "/zapier-integration/actions/labels": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "zapierCreateLabel", "tags": [ "Zapier integration" ], "summary": "Create a label", "description": "Scope: `manage_labels`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "name_ar": { "type": [ "string", "null" ] }, "name_en": { "type": [ "string", "null" ] }, "color": { "type": [ "string", "null" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "color": { "type": [ "string", "null" ] } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" }, "422": { "$ref": "#/components/responses/ZapierFailure" } } } }, "/zapier-integration/actions/contacts/get": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "zapierGetContact", "tags": [ "Zapier integration" ], "summary": "Full contact profile", "description": "Scope: `poll_contacts`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "parameters": [ { "name": "phone", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK — `data` holds the profile (labels, moderators, last message, flags).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZapierSuccess" } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" }, "404": { "$ref": "#/components/responses/ZapierFailure" } } } }, "/zapier-integration/actions/contacts/search": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "zapierSearchContacts", "tags": [ "Zapier integration" ], "summary": "Search contacts", "description": "Scope: `poll_contacts`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "parameters": [ { "name": "query", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 120 } }, { "name": "label_id", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "since", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Return rows with id greater than this cursor." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Default 20, capped at 100." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "count": { "type": "integer" }, "cursor": { "type": [ "integer", "null" ] }, "contacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "phone": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] } } } } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" } } } }, "/zapier-integration/actions/contacts/update-field": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "zapierUpdateContactField", "tags": [ "Zapier integration" ], "summary": "Set one custom field by key", "description": "Integrations area: a workspace that has not adopted it gets 404. Keys come from `lookup/custom-fields`. An empty `value` clears the field; `unknown_field` / `invalid_value` answer 422.\n\nScope: `update_contact`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": [ "string", "null" ] }, "contact_id": { "type": [ "integer", "null" ] }, "key": { "type": "string", "maxLength": 191 }, "value": { "type": [ "string", "number", "boolean", "null" ] } }, "required": [ "key" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "contact_id": { "type": "integer" }, "phone": { "type": [ "string", "null" ] }, "key": { "type": "string" }, "value": { "type": [ "string", "null" ] } }, "required": [ "contact_id", "phone", "key", "value" ] } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" }, "404": { "$ref": "#/components/responses/ZapierFailure" }, "422": { "$ref": "#/components/responses/ZapierFailure" } } } }, "/zapier-integration/actions/conversations/assign": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "zapierAssignConversation", "tags": [ "Zapier integration" ], "summary": "Assign a conversation to an agent", "description": "Scope: `manage_conversations`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "International format, digits only (e.g. 966501234567)." }, "agent_id": { "type": "integer" } }, "required": [ "phone", "agent_id" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "phone": { "type": [ "string", "null" ] }, "agent_id": { "type": "integer" }, "assigned": { "type": "boolean" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" }, "422": { "$ref": "#/components/responses/ZapierFailure" } } } }, "/zapier-integration/actions/conversations/transfer": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "zapierTransferConversation", "tags": [ "Zapier integration" ], "summary": "Transfer a conversation (same as assign)", "description": "Scope: `manage_conversations`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "International format, digits only (e.g. 966501234567)." }, "agent_id": { "type": "integer" } }, "required": [ "phone", "agent_id" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "phone": { "type": [ "string", "null" ] }, "agent_id": { "type": "integer" }, "assigned": { "type": "boolean" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" }, "422": { "$ref": "#/components/responses/ZapierFailure" } } } }, "/zapier-integration/actions/conversations/close": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "zapierCloseConversation", "tags": [ "Zapier integration" ], "summary": "Close a conversation", "description": "Scope: `manage_conversations`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "International format, digits only (e.g. 966501234567)." } }, "required": [ "phone" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "phone": { "type": [ "string", "null" ] }, "closed": { "type": "boolean" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" }, "404": { "$ref": "#/components/responses/ZapierFailure" }, "422": { "$ref": "#/components/responses/ZapierFailure" } } } }, "/zapier-integration/actions/conversations/reopen": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "zapierReopenConversation", "tags": [ "Zapier integration" ], "summary": "Reopen a conversation", "description": "Scope: `manage_conversations`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "International format, digits only (e.g. 966501234567)." } }, "required": [ "phone" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "phone": { "type": [ "string", "null" ] }, "closed": { "type": "boolean" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" }, "404": { "$ref": "#/components/responses/ZapierFailure" }, "422": { "$ref": "#/components/responses/ZapierFailure" } } } }, "/zapier-integration/actions/conversations/quick-reply": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "zapierSendQuickReply", "tags": [ "Zapier integration" ], "summary": "Send a saved quick reply", "description": "Scope: `manage_conversations`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "International format, digits only (e.g. 966501234567)." }, "quick_reply_id": { "type": "integer" } }, "required": [ "phone", "quick_reply_id" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "phone": { "type": "string" }, "quick_reply_id": { "type": "integer" }, "queued_at": { "type": "string", "format": "date-time" }, "automation_budget": { "$ref": "#/components/schemas/ZapierAutomationBudget" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" }, "422": { "$ref": "#/components/responses/ZapierFailure" } } } }, "/zapier-integration/actions/conversations/note": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "zapierAddNote", "tags": [ "Zapier integration" ], "summary": "Add an internal note", "description": "Scope: `manage_conversations`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "International format, digits only (e.g. 966501234567)." }, "note": { "type": "string", "maxLength": 5000 } }, "required": [ "phone", "note" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "phone": { "type": [ "string", "null" ] }, "note": { "type": "string" }, "created_at": { "type": [ "string", "null" ] } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" }, "422": { "$ref": "#/components/responses/ZapierFailure" } } } }, "/zapier-integration/actions/campaigns/add-contact": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "zapierCampaignAddContact", "tags": [ "Zapier integration" ], "summary": "Add a contact to a campaign", "description": "Scope: `manage_campaigns`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign_id": { "type": "integer" }, "phone": { "type": "string", "description": "International format, digits only (e.g. 966501234567)." } }, "required": [ "campaign_id", "phone" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "campaign_id": { "type": "integer" }, "contact_id": { "type": "integer" }, "row_id": { "type": "integer" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" }, "422": { "$ref": "#/components/responses/ZapierFailure" } } } }, "/zapier-integration/actions/campaigns/remove-contact": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "zapierCampaignRemoveContact", "tags": [ "Zapier integration" ], "summary": "Remove a contact from a campaign", "description": "Scope: `manage_campaigns`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign_id": { "type": "integer" }, "phone": { "type": "string", "description": "International format, digits only (e.g. 966501234567)." } }, "required": [ "campaign_id", "phone" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "campaign_id": { "type": "integer" }, "phone": { "type": "string" }, "removed_count": { "type": "integer" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" }, "422": { "$ref": "#/components/responses/ZapierFailure" } } } }, "/zapier-integration/actions/campaigns/trigger-bot": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "zapierTriggerBot", "tags": [ "Zapier integration" ], "summary": "Start a bot conversation for a contact", "description": "Scope: `manage_campaigns`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "International format, digits only (e.g. 966501234567)." }, "conversation_id": { "type": "integer" } }, "required": [ "phone", "conversation_id" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "phone": { "type": "string" }, "conversation_id": { "type": "integer" }, "triggered_at": { "type": "string", "format": "date-time" }, "automation_budget": { "$ref": "#/components/schemas/ZapierAutomationBudget" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" }, "422": { "$ref": "#/components/responses/ZapierFailure" } } } }, "/zapier-integration/actions/ai/summarize": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "zapierAiSummarize", "tags": [ "Zapier integration" ], "summary": "Summarise a conversation or text", "description": "`text` or `phone` (the last 20 messages of that contact) is required.\n\nScope: `use_ai`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ], "enum": [ "ar", "en", null ] } } } } } }, "responses": { "200": { "description": "OK — `data` is the AI service result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZapierSuccess" } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" }, "422": { "$ref": "#/components/responses/ZapierFailure" } } } }, "/zapier-integration/actions/ai/sentiment": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "zapierAiSentiment", "tags": [ "Zapier integration" ], "summary": "Sentiment of a conversation or text", "description": "`text` or `phone` (the last 20 messages of that contact) is required.\n\nScope: `use_ai`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] } } } } } }, "responses": { "200": { "description": "OK — `data` is the AI service result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZapierSuccess" } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" }, "422": { "$ref": "#/components/responses/ZapierFailure" } } } }, "/zapier-integration/actions/ai/translate": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "zapierAiTranslate", "tags": [ "Zapier integration" ], "summary": "Translate text", "description": "Scope: `use_ai`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string" }, "target_language": { "type": "string", "minLength": 2 } }, "required": [ "text", "target_language" ] } } } }, "responses": { "200": { "description": "OK — `data` is the AI service result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZapierSuccess" } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" }, "422": { "$ref": "#/components/responses/ZapierFailure" } } } }, "/zapier-integration/actions/ai/suggest-reply": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "zapierAiSuggestReply", "tags": [ "Zapier integration" ], "summary": "Suggest a reply", "description": "`text` or `phone` (the last 20 messages of that contact) is required.\n\nScope: `use_ai`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ], "enum": [ "ar", "en", null ] } } } } } }, "responses": { "200": { "description": "OK — `data` is the AI service result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZapierSuccess" } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" }, "422": { "$ref": "#/components/responses/ZapierFailure" } } } }, "/zapier-integration/lookup/templates": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "zapierLookupTemplates", "tags": [ "Zapier integration" ], "summary": "Dropdown: active notification templates", "description": "`id` is the template slug.\n\nScope: `read_events`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "responses": { "200": { "description": "OK — a bare JSON array (Zapier performList).", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" } }, "required": [ "id", "label" ] } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" } } } }, "/zapier-integration/lookup/channels": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "zapierLookupChannels", "tags": [ "Zapier integration" ], "summary": "Dropdown: the workspace channels", "description": "`id` is what `channel_id` on send-text / send-template takes.\n\nScope: `read_events`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "responses": { "200": { "description": "OK — a bare JSON array (Zapier performList).", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "label": { "type": "string" } }, "required": [ "id", "label" ] } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" } } } }, "/zapier-integration/lookup/labels": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "zapierLookupLabels", "tags": [ "Zapier integration" ], "summary": "Dropdown: contact labels", "description": "Scope: `read_events`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "responses": { "200": { "description": "OK — a bare JSON array (Zapier performList).", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "label": { "type": "string" } }, "required": [ "id", "label" ] } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" } } } }, "/zapier-integration/lookup/quick-replies": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "zapierLookupQuickReplies", "tags": [ "Zapier integration" ], "summary": "Dropdown: quick replies", "description": "Scope: `read_events`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "responses": { "200": { "description": "OK — a bare JSON array (Zapier performList).", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "label": { "type": "string" } }, "required": [ "id", "label" ] } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" } } } }, "/zapier-integration/lookup/lifecycle-stages": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "zapierLookupLifecycleStages", "tags": [ "Zapier integration" ], "summary": "Dropdown: lifecycle stages", "description": "The workspace's stages in the owner's order — the values of the `stage_id` filter of `contact_lifecycle_changed`. An empty list while the workspace's `lifecycle` or `integrations` area is off.\n\nScope: `read_events`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "responses": { "200": { "description": "OK — a bare JSON array (Zapier performList).", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "label": { "type": "string" }, "name": { "type": "string" }, "emoji": { "type": [ "string", "null" ] }, "position": { "type": "integer" }, "is_default": { "type": "boolean" }, "is_lost": { "type": "boolean" } }, "required": [ "id", "label", "name", "emoji", "position", "is_default", "is_lost" ] } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" } } } }, "/zapier-integration/lookup/custom-fields": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain (Zapier / Make / n8n surface — NOT /api/v1).", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "zapierLookupCustomFields", "tags": [ "Zapier integration" ], "summary": "Dropdown: custom contact field keys", "description": "An empty list while the workspace has not adopted the `integrations` area.\n\nScope: `read_events`.", "security": [ { "zapierApiKey": [] }, { "zapierOAuth": [] } ], "responses": { "200": { "description": "OK — a bare JSON array (Zapier performList).", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The machine key (= `key`), what `contacts/update-field` takes." }, "label": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "number", "date", "boolean", "select", "phone" ] }, "options": { "type": "array", "items": { "type": "string" }, "description": "Allowed values of a `select` field." } }, "required": [ "id", "label", "key", "name", "type", "options" ] } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/ZapierMissingScope" } } } }, "/v1/crm/contacts": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain. The CRM API lives under /v1/crm.", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "crmListContacts", "tags": [ "CRM" ], "summary": "List contacts", "description": "Contacts through the CRM lists engine: search, filters, saved views, sort and pages. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Free-text search.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "filters", "in": "query", "required": false, "description": "Lists-engine filter, JSON: `{\"match\":\"and|or\",\"conditions\":[{\"field\":\"email\",\"op\":\"is_not_empty\"}]}`. GET …/schema lists the fields and operators.", "schema": { "type": "string" } }, { "name": "view", "in": "query", "required": false, "description": "A saved view id (its filters / sort apply), or `all`.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sort key (see …/schema `sorts`).", "schema": { "type": "string" } }, { "name": "dir", "in": "query", "required": false, "description": "Sort direction.", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (max 100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "One page.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CrmContact" } }, "meta": { "$ref": "#/components/schemas/CrmListMeta" } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "422": { "$ref": "#/components/responses/CrmValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "crmCreateContact", "tags": [ "CRM" ], "summary": "Create a contact", "description": "Creates a contact (WhatsApp customer) by phone. A phone that already exists answers 409 with that contact in `data`. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "maxLength": 191 }, "email": { "type": [ "string", "null" ], "format": "email" }, "city": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "owner_user_id": { "type": [ "integer", "null" ], "description": "Team member who owns the contact." }, "lifecycle_stage_id": { "type": [ "integer", "null" ], "description": "Lifecycle stage id (GET /v1/crm/contacts/schema → `lifecycle` options)." }, "company_id": { "type": [ "integer", "null" ], "description": "Link the contact to this company." }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Custom field values keyed by field key." } } }, { "type": "object", "required": [ "phone" ], "properties": { "phone": { "type": "string", "description": "International format, e.g. 966501234567." } } } ] } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/CrmContact" } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "409": { "$ref": "#/components/responses/CrmConflict" }, "422": { "$ref": "#/components/responses/CrmValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/crm/contacts/schema": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain. The CRM API lives under /v1/crm.", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "crmContactsSchema", "tags": [ "CRM" ], "summary": "Contact fields, filters and sorts", "description": "The lists-engine catalogue for contact lists: every field with its type, whether it can be filtered or sorted, and the filter operators. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/CrmListSchema" } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/crm/contacts/search": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain. The CRM API lives under /v1/crm.", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "crmSearchContacts", "tags": [ "CRM" ], "summary": "Find contacts", "description": "Exact lookup by phone (any format) or e-mail, or free text `q`. Up to 25 matches, newest first. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "parameters": [ { "name": "phone", "in": "query", "required": false, "description": "Phone in any format.", "schema": { "type": "string" } }, { "name": "email", "in": "query", "required": false, "description": "E-mail address.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Free text.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CrmContact" } } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "422": { "$ref": "#/components/responses/CrmValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/crm/contacts/{id}": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain. The CRM API lives under /v1/crm.", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "crmGetContact", "tags": [ "CRM" ], "summary": "Get a contact", "description": "One contact. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The contact id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/CrmContact" } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "crmUpdateContact", "tags": [ "CRM" ], "summary": "Update a contact", "description": "Only the fields sent change; same validation and audit as the panel. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The contact id.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "maxLength": 191 }, "email": { "type": [ "string", "null" ], "format": "email" }, "city": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "owner_user_id": { "type": [ "integer", "null" ], "description": "Team member who owns the contact." }, "lifecycle_stage_id": { "type": [ "integer", "null" ], "description": "Lifecycle stage id (GET /v1/crm/contacts/schema → `lifecycle` options)." }, "company_id": { "type": [ "integer", "null" ], "description": "Link the contact to this company." }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Custom field values keyed by field key." } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/CrmContact" } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "422": { "$ref": "#/components/responses/CrmValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/crm/contacts/{id}/notes": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain. The CRM API lives under /v1/crm.", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "crmAddContactNote", "tags": [ "CRM" ], "summary": "Add a note to a contact", "description": "Logs a note on the contact's CRM timeline. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The contact id.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "body" ], "properties": { "body": { "type": "string", "maxLength": 10000 }, "title": { "type": "string", "maxLength": 191 }, "occurred_at": { "type": "string", "format": "date-time" }, "pinned": { "type": "boolean" } } } } } }, "responses": { "201": { "description": "The note.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/CrmActivity" } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "422": { "$ref": "#/components/responses/CrmValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/crm/companies": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain. The CRM API lives under /v1/crm.", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "crmListCompanies", "tags": [ "CRM" ], "summary": "List companies", "description": "Companies through the CRM lists engine. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Free-text search.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "filters", "in": "query", "required": false, "description": "Lists-engine filter, JSON: `{\"match\":\"and|or\",\"conditions\":[{\"field\":\"email\",\"op\":\"is_not_empty\"}]}`. GET …/schema lists the fields and operators.", "schema": { "type": "string" } }, { "name": "view", "in": "query", "required": false, "description": "A saved view id (its filters / sort apply), or `all`.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sort key (see …/schema `sorts`).", "schema": { "type": "string" } }, { "name": "dir", "in": "query", "required": false, "description": "Sort direction.", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (max 100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "One page.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CrmCompany" } }, "meta": { "$ref": "#/components/schemas/CrmListMeta" } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "422": { "$ref": "#/components/responses/CrmValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "crmCreateCompany", "tags": [ "CRM" ], "summary": "Create a company", "description": "Creates a company (account). Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "name": { "type": "string", "maxLength": 191 }, "domain": { "type": [ "string", "null" ] }, "industry": { "type": [ "string", "null" ] }, "size_range": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ], "description": "ISO 3166 alpha-2." }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "owner_user_id": { "type": [ "integer", "null" ] }, "lifecycle": { "type": "string" } } }, { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } } ] } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/CrmCompanyDetail" } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "422": { "$ref": "#/components/responses/CrmValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/crm/companies/schema": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain. The CRM API lives under /v1/crm.", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "crmCompaniesSchema", "tags": [ "CRM" ], "summary": "Company fields, filters and sorts", "description": "The lists-engine catalogue for company lists: every field with its type, whether it can be filtered or sorted, and the filter operators. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/CrmListSchema" } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/crm/companies/search": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain. The CRM API lives under /v1/crm.", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "crmSearchCompanies", "tags": [ "CRM" ], "summary": "Find companies", "description": "Exact lookup by domain or name, or free text `q`. Up to 25 matches. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "parameters": [ { "name": "domain", "in": "query", "required": false, "description": "Website domain (any form, normalised).", "schema": { "type": "string" } }, { "name": "name", "in": "query", "required": false, "description": "Exact name.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Free text.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CrmCompany" } } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "422": { "$ref": "#/components/responses/CrmValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/crm/companies/{id}": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain. The CRM API lives under /v1/crm.", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "crmGetCompany", "tags": [ "CRM" ], "summary": "Get a company", "description": "One company with its linked contacts. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The company id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/CrmCompanyDetail" } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "crmUpdateCompany", "tags": [ "CRM" ], "summary": "Update a company", "description": "Only the fields sent change. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The company id.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 191 }, "domain": { "type": [ "string", "null" ] }, "industry": { "type": [ "string", "null" ] }, "size_range": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ], "description": "ISO 3166 alpha-2." }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "owner_user_id": { "type": [ "integer", "null" ] }, "lifecycle": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/CrmCompanyDetail" } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "422": { "$ref": "#/components/responses/CrmValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "crmDeleteCompany", "tags": [ "CRM" ], "summary": "Delete a company", "description": "Soft-deletes the company (restorable in the panel). Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The company id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "type": "object", "required": [ "id", "deleted" ], "properties": { "id": { "type": "integer" }, "deleted": { "const": true } } } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/crm/companies/{id}/contacts": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain. The CRM API lives under /v1/crm.", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "crmLinkCompanyContact", "tags": [ "CRM" ], "summary": "Link a contact to a company", "description": "Associates a contact with the company, optionally as its primary contact. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The company id.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "contact_id" ], "properties": { "contact_id": { "type": "integer" }, "role": { "type": [ "string", "null" ], "maxLength": 100 }, "is_primary": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/CrmCompanyDetail" } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "422": { "$ref": "#/components/responses/CrmValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/crm/companies/{id}/contacts/{contactId}": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain. The CRM API lives under /v1/crm.", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "delete": { "operationId": "crmUnlinkCompanyContact", "tags": [ "CRM" ], "summary": "Unlink a contact from a company", "description": "Removes the association (the contact stays). Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The company id.", "schema": { "type": "integer" } }, { "name": "contactId", "in": "path", "required": true, "description": "The contact id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/CrmCompanyDetail" } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/crm/companies/{id}/notes": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain. The CRM API lives under /v1/crm.", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "crmAddCompanyNote", "tags": [ "CRM" ], "summary": "Add a note to a company", "description": "Logs a note on the company's CRM timeline. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The company id.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "body" ], "properties": { "body": { "type": "string", "maxLength": 10000 }, "title": { "type": "string", "maxLength": 191 }, "occurred_at": { "type": "string", "format": "date-time" }, "pinned": { "type": "boolean" } } } } } }, "responses": { "201": { "description": "The note.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/CrmActivity" } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "422": { "$ref": "#/components/responses/CrmValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/crm/pipelines": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain. The CRM API lives under /v1/crm.", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "crmListPipelines", "tags": [ "CRM" ], "summary": "List pipelines and stages", "description": "Every sales pipeline with its stages (kind `open`, `won` or `lost`). Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CrmPipeline" } } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/crm/deals": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain. The CRM API lives under /v1/crm.", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "crmListDeals", "tags": [ "CRM" ], "summary": "List deals", "description": "Deals, newest activity first by default. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "parameters": [ { "name": "pipeline_id", "in": "query", "required": false, "description": "Only this pipeline.", "schema": { "type": "integer" } }, { "name": "stage_id", "in": "query", "required": false, "description": "Only this stage.", "schema": { "type": "integer" } }, { "name": "status", "in": "query", "required": false, "description": "Only this status.", "schema": { "type": "string", "enum": [ "open", "won", "lost" ] } }, { "name": "owner_user_id", "in": "query", "required": false, "description": "Only this owner.", "schema": { "type": "integer" } }, { "name": "contact_id", "in": "query", "required": false, "description": "Only this contact.", "schema": { "type": "integer" } }, { "name": "company_id", "in": "query", "required": false, "description": "Only this company.", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "Text in the title.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sort key.", "schema": { "type": "string", "enum": [ "updated_at", "created_at", "amount", "expected_close_date" ] } }, { "name": "dir", "in": "query", "required": false, "description": "Sort direction.", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "updated_since", "in": "query", "required": false, "description": "Only records updated at or after this ISO-8601 time (polling).", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_since", "in": "query", "required": false, "description": "Only records created at or after this ISO-8601 time.", "schema": { "type": "string", "format": "date-time" } }, { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (max 100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "One page.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CrmDeal" } }, "meta": { "$ref": "#/components/schemas/CrmListMeta" } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "422": { "$ref": "#/components/responses/CrmValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "crmCreateDeal", "tags": [ "CRM" ], "summary": "Create a deal", "description": "Without `stage_id` the deal starts in the first open stage of `pipeline_id` (default pipeline when omitted). Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "title": { "type": "string", "maxLength": 191 }, "stage_id": { "type": "integer", "description": "Pipeline stage (GET /v1/crm/pipelines)." }, "amount": { "type": [ "number", "null" ], "minimum": 0 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "contact_id": { "type": [ "integer", "null" ] }, "company_id": { "type": [ "integer", "null" ] }, "owner_user_id": { "type": [ "integer", "null" ] }, "expected_close_date": { "type": [ "string", "null" ], "format": "date" } } }, { "type": "object", "required": [ "title" ], "properties": { "pipeline_id": { "type": "integer" } } } ] } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/CrmDeal" } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "422": { "$ref": "#/components/responses/CrmValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/crm/deals/lost-reasons": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain. The CRM API lives under /v1/crm.", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "crmListLostReasons", "tags": [ "CRM" ], "summary": "List lost reasons", "description": "Active reasons; marking a deal lost needs one. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/crm/deals/search": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain. The CRM API lives under /v1/crm.", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "crmSearchDeals", "tags": [ "CRM" ], "summary": "Find deals", "description": "By exact title, text `q` or contact. Up to 25 matches. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "parameters": [ { "name": "title", "in": "query", "required": false, "description": "Exact title.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Text in the title.", "schema": { "type": "string" } }, { "name": "contact_id", "in": "query", "required": false, "description": "The contact.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CrmDeal" } } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "422": { "$ref": "#/components/responses/CrmValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/crm/deals/{id}": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain. The CRM API lives under /v1/crm.", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "crmGetDeal", "tags": [ "CRM" ], "summary": "Get a deal", "description": "One deal. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The deal id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/CrmDeal" } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "crmUpdateDeal", "tags": [ "CRM" ], "summary": "Update a deal", "description": "Only the fields sent change. A `stage_id` of a won / lost stage wins / loses the deal (lost needs `lost_reason_id`). Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The deal id.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "title": { "type": "string", "maxLength": 191 }, "stage_id": { "type": "integer", "description": "Pipeline stage (GET /v1/crm/pipelines)." }, "amount": { "type": [ "number", "null" ], "minimum": 0 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "contact_id": { "type": [ "integer", "null" ] }, "company_id": { "type": [ "integer", "null" ] }, "owner_user_id": { "type": [ "integer", "null" ] }, "expected_close_date": { "type": [ "string", "null" ], "format": "date" } } }, { "type": "object", "properties": { "lost_reason_id": { "type": [ "integer", "null" ] }, "lost_note": { "type": [ "string", "null" ] } } } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/CrmDeal" } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "422": { "$ref": "#/components/responses/CrmValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "crmDeleteDeal", "tags": [ "CRM" ], "summary": "Delete a deal", "description": "Soft-deletes the deal. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The deal id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "type": "object", "required": [ "id", "deleted" ], "properties": { "id": { "type": "integer" }, "deleted": { "const": true } } } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/crm/deals/{id}/stage": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain. The CRM API lives under /v1/crm.", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "crmMoveDealStage", "tags": [ "CRM" ], "summary": "Move a deal to a stage", "description": "The stage must belong to the deal's pipeline. Fires `deal.stage_changed` (and `deal.won` / `deal.lost`). Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The deal id.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "stage_id" ], "properties": { "stage_id": { "type": "integer" }, "lost_reason_id": { "type": [ "integer", "null" ] }, "lost_note": { "type": [ "string", "null" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/CrmDeal" } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "422": { "$ref": "#/components/responses/CrmValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/crm/deals/{id}/won": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain. The CRM API lives under /v1/crm.", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "crmMarkDealWon", "tags": [ "CRM" ], "summary": "Mark a deal won", "description": "Moves it to the pipeline's won stage. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The deal id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/CrmDeal" } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "422": { "$ref": "#/components/responses/CrmValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/crm/deals/{id}/lost": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain. The CRM API lives under /v1/crm.", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "crmMarkDealLost", "tags": [ "CRM" ], "summary": "Mark a deal lost", "description": "Moves it to the pipeline's lost stage. `lost_reason_id` is required (GET /v1/crm/deals/lost-reasons). Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The deal id.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "lost_reason_id" ], "properties": { "lost_reason_id": { "type": "integer" }, "note": { "type": [ "string", "null" ], "maxLength": 500 } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/CrmDeal" } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "422": { "$ref": "#/components/responses/CrmValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/crm/deals/{id}/notes": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain. The CRM API lives under /v1/crm.", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "crmAddDealNote", "tags": [ "CRM" ], "summary": "Add a note to a deal", "description": "Logs a note on the deal's CRM timeline. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The deal id.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "body" ], "properties": { "body": { "type": "string", "maxLength": 10000 }, "title": { "type": "string", "maxLength": 191 }, "occurred_at": { "type": "string", "format": "date-time" }, "pinned": { "type": "boolean" } } } } } }, "responses": { "201": { "description": "The note.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/CrmActivity" } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "422": { "$ref": "#/components/responses/CrmValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/crm/tasks": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain. The CRM API lives under /v1/crm.", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "crmListTasks", "tags": [ "CRM" ], "summary": "List tasks", "description": "Tasks, newest activity first by default. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Only this status.", "schema": { "type": "string", "enum": [ "todo", "in_progress", "done" ] } }, { "name": "assignee_user_id", "in": "query", "required": false, "description": "Only this assignee.", "schema": { "type": "integer" } }, { "name": "contact_id", "in": "query", "required": false, "description": "Only this contact.", "schema": { "type": "integer" } }, { "name": "deal_id", "in": "query", "required": false, "description": "Only this deal.", "schema": { "type": "integer" } }, { "name": "due_before", "in": "query", "required": false, "description": "Due before.", "schema": { "type": "string", "format": "date-time" } }, { "name": "due_after", "in": "query", "required": false, "description": "Due at or after.", "schema": { "type": "string", "format": "date-time" } }, { "name": "q", "in": "query", "required": false, "description": "Text in the title.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sort key.", "schema": { "type": "string", "enum": [ "updated_at", "created_at", "due_at" ] } }, { "name": "dir", "in": "query", "required": false, "description": "Sort direction.", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "updated_since", "in": "query", "required": false, "description": "Only records updated at or after this ISO-8601 time (polling).", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_since", "in": "query", "required": false, "description": "Only records created at or after this ISO-8601 time.", "schema": { "type": "string", "format": "date-time" } }, { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (max 100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "One page.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CrmTask" } }, "meta": { "$ref": "#/components/schemas/CrmListMeta" } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "422": { "$ref": "#/components/responses/CrmValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "crmCreateTask", "tags": [ "CRM" ], "summary": "Create a task", "description": "Creates a task (a recurring one needs `due_at`). Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "title": { "type": "string", "maxLength": 191 }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "todo", "in_progress", "done" ] }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "remind_at": { "type": [ "string", "null" ], "format": "date-time" }, "assignee_user_id": { "type": [ "integer", "null" ] }, "contact_id": { "type": [ "integer", "null" ] }, "deal_id": { "type": [ "integer", "null" ] }, "recurrence": { "type": [ "string", "null" ], "enum": [ "daily", "weekly", "monthly", null ] } } }, { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string" } } } ] } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/CrmTask" } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "422": { "$ref": "#/components/responses/CrmValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/crm/tasks/{id}": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain. The CRM API lives under /v1/crm.", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "crmGetTask", "tags": [ "CRM" ], "summary": "Get a task", "description": "One task. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The task id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/CrmTask" } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "crmUpdateTask", "tags": [ "CRM" ], "summary": "Update a task", "description": "Only the fields sent change. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The task id.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 191 }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "todo", "in_progress", "done" ] }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "remind_at": { "type": [ "string", "null" ], "format": "date-time" }, "assignee_user_id": { "type": [ "integer", "null" ] }, "contact_id": { "type": [ "integer", "null" ] }, "deal_id": { "type": [ "integer", "null" ] }, "recurrence": { "type": [ "string", "null" ], "enum": [ "daily", "weekly", "monthly", null ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/CrmTask" } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "422": { "$ref": "#/components/responses/CrmValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "crmDeleteTask", "tags": [ "CRM" ], "summary": "Delete a task", "description": "Deletes the task. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The task id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "type": "object", "required": [ "id", "deleted" ], "properties": { "id": { "type": "integer" }, "deleted": { "const": true } } } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/crm/tasks/{id}/complete": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain. The CRM API lives under /v1/crm.", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "post": { "operationId": "crmCompleteTask", "tags": [ "CRM" ], "summary": "Complete a task", "description": "Marks the task done (fires `task.completed`). Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The task id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/CrmTask" } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/crm/activities": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain. The CRM API lives under /v1/crm.", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "crmListActivities", "tags": [ "CRM" ], "summary": "List activities", "description": "Timeline entries of contacts, companies and deals, newest first. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "parameters": [ { "name": "subject_type", "in": "query", "required": false, "description": "Record type (with subject_id).", "schema": { "type": "string", "enum": [ "contact", "company", "deal" ] } }, { "name": "subject_id", "in": "query", "required": false, "description": "Record id.", "schema": { "type": "integer" } }, { "name": "type", "in": "query", "required": false, "description": "Activity type, e.g. note, call, meeting, email, order.", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "required": false, "description": "Only records updated at or after this ISO-8601 time (polling).", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_since", "in": "query", "required": false, "description": "Only records created at or after this ISO-8601 time.", "schema": { "type": "string", "format": "date-time" } }, { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (max 100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "One page.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CrmActivity" } }, "meta": { "$ref": "#/components/schemas/CrmListMeta" } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "422": { "$ref": "#/components/responses/CrmValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "crmCreateActivity", "tags": [ "CRM" ], "summary": "Log an activity", "description": "Logs a note, call or meeting on a contact, company or deal. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "subject_type", "subject_id", "type" ], "properties": { "subject_type": { "type": "string", "enum": [ "contact", "company", "deal" ] }, "subject_id": { "type": "integer" }, "type": { "type": "string", "enum": [ "note", "call", "meeting" ] }, "body": { "type": [ "string", "null" ], "description": "Required for a note." }, "title": { "type": [ "string", "null" ] }, "occurred_at": { "type": [ "string", "null" ], "format": "date-time" }, "pinned": { "type": "boolean" }, "direction": { "type": [ "string", "null" ], "enum": [ "inbound", "outbound", null ], "description": "Calls: required." }, "outcome": { "type": [ "string", "null" ], "enum": [ "connected", "no_answer", "busy", "voicemail", "wrong_number", null ] }, "duration_minutes": { "type": [ "integer", "null" ] }, "location": { "type": [ "string", "null" ] } } } } } }, "responses": { "201": { "description": "Logged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/CrmActivity" } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "422": { "$ref": "#/components/responses/CrmValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/crm/activities/{id}": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain. The CRM API lives under /v1/crm.", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "crmGetActivity", "tags": [ "CRM" ], "summary": "Get an activity", "description": "One timeline entry. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The activity id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/CrmActivity" } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/crm/quotes": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain. The CRM API lives under /v1/crm.", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "crmListQuotes", "tags": [ "CRM" ], "summary": "List quotes", "description": "Quotes through the CRM lists engine. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Free-text search.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "filters", "in": "query", "required": false, "description": "Lists-engine filter, JSON: `{\"match\":\"and|or\",\"conditions\":[{\"field\":\"email\",\"op\":\"is_not_empty\"}]}`. GET …/schema lists the fields and operators.", "schema": { "type": "string" } }, { "name": "view", "in": "query", "required": false, "description": "A saved view id (its filters / sort apply), or `all`.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sort key (see …/schema `sorts`).", "schema": { "type": "string" } }, { "name": "dir", "in": "query", "required": false, "description": "Sort direction.", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (max 100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "One page.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CrmQuote" } }, "meta": { "$ref": "#/components/schemas/CrmListMeta" } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "422": { "$ref": "#/components/responses/CrmValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "crmCreateQuote", "tags": [ "CRM" ], "summary": "Draft a quote", "description": "Creates a draft quote. Sending it to the customer happens in the panel. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "deal_id": { "type": [ "integer", "null" ] }, "contact_id": { "type": [ "integer", "null" ] }, "company_id": { "type": [ "integer", "null" ] }, "currency": { "type": "string" }, "locale": { "type": "string", "enum": [ "ar", "en" ] }, "valid_until": { "type": [ "string", "null" ], "format": "date" }, "terms": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "qty": { "type": "number" }, "unit_price": { "type": "number" }, "discount_pct": { "type": "number" }, "tax_pct": { "type": "number" } } } } } } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/CrmQuote" } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "422": { "$ref": "#/components/responses/CrmValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/crm/quotes/schema": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain. The CRM API lives under /v1/crm.", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "crmQuotesSchema", "tags": [ "CRM" ], "summary": "Quote fields, filters and sorts", "description": "The lists-engine catalogue for quote lists: every field with its type, whether it can be filtered or sorted, and the filter operators. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/CrmListSchema" } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/crm/quotes/{id}": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain. The CRM API lives under /v1/crm.", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "crmGetQuote", "tags": [ "CRM" ], "summary": "Get a quote", "description": "One quote with its items. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The quote id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/CrmQuote" } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "crmUpdateQuote", "tags": [ "CRM" ], "summary": "Update a quote", "description": "Draft quotes only. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The quote id.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "deal_id": { "type": [ "integer", "null" ] }, "contact_id": { "type": [ "integer", "null" ] }, "company_id": { "type": [ "integer", "null" ] }, "currency": { "type": "string" }, "locale": { "type": "string", "enum": [ "ar", "en" ] }, "valid_until": { "type": [ "string", "null" ], "format": "date" }, "terms": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "qty": { "type": "number" }, "unit_price": { "type": "number" }, "discount_pct": { "type": "number" }, "tax_pct": { "type": "number" } } } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/CrmQuote" } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "422": { "$ref": "#/components/responses/CrmValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "crmDeleteQuote", "tags": [ "CRM" ], "summary": "Delete a draft quote", "description": "Only drafts; a sent quote answers 409. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The quote id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "type": "object", "required": [ "id", "deleted" ], "properties": { "id": { "type": "integer" }, "deleted": { "const": true } } } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "409": { "$ref": "#/components/responses/CrmConflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/crm/products": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain. The CRM API lives under /v1/crm.", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "crmListProducts", "tags": [ "CRM" ], "summary": "List products", "description": "The product catalogue through the CRM lists engine. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Free-text search.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "filters", "in": "query", "required": false, "description": "Lists-engine filter, JSON: `{\"match\":\"and|or\",\"conditions\":[{\"field\":\"email\",\"op\":\"is_not_empty\"}]}`. GET …/schema lists the fields and operators.", "schema": { "type": "string" } }, { "name": "view", "in": "query", "required": false, "description": "A saved view id (its filters / sort apply), or `all`.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sort key (see …/schema `sorts`).", "schema": { "type": "string" } }, { "name": "dir", "in": "query", "required": false, "description": "Sort direction.", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (max 100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "One page.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CrmProduct" } }, "meta": { "$ref": "#/components/schemas/CrmListMeta" } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "422": { "$ref": "#/components/responses/CrmValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "crmCreateProduct", "tags": [ "CRM" ], "summary": "Create a product", "description": "Adds a product to the catalogue. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "price": { "type": "number", "minimum": 0 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "tax_pct": { "type": "number", "minimum": 0, "maximum": 100 }, "is_active": { "type": "boolean" }, "description": { "type": [ "string", "null" ] }, "image_url": { "type": [ "string", "null" ], "format": "uri" } } }, { "type": "object", "required": [ "name", "price", "currency" ], "properties": { "name": { "type": "string" }, "price": { "type": "number" }, "currency": { "type": "string" } } } ] } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/CrmProduct" } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "422": { "$ref": "#/components/responses/CrmValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/crm/products/schema": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain. The CRM API lives under /v1/crm.", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "crmProductsSchema", "tags": [ "CRM" ], "summary": "Product fields, filters and sorts", "description": "The lists-engine catalogue for product lists: every field with its type, whether it can be filtered or sorted, and the filter operators. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/CrmListSchema" } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/crm/products/{id}": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain. The CRM API lives under /v1/crm.", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "crmGetProduct", "tags": [ "CRM" ], "summary": "Get a product", "description": "One product. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The product id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/CrmProduct" } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "crmUpdateProduct", "tags": [ "CRM" ], "summary": "Update a product", "description": "Only the fields sent change. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The product id.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "price": { "type": "number", "minimum": 0 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "tax_pct": { "type": "number", "minimum": 0, "maximum": 100 }, "is_active": { "type": "boolean" }, "description": { "type": [ "string", "null" ] }, "image_url": { "type": [ "string", "null" ], "format": "uri" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/CrmProduct" } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "422": { "$ref": "#/components/responses/CrmValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "crmDeleteProduct", "tags": [ "CRM" ], "summary": "Delete a product", "description": "Removes it from the catalogue (existing quotes keep their lines). Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The product id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "type": "object", "required": [ "id", "deleted" ], "properties": { "id": { "type": "integer" }, "deleted": { "const": true } } } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/crm/hooks": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain. The CRM API lives under /v1/crm.", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "crmListHooks", "tags": [ "CRM" ], "summary": "List API webhook subscriptions", "description": "Subscriptions created through the API (panel-made ones are managed in the panel). Secrets are never returned again. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CrmWebhookSubscription" } } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "crmSubscribeHook", "tags": [ "CRM" ], "summary": "Subscribe a webhook (REST hook)", "description": "Zapier / Make / n8n REST-hook subscribe. Accepts `target_url` or `url`, and `event` or `events`. The answer carries the signing `secret` ONCE. Deliveries are POSTed as CrmWebhookEvent with `X-LetsBot-Signature: t=,v1=`, `X-LetsBot-Event` and `X-LetsBot-Delivery`; failed deliveries are retried with backoff (1 min, 5 min, 30 min, 2 h, 6 h); after 5 deliveries in a row fail the subscription is switched off, and an HTTP 410 answer switches it off at once. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target_url": { "type": "string", "format": "uri" }, "url": { "type": "string", "format": "uri" }, "event": { "$ref": "#/components/schemas/CrmWebhookEventName" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/CrmWebhookEventName" } }, "source": { "type": "string", "enum": [ "zapier", "make", "n8n", "api" ] }, "description": { "type": [ "string", "null" ] } } } } } }, "responses": { "201": { "description": "Subscribed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "allOf": [ { "$ref": "#/components/schemas/CrmWebhookSubscription" }, { "type": "object", "required": [ "secret" ], "properties": { "secret": { "type": "string" } } } ] } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "422": { "$ref": "#/components/responses/CrmValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/crm/hooks/events": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain. The CRM API lives under /v1/crm.", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "crmListHookEvents", "tags": [ "CRM" ], "summary": "List webhook events", "description": "The event catalogue. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "required": [ "event", "object" ], "properties": { "event": { "$ref": "#/components/schemas/CrmWebhookEventName" }, "object": { "type": "string" } } } } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/crm/hooks/sample": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain. The CRM API lives under /v1/crm.", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "get": { "operationId": "crmHookSample", "tags": [ "CRM" ], "summary": "Sample webhook payload", "description": "One sample event built from the newest record of that object (empty when there is none) — for trigger setup screens. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "parameters": [ { "name": "event", "in": "query", "required": true, "description": "The event.", "schema": { "$ref": "#/components/schemas/CrmWebhookEventName" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CrmWebhookEvent" } } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "422": { "$ref": "#/components/responses/CrmValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/crm/hooks/{id}": { "x-letsbot-surface": "zapier", "servers": [ { "url": "https://{workspace}.letsbot.net/api", "description": "The workspace's own subdomain. The CRM API lives under /v1/crm.", "variables": { "workspace": { "default": "your-workspace", "description": "The workspace subdomain." } } } ], "delete": { "operationId": "crmUnsubscribeHook", "tags": [ "CRM" ], "summary": "Unsubscribe a webhook (REST hook)", "description": "Deletes an API-made subscription. Scope: `crm`.", "security": [ { "zapierApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The subscription id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "type": "object", "required": [ "id", "deleted" ], "properties": { "id": { "type": "integer" }, "deleted": { "const": true } } } } } } } }, "401": { "$ref": "#/components/responses/ZapierUnauthorized" }, "403": { "$ref": "#/components/responses/CrmForbidden" }, "404": { "$ref": "#/components/responses/CrmNotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "lb_api_key", "description": "The channel's `lb_api_key` (panel → API → Authentication data). Not the Zapier key (`lbz_…`)." }, "zapierApiKey": { "type": "apiKey", "in": "header", "name": "X-Zapier-Api-Key", "description": "A workspace Zapier / Make / n8n key (`lbz_…`, panel → Zapier → API keys). Scoped: each operation names the scope it needs. Zapier-integration operations only." }, "zapierOAuth": { "type": "http", "scheme": "bearer", "description": "Legacy Zapier OAuth (Passport) access token — accepted until it expires; OAuth connect is retired. Zapier-integration operations only." } }, "parameters": { "ValidationMode": { "name": "X-LetsBot-Validation", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "strict" ] }, "description": "`strict` makes a validation failure answer HTTP 422 `{\"message\", \"errors\"}` instead of the default historic HTTP 202 `{\"Status\": 0, \"Message\"}`. Equivalent: `Prefer: validation=strict`. Recommended for new integrations; omitting it keeps the historic behaviour." }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1 }, "description": "Put the same key on a send and every retry of it to get at most one message. Scoped to the workspace, kept 24 hours. A replay returns the stored response with `Idempotent-Replayed: true`; the same key on a different request is 422 `idempotency_key_reused`; a retry while the first is running is 409 `idempotency_request_in_progress` (+ `Retry-After`); a retry after the first died with a 5xx is 409 `idempotency_outcome_unknown` (nothing is sent). After a 4xx or a `success: false` / `Status: 0` answer the key is reopened. Keys up to 128 printable ASCII characters are stored as-is; anything else as its sha256." } }, "headers": { "RetryAfter": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "IdempotentReplayed": { "description": "`true` when this is the stored response of an earlier request with the same Idempotency-Key; nothing was sent.", "schema": { "type": "string", "enum": [ "true" ] } }, "AutomationLimit": { "description": "Workspace daily API send limit (only when a limit is configured).", "schema": { "type": "integer" } }, "AutomationUsed": { "description": "API sends counted today (only when a limit is configured).", "schema": { "type": "integer" } }, "AutomationResetsAt": { "description": "When the daily count resets (only when a limit is configured).", "schema": { "type": "string" } }, "RateLimitLimit": { "description": "Requests allowed per minute for this channel.", "schema": { "type": "integer" } }, "RateLimitRemaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } } }, "schemas": { "Phone": { "type": "string", "examples": [ "966501234567" ], "description": "Recipient in international format, digits only. A leading `+` is stripped and Arabic-Indic digits are converted server-side." }, "PhoneDigits": { "type": "string", "pattern": "^\\+?[0-9٠-٩]+$", "examples": [ "966501234567" ], "description": "As `Phone`, and validated as numeric." }, "GatewayResponse": { "type": "object", "additionalProperties": true, "description": "The connection gateway's answer, passed through unchanged. `success: false` means the request was not carried out even though the HTTP status is 2xx.", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": {} }, "examples": [ { "success": true, "message": "The message has been successfully sent.", "data": { "key": { "remoteJid": "966500000000@s.whatsapp.net", "fromMe": true, "id": "wamid.HBgLMTIzNDU2Nzg5MBUTQ" }, "messageTimestamp": 1706900000, "status": "PENDING" } } ] }, "SendMessageResponse": { "allOf": [ { "$ref": "#/components/schemas/GatewayResponse" }, { "type": "object", "properties": { "pricing_estimate": { "$ref": "#/components/schemas/PricingEstimate" } } } ] }, "PricingEstimate": { "type": "object", "additionalProperties": true, "description": "Present only when the workspace enabled pricing estimates. An estimate, not a bill.", "properties": { "estimate": { "type": "boolean" }, "billed_messages": { "type": "integer" }, "category": { "type": "string" }, "pricing_model": { "type": "string" }, "country_bucket": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] }, "rate": { "type": [ "number", "null" ] }, "total": { "type": [ "number", "null" ] }, "note": { "type": "string" } } }, "CarouselResponse": { "type": "object", "additionalProperties": true, "description": "Meta's answer on success (carries `message_id`), or `{Status: 0, Message}` when the workspace has no connected channel for `platform`.", "properties": { "message_id": { "type": "string" }, "recipient_id": { "type": "string" }, "Status": { "type": "integer" }, "Message": { "type": "string" } } }, "Button": { "type": "object", "required": [ "title" ], "additionalProperties": true, "properties": { "id": { "type": [ "string", "integer" ], "description": "Reply id returned when tapped." }, "title": { "type": "string" }, "type": { "type": [ "string", "integer" ], "description": "Postman examples use `1` = URL button and `2` = call button (target in `extra_data`); omit for a quick reply." }, "extra_data": { "type": "string", "description": "URL or phone number for type 1/2." } } }, "ListSection": { "type": "object", "properties": { "title": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "required": [ "title", "rowId" ], "properties": { "title": { "type": "string" }, "rowId": { "type": "string" }, "description": { "type": "string" } } } } } }, "CarouselCard": { "type": "object", "required": [ "title" ], "additionalProperties": true, "properties": { "title": { "type": "string", "description": "Required; cut to 80 characters." }, "subtitle": { "type": "string", "description": "Cut to 80 characters." }, "image_url": { "type": [ "string", "null" ], "format": "uri" }, "url": { "type": "string", "format": "uri", "description": "Tap action." }, "buttons": { "type": [ "array", "null" ], "maxItems": 3, "items": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string", "enum": [ "postback", "web_url" ] }, "title": { "type": "string" }, "payload": { "type": "string" }, "url": { "type": "string" } } } } } }, "TemplateComponents": { "type": [ "object", "null" ], "description": "Parameters for the approved template's components.", "properties": { "header": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "type": { "type": [ "string", "null" ], "enum": [ "text", "image", "document", "video", "location", null ] }, "parameters": { "type": [ "array", "null" ], "items": { "type": "object", "additionalProperties": true } }, "image": { "type": "object", "properties": { "link": { "type": "string" } } }, "video": { "type": "object", "properties": { "link": { "type": "string" } } }, "document": { "type": "object", "properties": { "link": { "type": "string" }, "filename": { "type": "string" } } } } }, "body": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Body variables in order." }, "buttons": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "index": { "type": [ "integer", "null" ] }, "sub_type": { "type": [ "string", "null" ], "enum": [ "url", "quick_reply", null ] }, "parameters": { "type": [ "array", "null" ], "items": { "type": "object", "additionalProperties": true } } } } } } }, "Label": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "name_translations": { "type": [ "object", "array", "null" ], "additionalProperties": { "type": "string" } }, "color": { "type": [ "string", "null" ] }, "status": { "type": "null" } } }, "Moderator": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "image": { "type": "string" } } }, "Contact": { "type": "object", "properties": { "id": { "type": "integer" }, "phone": { "type": [ "string", "null" ] }, "whatsapp_bsuid": { "type": [ "string", "null" ], "description": "Meta's business-scoped user ID for a customer who hides their number behind a WhatsApp username (e.g. `EG.2288384708632117`). Not a phone number. Sent only for workspaces with WhatsApp username support switched on." }, "whatsapp_username": { "type": [ "string", "null" ], "description": "The customer's WhatsApp @username, without the `@`. Display only. Sent only for workspaces with WhatsApp username support switched on." }, "phone_available": { "type": "boolean", "description": "`false` when the customer keeps their number private: `phone` then holds an identity, so do not SMS, call or store it as a number. Sent only for workspaces with WhatsApp username support switched on." }, "labels": { "type": "array", "items": { "$ref": "#/components/schemas/Label" } }, "moderators": { "type": "array", "items": { "$ref": "#/components/schemas/Moderator" } } } }, "ContactEnvelope": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Contact" } } }, "ModeratorList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Moderator" } } } }, "LabelList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Label" } } } }, "SentBy": { "type": "string", "enum": [ "live_chat", "bot", "api", "mcp", "send_bulk", "zapier", "salla", "zid", "woocommerce", "shopify", "hubspot", "pipedrive", "stripe", "magento", "agent", "drip", "cart", "system", "ai" ] }, "BusinessChannel": { "type": "object", "description": "One of the workspace's own numbers / channels. Also carried as `channel` by the `message_notification` and `ack_notification` webhooks (`null` when the event does not identify its channel).", "required": [ "id", "global_id", "phone", "platform", "is_official" ], "properties": { "id": { "type": "integer", "description": "The channel id shown in the panel." }, "global_id": { "type": [ "string", "null" ], "description": "The stable channel id." }, "phone": { "type": [ "string", "null" ], "description": "The business number, digits only; `null` for non-phone channels." }, "platform": { "type": "string", "examples": [ "whatsapp" ] }, "is_official": { "type": "boolean", "description": "`true` on the official WhatsApp Cloud API, `false` on a QR (WhatsApp Web) number." } } }, "ArchiveContact": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "description": "WhatsApp chat id (`@s.whatsapp.net`)." }, "contact_id": { "type": "integer" }, "phone": { "type": [ "string", "null" ], "description": "`null` when WhatsApp only gave a private identity." }, "name": { "type": [ "string", "null" ] }, "notify": { "type": [ "string", "null" ], "description": "WhatsApp profile name." }, "lb_name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "image": { "type": [ "string", "null" ] }, "platform": { "type": "string" }, "is_group": { "type": "boolean" }, "is_archived": { "type": "boolean" }, "is_blocked": { "type": "boolean" }, "last_message_date": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ArchiveContactPage": { "type": "object", "required": [ "success", "Status", "source", "data", "next_cursor" ], "properties": { "success": { "type": "boolean" }, "Status": { "type": "boolean" }, "source": { "type": "string", "const": "archive" }, "channel": { "anyOf": [ { "$ref": "#/components/schemas/BusinessChannel" }, { "type": "null" } ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ArchiveContact" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "ArchiveChat": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "contact_id": { "type": "integer" }, "phone": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "platform": { "type": "string" }, "is_group": { "type": "boolean" }, "is_archived": { "type": "boolean" }, "is_pinned": { "type": "boolean" }, "last_message_date": { "type": [ "string", "null" ], "format": "date-time" } } }, "ArchiveChatPage": { "type": "object", "required": [ "success", "Status", "source", "data", "next_cursor" ], "properties": { "success": { "type": "boolean" }, "Status": { "type": "boolean" }, "source": { "type": "string", "const": "archive" }, "channel": { "anyOf": [ { "$ref": "#/components/schemas/BusinessChannel" }, { "type": "null" } ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ArchiveChat" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "UseMessagesArchive": { "type": "object", "required": [ "success", "Status", "error_code", "Message", "use" ], "properties": { "success": { "type": "boolean", "const": false }, "Status": { "type": "boolean", "const": false }, "error_code": { "type": "string", "const": "USE_MESSAGES_ARCHIVE" }, "Message": { "type": "string" }, "use": { "type": "object", "properties": { "method": { "type": "string", "const": "GET" }, "path": { "type": "string", "const": "/api/v1/messages" }, "example": { "type": "string" } } } } }, "ArchiveMessage": { "type": "object", "required": [ "id", "message_id", "from_me", "sent_by", "agent", "contact", "group_id", "type", "body", "caption", "attachment", "status", "status_text", "message_date", "channel_platform", "channel", "referral" ], "properties": { "id": { "type": "integer" }, "message_id": { "type": [ "string", "null" ] }, "from_me": { "type": "boolean" }, "sent_by": { "type": [ "string", "null" ] }, "agent": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] } } }, "contact": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "phone": { "type": [ "string", "null" ] }, "chat_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } } }, "group_id": { "type": [ "integer", "null" ] }, "type": { "type": "string", "description": "Lower-case message type name, or `unknown`." }, "body": { "type": [ "string", "null" ] }, "caption": { "type": [ "string", "null" ] }, "attachment": { "type": [ "object", "array", "null" ] }, "status": { "type": "integer" }, "status_text": { "type": [ "string", "null" ] }, "message_date": { "type": "string", "format": "date-time" }, "channel_platform": { "type": "string", "description": "`whatsapp`, `messenger`, `instagram`, `email`, ..." }, "channel": { "anyOf": [ { "$ref": "#/components/schemas/BusinessChannel" }, { "type": "null" } ], "description": "The workspace channel the message belongs to, when the row records it; `null` otherwise (never guessed)." }, "referral": { "anyOf": [ { "$ref": "#/components/schemas/AdReferral" }, { "type": "null" } ], "description": "For an incoming message that started from a Click-to-WhatsApp ad, the ad it came from; `null` for every other message, including everything you sent. Available on past messages too." } } }, "AdReferral": { "type": "object", "description": "The Click-to-WhatsApp ad an incoming message came from, as Meta reported it. Any field Meta did not send is `null`. Count leads per ad by grouping on `ad_id`.", "required": [ "source_type", "ad_id", "source_url", "headline", "body", "media_type", "media_url", "ctwa_clid" ], "properties": { "source_type": { "type": "string", "const": "ad" }, "ad_id": { "type": [ "string", "null" ], "description": "Meta's ad id (Meta's `referral.source_id`).", "examples": [ "120212345678900123" ] }, "source_url": { "type": [ "string", "null" ], "description": "The ad or post URL the customer tapped." }, "headline": { "type": [ "string", "null" ], "description": "The ad's headline." }, "body": { "type": [ "string", "null" ], "description": "The ad's primary text." }, "media_type": { "type": [ "string", "null" ], "description": "`image` or `video`." }, "media_url": { "type": [ "string", "null" ], "description": "The ad's image URL, video URL or thumbnail URL. Meta's URLs can expire." }, "ctwa_clid": { "type": [ "string", "null" ], "description": "Meta's Click-to-WhatsApp click id, for attributing conversions (Conversions API)." } } }, "ArchivePage": { "type": "object", "required": [ "Status", "timezone", "data", "next_cursor" ], "properties": { "Status": { "type": "boolean", "const": true }, "timezone": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ArchiveMessage" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "LegacyValidationFailure": { "type": "object", "required": [ "Status", "Message" ], "properties": { "Status": { "type": "integer", "const": 0 }, "Message": { "type": "string" } } }, "ApiRefusal": { "type": "object", "required": [ "Status", "Message" ], "properties": { "Status": { "type": "boolean", "const": false }, "Message": { "type": "string" }, "error_code": { "type": "string", "enum": [ "SUBSCRIPTION_EXPIRED", "API_ADDON_REQUIRED" ] } } }, "LaravelValidationError": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } }, "ContactValidationError": { "type": "object", "properties": { "message": { "type": "string", "const": "error" }, "data": { "type": "string" } } }, "TemplateValidationError": { "type": "object", "properties": { "success": { "type": "boolean", "const": false }, "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } }, "TemplateRefusal": { "type": "object", "properties": { "success": { "type": "boolean", "const": false }, "message": { "type": "string" } } }, "ArchiveValidationError": { "type": "object", "properties": { "Status": { "type": "boolean", "const": false }, "Message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } }, "IdempotencyError": { "type": "object", "required": [ "Status", "Message", "code" ], "properties": { "Status": { "type": "boolean", "const": false }, "Message": { "type": "string" }, "code": { "type": "string", "enum": [ "idempotency_key_reused", "idempotency_request_in_progress", "idempotency_outcome_unknown" ] } } }, "AutomationLimitError": { "type": "object", "properties": { "Status": { "type": "boolean", "const": false }, "Message": { "type": "string" }, "code": { "type": "string", "const": "automation_daily_limit_reached" }, "limit": { "type": "integer" }, "used": { "type": "integer" }, "resets_at": { "type": "string" } } }, "ThrottleError": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Too Many Attempts." ] } } }, "MetaRejection": { "type": "object", "properties": { "Status": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": false }, "Message": { "type": "string" }, "error_code": { "type": "string", "description": "e.g. WHATSAPP_NUMBER_NOT_REGISTERED, CUSTOMER_SERVICE_WINDOW_CLOSED, RECIPIENT_UNREACHABLE, WHATSAPP_RATE_LIMITED, WHATSAPP_API_ERROR." }, "help_url": { "type": "string" }, "meta_error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "fbtrace_id": { "type": "string" } } } } }, "InternalError": { "type": "object", "properties": { "Status": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": false }, "Message": { "type": "string" }, "error_code": { "type": "string", "const": "INTERNAL_ERROR" }, "reference": { "type": "string", "description": "Support reference, `API-XXXXXXXXXX`." } } }, "LifecycleError": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "TENANT_WRITES_LOCKED", "TENANT_LIFECYCLE_INVALID" ] }, "message": { "type": "string" } } }, "TenantMerged": { "type": "object", "properties": { "error": { "type": "string", "const": "TENANT_MERGED" }, "message": { "type": "string" }, "canonical_tenant_id": { "type": "string" }, "canonical_url": { "type": [ "string", "null" ] } } }, "NotFoundError": { "type": "object", "properties": { "message": { "type": "string" } } }, "ZapierSuccess": { "type": "object", "description": "Every Zapier action answers `{success: true, data}` on success.", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "additionalProperties": true } }, "required": [ "success", "data" ] }, "ZapierError": { "type": "object", "description": "Every Zapier action fails with `{success: false, error, code}`.", "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string" }, "code": { "type": "string", "description": "Machine-readable, e.g. `no_channel`, `channel_not_found`, `not_found`." } }, "required": [ "success", "error" ] }, "ZapierAutomationBudget": { "type": "object", "description": "Present only once the workspace's daily Zapier send limit is reached.", "properties": { "limit": { "type": "integer" }, "used": { "type": "integer" }, "resets_at": { "type": "string" }, "mode": { "type": "string", "enum": [ "alert", "stop" ] } } }, "ZapierMessage": { "type": "object", "properties": { "id": { "type": "integer" }, "message_id": { "type": [ "string", "null" ] }, "message_body": { "type": [ "string", "null" ] }, "message_type": { "type": [ "string", "null" ] }, "attachment": {}, "full_date": { "type": [ "string", "null" ] }, "from_me": { "type": "boolean" }, "contact_id": { "type": [ "integer", "null" ] }, "whatsapp_group_id": { "type": [ "integer", "null" ] } } }, "ZapierTrigger": { "type": "string", "enum": [ "new_message_received", "new_message_sent", "message_status_changed", "message_reacted", "keyword_matched", "media_received", "new_contact_created", "contact_updated", "contact_labeled", "contact_unlabeled", "contact_blocked", "contact_lifecycle_changed", "new_chat_started", "chat_closed", "chat_reopened", "connection_status_changed", "new_order_received", "salla_order_created", "zid_order_created", "woocommerce_order_created", "order_status_changed", "bot_template_sent", "new_lead_captured", "meta_ad_lead", "campaign_started", "campaign_completed", "campaign_failed_threshold", "call_received", "call_completed", "call_missed" ], "description": "A Zapier trigger key." }, "CrmListMeta": { "type": "object", "required": [ "current_page", "last_page", "per_page", "total" ], "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "additionalProperties": true }, "CrmListSchema": { "type": "object", "required": [ "fields", "sorts" ], "properties": { "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string" }, "filterable": { "type": "boolean" }, "sortable": { "type": "boolean" }, "operators": { "type": "array", "items": { "type": "string" } }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": {}, "label": { "type": [ "string", "null" ] } } } } } } }, "sorts": { "type": "array", "items": { "type": "string" } }, "default_sort": { "type": "object", "properties": { "key": { "type": "string" }, "dir": { "type": "string" } } } } }, "CrmError": { "type": "object", "required": [ "success", "error", "code" ], "properties": { "success": { "const": false }, "error": { "type": "string", "description": "Human-readable message (Accept-Language: en, ar, es or pt)." }, "code": { "type": "string", "enum": [ "not_found", "missing_scope", "validation_failed", "already_exists", "conflict", "forbidden", "unprocessable", "error" ] }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "data": { "description": "On `already_exists`: the existing record." } } }, "CrmContact": { "type": "object", "required": [ "id", "name", "phone" ], "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "lifecycle": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] } } }, "owner": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] } } }, "company": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] } } }, "tags": { "type": "array", "items": { "type": [ "string", "null" ] } }, "custom_fields": { "type": "object", "additionalProperties": true }, "last_activity_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "url": { "type": "string" }, "whatsapp_bsuid": { "type": [ "string", "null" ], "description": "Meta's business-scoped user ID for a customer who hides their number behind a WhatsApp username (e.g. `EG.2288384708632117`). Not a phone number. Sent only for workspaces with WhatsApp username support switched on." }, "whatsapp_username": { "type": [ "string", "null" ], "description": "The customer's WhatsApp @username, without the `@`. Display only. Sent only for workspaces with WhatsApp username support switched on." }, "phone_available": { "type": "boolean", "description": "`false` when the customer keeps their number private: `phone` then holds an identity, so do not SMS, call or store it as a number. Sent only for workspaces with WhatsApp username support switched on." } } }, "CrmCompany": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "domain": { "type": [ "string", "null" ] }, "industry": { "type": [ "string", "null" ] }, "size_range": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "lifecycle": { "type": "string" }, "owner": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] } } }, "contacts_count": { "type": "integer" }, "custom_fields": { "type": "object", "additionalProperties": true }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "url": { "type": "string" } } }, "CrmCompanyDetail": { "allOf": [ { "$ref": "#/components/schemas/CrmCompany" }, { "type": "object", "properties": { "contacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "phone": { "type": "string" }, "role": { "type": [ "string", "null" ] }, "is_primary": { "type": "boolean" } } } }, "deals_count": { "type": [ "integer", "null" ] }, "tickets_count": { "type": [ "integer", "null" ] } } } ] }, "CrmPipeline": { "type": "object", "required": [ "id", "name", "stages" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "currency": { "type": [ "string", "null" ] }, "is_default": { "type": "boolean" }, "stages": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "kind" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "open", "won", "lost" ] }, "position": { "type": "integer" }, "probability": { "type": [ "integer", "null" ] } } } } } }, "CrmDeal": { "type": "object", "required": [ "id", "title", "status" ], "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "pipeline_id": { "type": "integer" }, "stage": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] } } }, "status": { "type": "string", "enum": [ "open", "won", "lost" ] }, "expected_close_date": { "type": [ "string", "null" ], "format": "date" }, "contact": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "phone": { "type": "string" } } }, "company_id": { "type": [ "integer", "null" ] }, "owner": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] } } }, "lost_reason_id": { "type": [ "integer", "null" ] }, "lost_note": { "type": [ "string", "null" ] }, "won_at": { "type": [ "string", "null" ], "format": "date-time" }, "lost_at": { "type": [ "string", "null" ], "format": "date-time" }, "custom_fields": { "type": "object", "additionalProperties": true }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "url": { "type": "string" } } }, "CrmTask": { "type": "object", "required": [ "id", "title", "status" ], "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "todo", "in_progress", "done" ] }, "priority": { "type": "string" }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "remind_at": { "type": [ "string", "null" ], "format": "date-time" }, "overdue": { "type": "boolean" }, "assignee": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] } } }, "contact": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "phone": { "type": "string" } } }, "deal": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "title": { "type": "string" } } }, "recurrence": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "url": { "type": "string" } } }, "CrmActivity": { "type": "object", "required": [ "id", "subject_type", "subject_id", "type" ], "properties": { "id": { "type": "integer" }, "subject_type": { "type": "string", "enum": [ "contact", "company", "deal" ] }, "subject_id": { "type": "integer" }, "type": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "body": { "type": [ "string", "null" ] }, "details": { "type": "object", "additionalProperties": true }, "actor_user_id": { "type": [ "integer", "null" ] }, "source": { "type": "string" }, "pinned": { "type": "boolean" }, "occurred_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "CrmQuote": { "type": "object", "required": [ "id", "number", "status" ], "properties": { "id": { "type": "integer" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "sent", "viewed", "accepted", "declined", "expired" ] }, "currency": { "type": "string" }, "subtotal": { "type": "number" }, "discount_total": { "type": "number" }, "tax_total": { "type": "number" }, "total": { "type": "number" }, "issue_date": { "type": [ "string", "null" ], "format": "date" }, "valid_until": { "type": [ "string", "null" ], "format": "date" }, "deal_id": { "type": [ "integer", "null" ] }, "contact_id": { "type": [ "integer", "null" ] }, "company_id": { "type": [ "integer", "null" ] }, "owner_user_id": { "type": [ "integer", "null" ] }, "locale": { "type": "string" }, "terms": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "buyer": { "type": "object", "additionalProperties": true }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "product_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "qty": { "type": "number" }, "unit_price": { "type": "number" }, "discount_pct": { "type": "number" }, "tax_pct": { "type": "number" }, "total": { "type": "number" } } } }, "view_count": { "type": "integer" }, "sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "sent_via": { "type": [ "string", "null" ] }, "first_viewed_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_viewed_at": { "type": [ "string", "null" ], "format": "date-time" }, "accepted_at": { "type": [ "string", "null" ], "format": "date-time" }, "declined_at": { "type": [ "string", "null" ], "format": "date-time" }, "public_url": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "url": { "type": "string" } } }, "CrmProduct": { "type": "object", "required": [ "id", "name", "price", "currency" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "price": { "type": "number" }, "currency": { "type": "string" }, "tax_pct": { "type": "number" }, "is_active": { "type": "boolean" }, "description": { "type": [ "string", "null" ] }, "image_url": { "type": [ "string", "null" ] }, "source": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "url": { "type": "string" } } }, "CrmWebhookEventName": { "type": "string", "enum": [ "contact.created", "contact.updated", "contact.deleted", "company.created", "company.updated", "company.deleted", "deal.created", "deal.updated", "deal.deleted", "deal.stage_changed", "deal.won", "deal.lost", "task.created", "task.completed", "ticket.created", "quote.sent", "quote.viewed", "quote.accepted" ] }, "CrmWebhookSubscription": { "type": "object", "required": [ "id", "url", "events", "source", "is_active" ], "properties": { "id": { "type": "integer" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/CrmWebhookEventName" } }, "source": { "type": "string", "enum": [ "panel", "zapier", "make", "n8n", "api" ] }, "description": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean" }, "disabled_reason": { "type": [ "string", "null" ], "enum": [ "failures", "gone", "manual", null ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "CrmWebhookEvent": { "type": "object", "required": [ "id", "event", "occurred_at", "data" ], "description": "The JSON body POSTed to a webhook URL. `data` is the record in the same shape the matching GET returns.", "properties": { "id": { "type": "string", "description": "Unique event id (also X-LetsBot-Delivery); use it to de-duplicate." }, "event": { "type": "string" }, "object": { "type": [ "string", "null" ] }, "record_id": { "type": [ "integer", "null" ] }, "occurred_at": { "type": "string", "format": "date-time" }, "data": { "type": [ "object", "null" ], "additionalProperties": true }, "changes": { "type": "object", "description": "`*.updated` only: field → {old, new}.", "additionalProperties": { "type": "object", "properties": { "old": {}, "new": {} } } }, "previous": { "type": "object", "description": "deal.stage_changed / won / lost: the stage and status before.", "properties": { "stage_id": { "type": [ "integer", "null" ] }, "status": { "type": [ "string", "null" ] } } } } } }, "responses": { "LegacyValidationFailure": { "description": "Validation failed (historic contract, the default: HTTP 202, nothing was done). With `X-LetsBot-Validation: strict` the same failure is a 422 `LaravelValidationError`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyValidationFailure" } } } }, "Unauthorized": { "description": "Missing, empty or unknown `lb_api_key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiRefusal" } } } }, "PaymentRequired": { "description": "Subscription expired (`SUBSCRIPTION_EXPIRED`) or no API add-on (`API_ADDON_REQUIRED`). Trials include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiRefusal" } } } }, "Forbidden": { "description": "The key's channel is not attached to a workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiRefusal" } } } }, "NotFound": { "description": "No route for this path and method (the framework's 404).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "Conflict": { "description": "The workspace was merged into another one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantMerged" } } } }, "UseMessagesArchiveConflict": { "description": "An official (Cloud API) number: this endpoint reads a QR session it does not have — use `GET /messages` (`USE_MESSAGES_ARCHIVE`). Also `TENANT_MERGED` when the workspace was merged into another one.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/UseMessagesArchive" }, { "$ref": "#/components/schemas/TenantMerged" } ] } } } }, "SendConflict": { "description": "An earlier request with this Idempotency-Key is still running (`idempotency_request_in_progress`, retry with the same key after `Retry-After`) or died with an unknown outcome (`idempotency_outcome_unknown`: do NOT retry with the same key; check the message first). Also `TENANT_MERGED`.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/IdempotencyError" }, { "$ref": "#/components/schemas/TenantMerged" } ] } } } }, "WritesLocked": { "description": "Workspace writes are temporarily locked (`TENANT_WRITES_LOCKED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LifecycleError" } } } }, "TooManyRequests": { "description": "Rate limit: 1000 requests per minute per channel (`throttle:api`), or WhatsApp throttling (`WHATSAPP_RATE_LIMITED`).", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ThrottleError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "SendTooManyRequests": { "description": "Rate limit (1000/min per channel), WhatsApp throttling, or the workspace's daily API send limit (`automation_daily_limit_reached`; `Retry-After` can be hours).", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ThrottleError" }, { "$ref": "#/components/schemas/AutomationLimitError" }, { "$ref": "#/components/schemas/MetaRejection" } ] } } } }, "InternalError": { "description": "Unexpected failure. Quote `reference` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } }, "BadGateway": { "description": "WhatsApp (Meta) failed on its side; a retry may succeed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetaRejection" } } } }, "LifecycleUnavailable": { "description": "Workspace state temporarily unavailable (`TENANT_LIFECYCLE_INVALID`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LifecycleError" } } } }, "ZapierUnauthorized": { "description": "Missing or unknown `X-Zapier-Api-Key` (or expired legacy bearer token).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZapierError" } } } }, "ZapierMissingScope": { "description": "The key lacks the scope this operation needs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZapierError" } } } }, "ZapierFailure": { "description": "Refused: `{success: false, error, code}` (or a framework validation error).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZapierError" } } } }, "CrmNotFound": { "description": "Not found — also the answer for every CRM path while the workspace has not adopted the CRM.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrmError" } } } }, "CrmForbidden": { "description": "The key does not list the `crm` scope (`code: missing_scope`). Keys with no scopes (\"full access\") do not include it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrmError" } } } }, "CrmValidationFailed": { "description": "Validation failed (`code: validation_failed`, `errors` per field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrmError" } } } }, "CrmConflict": { "description": "Conflict (`already_exists` with the existing record in `data`, or `conflict`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrmError" } } } } } } }