{ "openapi": "3.0.0", "info": { "title": "Blueticks API", "version": "2.0.0", "description": "Public API for Blueticks WhatsApp automation." }, "servers": [ { "url": "https://api.blueticks.co" } ], "tags": [ { "name": "Account", "description": "Account metadata for the authenticated API key." }, { "name": "Audiences", "description": "Reusable contact lists used as targets for messages and campaigns." }, { "name": "Boards", "description": "AI-managed memory boards (Tasks, Leads). Each board is a normal Blueticks board with an AI agent config; items are board tasks with status/priority cells plus AI dedupe/provenance metadata." }, { "name": "Campaigns", "description": "Schedule audiences for paced bulk delivery with pause/resume/cancel controls." }, { "name": "Chats", "description": "Read and manage WhatsApp chats on the connected engine." }, { "name": "Contacts", "description": "Read WhatsApp contacts known to the connected engine." }, { "name": "Engines", "description": "Inspect or control the WhatsApp engine(s) connected to the workspace." }, { "name": "Groups", "description": "Create and manage WhatsApp groups via the connected engine." }, { "name": "Messages", "description": "Send, list, search, react to, and fetch media for individual WhatsApp messages on the connected engine." }, { "name": "Newsletters", "description": "Create and inspect WhatsApp newsletters (channels) via the connected engine." }, { "name": "Ping", "description": "Connectivity probe for the Blueticks API and the account's WhatsApp engine(s)." }, { "name": "Scheduled Messages", "description": "Send or schedule WhatsApp messages via the user-messages queue. Each request creates a queued send — set `sendAt` (RFC 3339) to defer delivery, omit it to send immediately. List, retrieve, edit, and cancel queued sends." }, { "name": "Suno", "description": "Generate songs on Suno from lyrics + style, and poll their progress." }, { "name": "Webhooks", "description": "Register URLs to receive HTTPS POSTs on Blueticks events." } ], "paths": { "/v1/ping": { "get": { "tags": [ "Ping" ], "summary": "Ping", "description": "Health and connectivity probe. Confirms the Blueticks API server is live (`api: \"ok\"`) and lists the WhatsApp engines currently connected to this account in `whatsappConnections`. Each connection is labelled `gateway` (a remote, server-side engine — the Blueticks 24/7 gateway / baileys pod) or `regular` (the user's own WhatsApp Web browser extension). An empty `whatsappConnections` array means no WhatsApp is connected — this is not an error, and `message` explains it. Requires a valid API key; no scope required.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "api": { "type": "string", "enum": [ "ok" ], "description": "Blueticks API server liveness. \"ok\" means the API server is up and served this request." }, "accountId": { "type": "string", "description": "The account (workspace) the API key belongs to." }, "whatsappConnections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable id of the live engine session (its MQTT presence client id)." }, "type": { "type": "string", "enum": [ "gateway", "regular" ], "description": "Engine kind. \"gateway\" = a remote, server-side engine (Blueticks 24/7 gateway / baileys pod). \"regular\" = the user's own WhatsApp Web browser extension." }, "connected": { "type": "boolean", "enum": [ true ], "description": "Always true — an entry appears only while its presence heartbeat is live." } }, "required": [ "id", "type", "connected" ], "additionalProperties": false }, "description": "WhatsApp engines currently connected for this account. Empty means no WhatsApp is connected." }, "message": { "type": "string", "description": "Present only when whatsappConnections is empty; explains the empty state." } }, "required": [ "api", "accountId", "whatsappConnections" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "ping.list" } }, "/v1/account": { "get": { "tags": [ "Account" ], "summary": "Get account", "description": "Retrieve the account the API key belongs to.", "security": [ { "BearerAuth": [ "account:read" ] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier for the account." }, "name": { "type": "string", "description": "Account display name." }, "userEmail": { "type": "string", "description": "Email address of the user the API key belongs to, or null if unavailable." }, "timezone": { "type": "string", "description": "IANA timezone (e.g. \"America/New_York\"), or null if unset." }, "createdAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp of account creation." } }, "required": [ "id", "name", "createdAt" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "account.list" } }, "/v1/scheduled-messages": { "get": { "tags": [ "Scheduled Messages" ], "summary": "List scheduled messages", "description": "List messages in the user-messages queue (all sources: API, dashboard, extension), newest first (offset-paginated). Optionally filter by `chatId` and/or lifecycle `status`.", "security": [ { "BearerAuth": [ "messages:read" ] } ], "parameters": [ { "name": "chatId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9]+(?:-[0-9]+)?@(?:c\\.us|g\\.us|newsletter)$" }, "description": "Filter to messages addressed to this WhatsApp JID. Matches the recipient stored on the queued/scheduled doc — for sends to a phone number, the JID is `@c.us`." }, { "name": "searchToken", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Search token; when set, only items whose name matches are returned." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "before-wa-send", "bt-sent", "sending", "sent", "sent_pending_ack", "confirmed", "delivered", "received", "read", "played", "cancelled", "error", "failed", "expired" ] }, "description": "Filter by lifecycle status: `pending` (accepted, waiting), `confirmed` (WhatsApp accepted — has waMessageKey), `received` (double grey tick), `read` (double blue tick), `played` (voice played), `failed`." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Sort direction by timestamp: `asc` (oldest first) or `desc` (newest first, default)." }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of items to skip before the page (default 0)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Page size (1-200, default 50)." } ], "responses": { "200": { "description": "messages", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Primary handle for the message. Scheduled sends: the queue id (accepted by GET/cancel /v1/scheduled-messages/{id}). Direct sends: the serialized WhatsApp message key (== waMessageKey._serialized), accepted by GET /v1/messages/{id}." }, "waMessageKey": { "type": "object", "properties": { "fromMe": { "type": "boolean" }, "remote": { "type": "string" }, "id": { "type": "string" }, "_serialized": { "type": "string" }, "participant": { "type": "string" } }, "required": [ "fromMe" ], "additionalProperties": false }, "to": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "media", "poll" ], "description": "Message kind that was sent." }, "text": { "type": "string" }, "mediaUrl": { "type": "string" }, "mediaKind": { "type": "string", "enum": [ "image", "video", "audio", "document", "sticker", "voice", "gif" ] }, "pollQuestion": { "type": "string" }, "pollOptions": { "type": "array", "items": { "type": "string" }, "description": "Poll option labels in order (type=poll). Null for non-poll messages." }, "pollAllowMultiple": { "type": "boolean", "description": "Whether the poll accepts multiple selections (type=poll). Null for non-poll messages." }, "status": { "type": "string", "enum": [ "pending", "before-wa-send", "bt-sent", "sending", "sent", "sent_pending_ack", "confirmed", "delivered", "received", "read", "played", "cancelled", "error", "failed", "expired" ] }, "sendAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "confirmedAt": { "type": "string", "format": "date-time" }, "receivedAt": { "type": "string", "format": "date-time" }, "readAt": { "type": "string", "format": "date-time" }, "playedAt": { "type": "string", "format": "date-time" }, "failedAt": { "type": "string", "format": "date-time" }, "failureReason": { "type": "string" }, "secret": { "type": "string", "description": "Opaque correlation token carried on the message. Echoes the `secret` you sent (or the engine-encoded internal id when you omitted it), and is carried into WhatsApp's `messageSecret`. Null until a queued/scheduled send dispatches." }, "linkPreview": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "canonicalUrl": { "type": "string" }, "thumbnail": { "type": "string" } }, "additionalProperties": false } }, "required": [ "to", "type", "status", "createdAt" ], "additionalProperties": false } }, "limit": { "type": "integer", "description": "Page size echoed back from the request." }, "skip": { "type": "integer", "description": "Offset echoed back from the request." }, "total": { "type": "integer", "description": "Total number of items matching the query, across all pages." } }, "required": [ "success", "data", "limit", "skip", "total" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "scheduled-messages.list" } }, "/v1/scheduled-messages/{id}": { "get": { "tags": [ "Scheduled Messages" ], "summary": "Get scheduled message", "description": "Get the current status of a message by ID.", "security": [ { "BearerAuth": [ "messages:read" ] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Primary handle for the message. Scheduled sends: the queue id (accepted by GET/cancel /v1/scheduled-messages/{id}). Direct sends: the serialized WhatsApp message key (== waMessageKey._serialized), accepted by GET /v1/messages/{id}." }, "waMessageKey": { "type": "object", "properties": { "fromMe": { "type": "boolean" }, "remote": { "type": "string" }, "id": { "type": "string" }, "_serialized": { "type": "string" }, "participant": { "type": "string" } }, "required": [ "fromMe" ], "additionalProperties": false }, "to": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "media", "poll" ], "description": "Message kind that was sent." }, "text": { "type": "string" }, "mediaUrl": { "type": "string" }, "mediaKind": { "type": "string", "enum": [ "image", "video", "audio", "document", "sticker", "voice", "gif" ] }, "pollQuestion": { "type": "string" }, "pollOptions": { "type": "array", "items": { "type": "string" }, "description": "Poll option labels in order (type=poll). Null for non-poll messages." }, "pollAllowMultiple": { "type": "boolean", "description": "Whether the poll accepts multiple selections (type=poll). Null for non-poll messages." }, "status": { "type": "string", "enum": [ "pending", "before-wa-send", "bt-sent", "sending", "sent", "sent_pending_ack", "confirmed", "delivered", "received", "read", "played", "cancelled", "error", "failed", "expired" ] }, "sendAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "confirmedAt": { "type": "string", "format": "date-time" }, "receivedAt": { "type": "string", "format": "date-time" }, "readAt": { "type": "string", "format": "date-time" }, "playedAt": { "type": "string", "format": "date-time" }, "failedAt": { "type": "string", "format": "date-time" }, "failureReason": { "type": "string" }, "secret": { "type": "string", "description": "Opaque correlation token carried on the message. Echoes the `secret` you sent (or the engine-encoded internal id when you omitted it), and is carried into WhatsApp's `messageSecret`. Null until a queued/scheduled send dispatches." }, "linkPreview": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "canonicalUrl": { "type": "string" }, "thumbnail": { "type": "string" } }, "additionalProperties": false } }, "required": [ "to", "type", "status", "createdAt" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "operationId": "scheduled-messages.get" }, "patch": { "tags": [ "Scheduled Messages" ], "summary": "Update scheduled message", "description": "Edit a previously-queued message that has not dispatched yet (status `pending`).\n\nAccepts the **same flat body fields as [Schedule message](#schedule-message)** — `type`, `text`, `mediaUrl`, `mediaBase64`, `mediaKind`, `mediaFilename`, `pollQuestion`, `pollOptions`, `pollAllowMultiple`, `sendAt`, `replyTo`, `secret` — but **every field is optional**. Send only the fields you want to change; at least one is required. The recipient is fixed at schedule time (it was the `{chatId}` path param) and cannot be changed here.\n\nNotes:\n- A new `mediaUrl` / `mediaBase64` is re-hosted to GCS just like on create; `mediaKind` / `mediaFilename` can be edited on their own.\n- Editing `text` re-derives the link-preview card (auto-attached when the text contains a URL).\n- `sendAt` reschedules (must be ≥10s in the future, ≤365 days).\n- Returns 400 once the message has advanced past the editable window (status not `pending`).", "security": [ { "BearerAuth": [ "messages:write" ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text", "media", "poll" ] }, "text": { "type": "string", "maxLength": 4096, "description": "Text body (required for type=text) or optional media caption (type=media). Up to 4096 chars. Mention a contact inline with `@[Display Name]()`, e.g. `Hi @[Jon Daw](xxxxxxxxxxxx@c.us)`." }, "mediaUrl": { "type": "string", "maxLength": 2048, "description": "Media source URL (https only). One of mediaUrl or mediaBase64 is required for media sends; mediaUrl wins when both are present." }, "mediaBase64": { "type": "string", "maxLength": 15728640, "description": "Raw media bytes, base64-encoded (or a data: URL). Used when mediaUrl is absent. For a file upload, send multipart/form-data with a `mediaFile` part instead — it is converted to this." }, "mediaKind": { "type": "string", "enum": [ "image", "video", "audio", "document", "sticker", "voice", "gif" ], "description": "Media kind (image · video · audio · document · sticker · voice · gif). Optional — auto-detected from the URL / content-type when omitted." }, "mediaFilename": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Filename shown on the attachment (type=media). Optional — derived from the URL / uploaded file when omitted." }, "sendAt": { "type": "string", "format": "date-time" }, "replyTo": { "type": "string", "maxLength": 256, "description": "Wire `key` of a prior message to quote-reply (from MessageResponse.key). Empty string = no reply." }, "secret": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Opaque correlation token you choose to tag this message with. It is stored on the message and carried into WhatsApp's `messageSecret`, so you can match it back to your own records later. NOT a deduplication key: sending the same `secret` twice creates two separate messages. To make retries safe (at-most-once send), use the `Idempotency-Key` header instead. When omitted, the API encodes the internal message id here for delivery-status matching — only set this if you have your own correlation scheme." }, "pollQuestion": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Poll question (type=poll). Required for poll sends." }, "pollAllowMultiple": { "type": "boolean", "description": "Allow selecting multiple poll options (type=poll). Default false." }, "pollOptions": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": "Poll options (type=poll). 2–12 items." } }, "additionalProperties": false }, "examples": { "edit_text": { "summary": "Change the text body", "value": { "text": "Updated reminder: meeting moved to 4pm" } }, "reschedule": { "summary": "Reschedule only", "value": { "sendAt": "2026-12-31T15:00:00Z" } }, "swap_media": { "summary": "Replace the attached media", "value": { "mediaUrl": "https://cdn.example.com/new.pdf", "mediaKind": "document", "mediaFilename": "new.pdf" } }, "edit_poll": { "summary": "Edit poll question and options", "value": { "pollQuestion": "Pizza or sushi?", "pollOptions": [ "Pizza", "Sushi" ] } } } } } }, "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Primary handle for the message. Scheduled sends: the queue id (accepted by GET/cancel /v1/scheduled-messages/{id}). Direct sends: the serialized WhatsApp message key (== waMessageKey._serialized), accepted by GET /v1/messages/{id}." }, "waMessageKey": { "type": "object", "properties": { "fromMe": { "type": "boolean" }, "remote": { "type": "string" }, "id": { "type": "string" }, "_serialized": { "type": "string" }, "participant": { "type": "string" } }, "required": [ "fromMe" ], "additionalProperties": false }, "to": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "media", "poll" ], "description": "Message kind that was sent." }, "text": { "type": "string" }, "mediaUrl": { "type": "string" }, "mediaKind": { "type": "string", "enum": [ "image", "video", "audio", "document", "sticker", "voice", "gif" ] }, "pollQuestion": { "type": "string" }, "pollOptions": { "type": "array", "items": { "type": "string" }, "description": "Poll option labels in order (type=poll). Null for non-poll messages." }, "pollAllowMultiple": { "type": "boolean", "description": "Whether the poll accepts multiple selections (type=poll). Null for non-poll messages." }, "status": { "type": "string", "enum": [ "pending", "before-wa-send", "bt-sent", "sending", "sent", "sent_pending_ack", "confirmed", "delivered", "received", "read", "played", "cancelled", "error", "failed", "expired" ] }, "sendAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "confirmedAt": { "type": "string", "format": "date-time" }, "receivedAt": { "type": "string", "format": "date-time" }, "readAt": { "type": "string", "format": "date-time" }, "playedAt": { "type": "string", "format": "date-time" }, "failedAt": { "type": "string", "format": "date-time" }, "failureReason": { "type": "string" }, "secret": { "type": "string", "description": "Opaque correlation token carried on the message. Echoes the `secret` you sent (or the engine-encoded internal id when you omitted it), and is carried into WhatsApp's `messageSecret`. Null until a queued/scheduled send dispatches." }, "linkPreview": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "canonicalUrl": { "type": "string" }, "thumbnail": { "type": "string" } }, "additionalProperties": false } }, "required": [ "to", "type", "status", "createdAt" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "operationId": "scheduled-messages.update" }, "delete": { "tags": [ "Scheduled Messages" ], "summary": "Delete scheduled message", "description": "Delete a scheduled or queued message so it will not be sent. Soft-deletes the message (and records a cancellation in its delivery log). Returns 404 if no pending/queued message with this id is owned by the caller.", "security": [ { "BearerAuth": [ "messages:write" ] } ], "responses": { "200": { "description": "deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Id of the deleted message." }, "deleted": { "type": "boolean", "enum": [ true ], "description": "Always true on a successful delete." } }, "required": [ "id", "deleted" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "operationId": "scheduled-messages.delete" } }, "/v1/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List webhooks", "description": "List webhooks in the workspace.", "security": [ { "BearerAuth": [ "webhooks:read" ] } ], "parameters": [ { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Sort direction by timestamp: `asc` (oldest first) or `desc` (newest first, default)." }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of items to skip before the page (default 0)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Page size (default 50, max 200)." } ], "responses": { "200": { "description": "list", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "url", "events", "status", "createdAt" ], "additionalProperties": false } }, "limit": { "type": "integer", "description": "Page size echoed back from the request." }, "skip": { "type": "integer", "description": "Offset echoed back from the request." }, "total": { "type": "integer", "description": "Total number of items matching the query, across all pages." } }, "required": [ "success", "data", "limit", "skip", "total" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "webhooks.list" }, "post": { "tags": [ "Webhooks" ], "summary": "Create webhook", "description": "Register a new webhook.", "security": [ { "BearerAuth": [ "webhooks:write" ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "events": { "type": "array", "items": { "type": "string", "enum": [ "message.queued", "message.sending", "message.delivered", "message.failed", "message.read", "session.connected", "session.disconnected", "campaign.started", "campaign.paused", "campaign.resumed", "campaign.completed", "campaign.aborted", "new_message_received_webhook", "message_reaction_webhook", "ack_changed_webhook", "participant_joined_via_link_webhook", "participant_added_by_admin_webhook", "participant_left_group_webhook", "participant_kicked_from_group_webhook", "group_admin_changed_webhook", "group_name_changed_webhook", "group_description_changed_webhook", "group_message_pinned_webhook", "poll_vote_webhook", "reply_to_my_message_webhook", "message_deleted_revoked_webhook", "message_edited_webhook" ] }, "minItems": 1 }, "description": { "type": "string", "maxLength": 120 } }, "required": [ "url", "events" ], "additionalProperties": false }, "examples": { "delivery_status": { "summary": "Subscribe to delivery lifecycle events", "value": { "url": "https://example.com/webhooks/blueticks", "events": [ "message.queued", "message.sending", "message.delivered", "message.read", "message.failed" ], "description": "Delivery lifecycle stream" } }, "inbound_messages": { "summary": "Receive inbound messages", "value": { "url": "https://example.com/webhooks/inbound", "events": [ "new_message_received_webhook" ], "description": "Inbound message stream" } } } } } }, "responses": { "201": { "description": "created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "url", "events", "status", "createdAt" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "webhooks.create" } }, "/v1/webhooks/{id}": { "get": { "tags": [ "Webhooks" ], "summary": "Get webhook", "description": "Get a webhook by id.", "security": [ { "BearerAuth": [ "webhooks:read" ] } ], "responses": { "200": { "description": "webhook", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "url", "events", "status", "createdAt" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "operationId": "webhooks.get" }, "patch": { "tags": [ "Webhooks" ], "summary": "Update webhook", "description": "Update a webhook.", "security": [ { "BearerAuth": [ "webhooks:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "events": { "type": "array", "items": { "type": "string", "enum": [ "message.queued", "message.sending", "message.delivered", "message.failed", "message.read", "session.connected", "session.disconnected", "campaign.started", "campaign.paused", "campaign.resumed", "campaign.completed", "campaign.aborted", "new_message_received_webhook", "message_reaction_webhook", "ack_changed_webhook", "participant_joined_via_link_webhook", "participant_added_by_admin_webhook", "participant_left_group_webhook", "participant_kicked_from_group_webhook", "group_admin_changed_webhook", "group_name_changed_webhook", "group_description_changed_webhook", "group_message_pinned_webhook", "poll_vote_webhook", "reply_to_my_message_webhook", "message_deleted_revoked_webhook", "message_edited_webhook" ] }, "minItems": 1 }, "description": { "type": "string", "maxLength": 120, "nullable": true }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "url", "events", "status", "createdAt" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "webhooks.update" }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete webhook", "description": "Delete a webhook.", "security": [ { "BearerAuth": [ "webhooks:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "id", "deleted" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "webhooks.delete" } }, "/v1/audiences": { "get": { "tags": [ "Audiences" ], "summary": "List audiences", "description": "List the audiences in your workspace, newest first. Offset-paginated via `limit` + `skip`. Requires `audiences:read`.", "security": [ { "BearerAuth": [ "audiences:read" ] } ], "parameters": [ { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Sort direction by timestamp: `asc` (oldest first) or `desc` (newest first, default)." }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of items to skip before the page (default 0)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Page size (default 50, max 200)." } ], "responses": { "200": { "description": "audiences", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "contactCount": { "type": "integer", "minimum": 0 }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "contactCount", "createdAt" ], "additionalProperties": false } }, "limit": { "type": "integer", "description": "Page size echoed back from the request." }, "skip": { "type": "integer", "description": "Offset echoed back from the request." }, "total": { "type": "integer", "description": "Total number of items matching the query, across all pages." } }, "required": [ "success", "data", "limit", "skip", "total" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "audiences.list" }, "post": { "tags": [ "Audiences" ], "summary": "Create audience", "description": "Create a new audience. Returns the audience with `contactCount: 0`. Requires `audiences:write`.", "security": [ { "BearerAuth": [ "audiences:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "contacts": { "type": "array", "items": { "type": "object", "properties": { "to": { "type": "string", "description": "Recipient. A phone number (+E164), or a WhatsApp JID — individual (…@c.us), group (…@g.us), or newsletter (…@newsletter). Individual recipients are stored in international format; group/newsletter ids are stored verbatim." }, "variables": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 1024 }, "description": "Per-contact substitution values used by campaign templates.\nEach key becomes a token usable as `{key}` in a campaign `text`. Lookup is case-insensitive (e.g. `{firstName}` resolves `firstname`).\nBuilt-in tokens always available regardless of variables: `{whatsappname}`, `{displayname}`, `{phone}`, `{mobile}`. Setting a variable with the same name overrides the built-in.\nStorage: keys are persisted as text-cell column titles on the audience board, so values flow back via audiences.get under the same names.\nLimits: at most 32 keys per contact; values up to 1024 chars; keys must match /^[A-Za-z_][A-Za-z0-9_]{0,31}$/." } }, "required": [ "to" ], "additionalProperties": false }, "maxItems": 1000 } }, "required": [ "name" ], "additionalProperties": false }, "examples": { "empty": { "summary": "Empty audience (add contacts later)", "value": { "name": "Q4 Newsletter Recipients" } }, "with_contacts": { "summary": "Audience seeded with contacts and variables", "value": { "name": "Q4 Newsletter Recipients", "contacts": [ { "to": "+15555550100", "variables": { "firstname": "Alex", "plan": "pro" } }, { "to": "+15555550101", "variables": { "firstname": "Sam", "plan": "free" } } ] } } } } } }, "responses": { "200": { "description": "created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "contactCount": { "type": "integer", "minimum": 0 }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "contactCount", "createdAt" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "audiences.create" } }, "/v1/audiences/{id}": { "get": { "tags": [ "Audiences" ], "summary": "Get audience", "description": "Retrieve a single audience by id, including its `contactCount` and variable schema. Requires `audiences:read`.", "security": [ { "BearerAuth": [ "audiences:read" ] } ], "responses": { "200": { "description": "audience", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "contactCount": { "type": "integer", "minimum": 0 }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "contactCount", "createdAt" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "operationId": "audiences.get" }, "patch": { "tags": [ "Audiences" ], "summary": "Update audience", "description": "Rename an audience or update its variable schema. Requires `audiences:write`.", "security": [ { "BearerAuth": [ "audiences:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "contactCount": { "type": "integer", "minimum": 0 }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "contactCount", "createdAt" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "audiences.update" }, "delete": { "tags": [ "Audiences" ], "summary": "Delete audience", "description": "Soft-delete an audience. 409 if it's referenced by an active campaign. Returns the deleted ref. Requires `audiences:write`.", "security": [ { "BearerAuth": [ "audiences:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "id", "deleted" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "audiences.delete" } }, "/v1/boards": { "get": { "tags": [ "Boards" ], "summary": "List boards", "description": "List boards, newest first. Filter by `domain` or `agent_managed`. Requires `boards:read`.", "security": [ { "BearerAuth": [ "boards:read" ] } ], "parameters": [ { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Sort direction by timestamp: `asc` (oldest first) or `desc` (newest first, default)." }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of items to skip before the page (default 0)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Page size (default 50, max 200)." } ], "responses": { "200": { "description": "boards", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "array", "items": { "type": "object", "properties": { "board_id": { "type": "string" }, "name": { "type": "string" }, "domain": { "type": "string" }, "agent_managed": { "type": "boolean" }, "memory_retention_days": { "type": "integer" }, "item_count": { "type": "integer" }, "web_url": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "board_id", "name", "agent_managed", "web_url", "created_at", "updated_at" ], "additionalProperties": false } }, "limit": { "type": "integer", "description": "Page size echoed back from the request." }, "skip": { "type": "integer", "description": "Offset echoed back from the request." }, "total": { "type": "integer", "description": "Total number of items matching the query, across all pages." } }, "required": [ "success", "data", "limit", "skip", "total" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "boards.list" }, "post": { "tags": [ "Boards" ], "summary": "Create or find board", "description": "Find-or-create the agent memory board for (`agent_id`, `domain`). Returns the existing board if one exists, else provisions it from the domain template. Requires `boards:write`.", "security": [ { "BearerAuth": [ "boards:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "minLength": 1, "description": "Memory domain id for a built-in board — `tasks`, `leads` or `invoices`. Omit and pass `entity_kind` to open a board for a NEW entity type." }, "entity_kind": { "type": "string", "minLength": 1, "maxLength": 40, "description": "The kind of entity this board tracks (e.g. `reminders`, `orders`, `follow-ups`). Opens a NEW dynamic board with a generic Status/Priority/Date/Source template. Slug-ified server-side; a `custom:` domain is derived unless the slug already names a built-in domain. `description` is REQUIRED for custom boards." }, "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Board name; defaults to the domain label (custom: `🤖 `)." }, "description": { "type": "string", "minLength": 1, "maxLength": 500, "description": "One-line purpose of the board (subtitle + board directory). Optional for built-in domains (falls back to the domain default); REQUIRED for custom `entity_kind` boards (422 if missing)." }, "agent_id": { "type": "string", "maxLength": 200, "description": "Owning agent id for memory isolation (e.g. `btgpt:` or `bot:`). Defaults to `user`." }, "memory_retention_days": { "type": "integer", "minimum": 0, "maximum": 3650, "description": "Retention window in days (default 30; 0 = never expires)." } }, "additionalProperties": false }, "examples": { "tasks": { "summary": "Tasks board for btgpt", "value": { "domain": "tasks", "agent_id": "btgpt:USER_ID" } }, "leads": { "summary": "Leads board, 90-day retention", "value": { "domain": "leads", "agent_id": "bot:BOT_ID", "memory_retention_days": 90 } } } } } }, "responses": { "200": { "description": "board", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "board_id": { "type": "string" }, "name": { "type": "string" }, "domain": { "type": "string" }, "agent_managed": { "type": "boolean" }, "memory_retention_days": { "type": "integer" }, "item_count": { "type": "integer" }, "web_url": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "columns": { "type": "array", "items": { "type": "object", "properties": { "column_id": { "type": "string" }, "title": { "type": "string" }, "type": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "bgcolor": { "type": "string" } }, "required": [ "label", "bgcolor" ], "additionalProperties": false }, "description": "Selectable options (status/priority columns); empty otherwise." } }, "required": [ "column_id", "title", "type", "options" ], "additionalProperties": false } } }, "required": [ "board_id", "name", "agent_managed", "web_url", "created_at", "updated_at", "columns" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "boards.create" } }, "/v1/boards/{id}": { "get": { "tags": [ "Boards" ], "summary": "Get board", "description": "Retrieve a board with its columns, options and item count. Requires `boards:read`.", "security": [ { "BearerAuth": [ "boards:read" ] } ], "responses": { "200": { "description": "board", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "board_id": { "type": "string" }, "name": { "type": "string" }, "domain": { "type": "string" }, "agent_managed": { "type": "boolean" }, "memory_retention_days": { "type": "integer" }, "item_count": { "type": "integer" }, "web_url": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "columns": { "type": "array", "items": { "type": "object", "properties": { "column_id": { "type": "string" }, "title": { "type": "string" }, "type": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "bgcolor": { "type": "string" } }, "required": [ "label", "bgcolor" ], "additionalProperties": false }, "description": "Selectable options (status/priority columns); empty otherwise." } }, "required": [ "column_id", "title", "type", "options" ], "additionalProperties": false } } }, "required": [ "board_id", "name", "agent_managed", "web_url", "created_at", "updated_at", "columns" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "operationId": "boards.get" } }, "/v1/campaigns": { "get": { "tags": [ "Campaigns" ], "summary": "List campaigns", "description": "List the campaigns in your workspace, newest first, each with its live counters (`sentCount`, `deliveredCount`, `readCount`, `failedCount`). Offset-paginated via `limit` + `skip`. Requires `campaigns:read`.", "security": [ { "BearerAuth": [ "campaigns:read" ] } ], "parameters": [ { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Sort direction by timestamp: `asc` (oldest first) or `desc` (newest first, default)." }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of items to skip before the page (default 0)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Page size (default 50, max 200)." } ], "responses": { "200": { "description": "campaigns", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "array", "items": { "type": "object", "properties": { "cmpId": { "type": "string" }, "name": { "type": "string" }, "audienceId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "running", "paused", "complete_sent", "complete_delivered", "aborted" ] }, "totalCount": { "type": "integer", "minimum": 0 }, "sentCount": { "type": "integer", "minimum": 0 }, "deliveredCount": { "type": "integer", "minimum": 0 }, "readCount": { "type": "integer", "minimum": 0 }, "failedCount": { "type": "integer", "minimum": 0 }, "createdAt": { "type": "string", "format": "date-time" }, "startedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time" }, "abortedAt": { "type": "string", "format": "date-time" } }, "required": [ "cmpId", "name", "audienceId", "status", "totalCount", "sentCount", "deliveredCount", "readCount", "failedCount", "createdAt" ], "additionalProperties": false } }, "limit": { "type": "integer", "description": "Page size echoed back from the request." }, "skip": { "type": "integer", "description": "Offset echoed back from the request." }, "total": { "type": "integer", "description": "Total number of items matching the query, across all pages." } }, "required": [ "success", "data", "limit", "skip", "total" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "campaigns.list" }, "post": { "tags": [ "Campaigns" ], "summary": "Create campaign", "description": "Schedule a new bulk-message campaign. Returns the campaign in `pending` state. Requires `campaigns:write`.", "security": [ { "BearerAuth": [ "campaigns:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Display name for the campaign." }, "audienceId": { "type": "string", "minLength": 1, "description": "ID of the audience to target. Each audience contact contributes one outgoing message." }, "text": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Message body. Supports per-contact substitution using single-brace tokens like `{firstName}` or `{product}`.\nResolution rules (case-insensitive, whitespace stripped):\n - Built-ins always available: `{whatsappname}` (WA profile name), `{displayname}` (firstname+lastname fallback), `{phone}` / `{mobile}`.\n - Custom variables: every property attached to a contact via audiences.append_contacts becomes a token of the same name.\n - Unresolved tokens are left as literal `{token}` in the sent message.\nTemplates use SINGLE braces `{var}` — `{{var}}` is treated as literal text." }, "mediaUrl": { "type": "string", "format": "uri", "maxLength": 2048, "description": "Public https URL of an image/video/document to attach." }, "mediaCaption": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "Caption for the media attachment. Requires mediaUrl." }, "onMissingVariable": { "type": "string", "enum": [ "fail", "skip" ], "description": "Behavior when a template references a variable that is not present on a contact:\n - `fail` (default): reject the request at create time; no messages are sent. Returns 400 with `data.examples` listing offending contacts.\n - `skip`: accept the campaign; contacts missing variables receive the message with literal `{token}` left in place." } }, "required": [ "name", "audienceId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "cmpId": { "type": "string" }, "name": { "type": "string" }, "audienceId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "running", "paused", "complete_sent", "complete_delivered", "aborted" ] }, "totalCount": { "type": "integer", "minimum": 0 }, "sentCount": { "type": "integer", "minimum": 0 }, "deliveredCount": { "type": "integer", "minimum": 0 }, "readCount": { "type": "integer", "minimum": 0 }, "failedCount": { "type": "integer", "minimum": 0 }, "createdAt": { "type": "string", "format": "date-time" }, "startedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time" }, "abortedAt": { "type": "string", "format": "date-time" } }, "required": [ "cmpId", "name", "audienceId", "status", "totalCount", "sentCount", "deliveredCount", "readCount", "failedCount", "createdAt" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "campaigns.create" } }, "/v1/campaigns/{id}": { "get": { "tags": [ "Campaigns" ], "summary": "Get campaign", "description": "Retrieve a single campaign by id, including its status and live delivery counters. Poll this to track progress. Requires `campaigns:read`.", "security": [ { "BearerAuth": [ "campaigns:read" ] } ], "responses": { "200": { "description": "campaign", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "cmpId": { "type": "string" }, "name": { "type": "string" }, "audienceId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "running", "paused", "complete_sent", "complete_delivered", "aborted" ] }, "totalCount": { "type": "integer", "minimum": 0 }, "sentCount": { "type": "integer", "minimum": 0 }, "deliveredCount": { "type": "integer", "minimum": 0 }, "readCount": { "type": "integer", "minimum": 0 }, "failedCount": { "type": "integer", "minimum": 0 }, "createdAt": { "type": "string", "format": "date-time" }, "startedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time" }, "abortedAt": { "type": "string", "format": "date-time" } }, "required": [ "cmpId", "name", "audienceId", "status", "totalCount", "sentCount", "deliveredCount", "readCount", "failedCount", "createdAt" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "operationId": "campaigns.get" } }, "/v1/chats": { "get": { "tags": [ "Chats" ], "summary": "List chats", "description": "List the chats (conversations) the connected WhatsApp engine sees, most-recent first. Offset-paginated via `limit` + `skip`, with an optional case-insensitive substring search on the chat name via `searchToken` and a `filter` to restrict to one chat kind. Requires `chats:read`.", "security": [ { "BearerAuth": [ "chats:read" ] } ], "parameters": [ { "name": "searchToken", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Search token; when set, only items whose name matches are returned." }, { "name": "filter", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "groups", "contacts", "newsletters" ] }, "description": "Restrict to one chat kind." }, { "name": "kinds", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "contact", "group", "newsletter" ] }, "minItems": 1 }, "description": "Keep only these chat kinds (INCLUDE semantics). Comma-separated or repeated." }, { "name": "since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Keep only chats whose last message is at/after this ISO 8601 instant (offset allowed; approximate — see sinceApplied)." }, { "name": "includeLastMessage", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Include the last message snippet on each chat row." }, { "name": "includeExtendedInfo", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Include extended chat metadata (engine-side opt-in)." }, { "name": "includeWithoutName", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Include chats with no resolved name (default: skipped)." }, { "name": "includeArchive", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Include archived chats (default false → archived excluded)." }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of items to skip before the page (default 0)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Page size (1-200, default 50)." } ], "responses": { "200": { "description": "chats", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "array", "items": { "type": "object", "properties": { "chatId": { "type": "string", "description": "WhatsApp JID of the chat — `@c.us` for a 1:1 contact, `@g.us` for a group, `@newsletter` for a channel." }, "name": { "type": "string", "description": "Display name of the chat (contact name, group subject, or channel title). Null when WhatsApp has no name for it." }, "chatType": { "type": "string", "enum": [ "contact", "group", "newsletter" ], "description": "Kind of chat: `contact` (1:1), `group`, or `newsletter` (WhatsApp Channel). The three are mutually exclusive." }, "pinned": { "type": "boolean", "description": "True when the chat is pinned to the top of the chat list." }, "archived": { "type": "boolean", "description": "True when the chat is archived. Excluded from list responses unless `includeArchive=true`." }, "lastMessageAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp of the most recent message in this chat. Null when the chat has no messages." }, "unreadCount": { "type": "integer", "minimum": 0, "description": "Count of unseen incoming messages (>= 0). Excludes the \"manually marked unread\" sentinel — see `markedUnread`." }, "markedUnread": { "type": "boolean", "description": "True when the chat was manually flagged unread in WhatsApp (the dot badge), distinct from having N unread messages." }, "lastMessageText": { "type": "string", "description": "Preview text of the most recent message. Present only when includeLastMessage=true." }, "lastMessageFromMe": { "type": "boolean", "description": "True if the last message was sent by the connected account. Present only when includeLastMessage=true." } }, "required": [ "chatId", "chatType", "markedUnread" ], "additionalProperties": false, "description": "A WhatsApp chat (conversation) — a 1:1 contact, a group, or a channel — as seen by the connected engine." } }, "limit": { "type": "integer", "description": "Page size echoed back from the request." }, "skip": { "type": "integer", "description": "Offset echoed back from the request." }, "total": { "type": "integer", "description": "Total number of items matching the query, across all pages." } }, "required": [ "success", "data", "limit", "skip", "total" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "chats.list" } }, "/v1/chats/{id}": { "get": { "tags": [ "Chats" ], "summary": "Get chat", "description": "Retrieve a single chat by its id — a phone number in international format (e.g. +14155551234) or a WhatsApp JID (`@c.us`, `@g.us`, or `@newsletter`). Requires `chats:read`.", "security": [ { "BearerAuth": [ "chats:read" ] } ], "responses": { "200": { "description": "chat", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "chatId": { "type": "string", "description": "WhatsApp JID of the chat — `@c.us` for a 1:1 contact, `@g.us` for a group, `@newsletter` for a channel." }, "name": { "type": "string", "description": "Display name of the chat (contact name, group subject, or channel title). Null when WhatsApp has no name for it." }, "chatType": { "type": "string", "enum": [ "contact", "group", "newsletter" ], "description": "Kind of chat: `contact` (1:1), `group`, or `newsletter` (WhatsApp Channel). The three are mutually exclusive." }, "pinned": { "type": "boolean", "description": "True when the chat is pinned to the top of the chat list." }, "archived": { "type": "boolean", "description": "True when the chat is archived. Excluded from list responses unless `includeArchive=true`." }, "lastMessageAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp of the most recent message in this chat. Null when the chat has no messages." }, "unreadCount": { "type": "integer", "minimum": 0, "description": "Count of unseen incoming messages (>= 0). Excludes the \"manually marked unread\" sentinel — see `markedUnread`." }, "markedUnread": { "type": "boolean", "description": "True when the chat was manually flagged unread in WhatsApp (the dot badge), distinct from having N unread messages." }, "lastMessageText": { "type": "string", "description": "Preview text of the most recent message. Present only when includeLastMessage=true." }, "lastMessageFromMe": { "type": "boolean", "description": "True if the last message was sent by the connected account. Present only when includeLastMessage=true." } }, "required": [ "chatId", "chatType", "markedUnread" ], "additionalProperties": false, "description": "A WhatsApp chat (conversation) — a 1:1 contact, a group, or a channel — as seen by the connected engine." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "operationId": "chats.get" } }, "/v1/groups": { "get": { "tags": [ "Groups" ], "summary": "List groups", "description": "List the groups the connected WhatsApp engine sees. Supports offset pagination (`limit`+`skip`) and an optional case-insensitive substring search on the group name via `searchToken`.", "security": [ { "BearerAuth": [ "groups:read" ] } ], "parameters": [ { "name": "searchToken", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Search token; when set, only items whose name matches are returned." }, { "name": "includeArchive", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Include archived groups (default false → archived excluded)." }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of items to skip before the page (default 0)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Page size (1-200, default 50)." } ], "responses": { "200": { "description": "groups", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "owner": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "lastMessageAt": { "type": "string", "format": "date-time" }, "participantCount": { "type": "integer", "minimum": 0 }, "restrict": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false } }, "limit": { "type": "integer", "description": "Page size echoed back from the request." }, "skip": { "type": "integer", "description": "Offset echoed back from the request." }, "total": { "type": "integer", "description": "Total number of items matching the query, across all pages." } }, "required": [ "success", "data", "limit", "skip", "total" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "groups.list" }, "post": { "tags": [ "Groups" ], "summary": "Create group", "description": "Create a WhatsApp group with the given name and initial participants. Requires `groups:write`.", "security": [ { "BearerAuth": [ "groups:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "participants": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 256 } }, "required": [ "name", "participants" ], "additionalProperties": false }, "examples": { "basic": { "summary": "Two-member group", "value": { "name": "Q4 Planning", "participants": [ "+15555550100", "+15555550101" ] } } } } } }, "responses": { "200": { "description": "created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "owner": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "lastMessageAt": { "type": "string", "format": "date-time" }, "participantCount": { "type": "integer", "minimum": 0 }, "announce": { "type": "boolean" }, "restrict": { "type": "boolean" }, "participants": { "type": "array", "items": { "type": "object", "properties": { "chatId": { "type": "string" }, "isAdmin": { "type": "boolean" }, "isSuperAdmin": { "type": "boolean" }, "name": { "type": "string" } }, "required": [ "chatId", "isAdmin", "isSuperAdmin" ], "additionalProperties": false } } }, "required": [ "id" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "groups.create" } }, "/v1/groups/{id}": { "get": { "tags": [ "Groups" ], "summary": "Get group", "description": "Retrieve a single group by its `@g.us` id, including its subject, description, and (with `?include=participants`) its participant list. Requires `groups:read`.", "security": [ { "BearerAuth": [ "groups:read" ] } ], "parameters": [ { "name": "include", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "participants" ] }, "description": "Set to `participants` to inline the group members array on the response. Omit to leave `participants` null." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "group", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "owner": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "lastMessageAt": { "type": "string", "format": "date-time" }, "participantCount": { "type": "integer", "minimum": 0 }, "announce": { "type": "boolean" }, "restrict": { "type": "boolean" }, "participants": { "type": "array", "items": { "type": "object", "properties": { "chatId": { "type": "string" }, "isAdmin": { "type": "boolean" }, "isSuperAdmin": { "type": "boolean" }, "name": { "type": "string" } }, "required": [ "chatId", "isAdmin", "isSuperAdmin" ], "additionalProperties": false } } }, "required": [ "id" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "groups.get" }, "patch": { "tags": [ "Groups" ], "summary": "Update group", "description": "Update group metadata. Provide at least one of `name` or `settings`. Requires `groups:write`.", "security": [ { "BearerAuth": [ "groups:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "settings": { "type": "object", "properties": { "announce": { "type": "boolean" }, "restrict": { "type": "boolean" }, "editInfoAdminsOnly": { "type": "boolean" }, "description": { "type": "string", "minLength": 1, "maxLength": 2048 } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "owner": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "lastMessageAt": { "type": "string", "format": "date-time" }, "participantCount": { "type": "integer", "minimum": 0 }, "announce": { "type": "boolean" }, "restrict": { "type": "boolean" }, "participants": { "type": "array", "items": { "type": "object", "properties": { "chatId": { "type": "string" }, "isAdmin": { "type": "boolean" }, "isSuperAdmin": { "type": "boolean" }, "name": { "type": "string" } }, "required": [ "chatId", "isAdmin", "isSuperAdmin" ], "additionalProperties": false } } }, "required": [ "id" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "groups.update" } }, "/v1/newsletters": { "get": { "tags": [ "Newsletters" ], "summary": "List newsletters", "description": "List newsletters visible to the connected WhatsApp engine. Offset-paginated via `limit` + `skip`. Requires `newsletters:read` scope.", "security": [ { "BearerAuth": [ "newsletters:read" ] } ], "parameters": [ { "name": "searchToken", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Search token; when set, only newsletters whose name matches (case-insensitive substring) are returned, and `total` reflects the matched count." }, { "name": "includeArchive", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Include archived newsletters (default false → archived excluded)." }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of items to skip before the page (default 0)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Page size (1-200, default 50)." } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "array", "items": { "type": "object", "properties": { "chatId": { "type": "string", "description": "Newsletter JID, e.g. 120363201733549020@newsletter." }, "name": { "type": "string", "description": "Display name of the newsletter / WhatsApp channel." }, "description": { "type": "string", "description": "Optional description." }, "createdAt": { "type": "string", "format": "date-time" }, "subscribers": { "type": "integer", "minimum": 0 }, "invite": { "type": "string", "description": "Invite code (suffix of https://whatsapp.com/channel/)." }, "verification": { "type": "string", "enum": [ "VERIFIED", "UNVERIFIED" ] } }, "required": [ "chatId", "name" ], "additionalProperties": false } }, "limit": { "type": "integer", "description": "Page size echoed back from the request." }, "skip": { "type": "integer", "description": "Offset echoed back from the request." }, "total": { "type": "integer", "description": "Total number of items matching the query, across all pages." } }, "required": [ "success", "data", "limit", "skip", "total" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "newsletters.list" }, "post": { "tags": [ "Newsletters" ], "summary": "Create newsletter", "description": "Create a new WhatsApp newsletter (channel). Requires `messages:write` scope (newsletter creation shares the messages write budget).", "security": [ { "BearerAuth": [ "messages:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 2048 } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "newsletterId": { "type": "string", "description": "Newsletter JID, e.g. 120363201733549020@newsletter." }, "name": { "type": "string", "description": "Display name of the newsletter / WhatsApp channel." }, "description": { "type": "string", "description": "Optional description." }, "createdAt": { "type": "string", "format": "date-time" }, "subscribers": { "type": "integer", "minimum": 0 }, "invite": { "type": "string", "description": "Invite code (suffix of https://whatsapp.com/channel/)." }, "verification": { "type": "string", "enum": [ "VERIFIED", "UNVERIFIED" ] } }, "required": [ "newsletterId", "name" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "newsletters.create" } }, "/v1/newsletters/{id}": { "get": { "tags": [ "Newsletters" ], "summary": "Get newsletter", "description": "Retrieve a newsletter by its JID. Requires `newsletters:read` scope.", "security": [ { "BearerAuth": [ "newsletters:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d+@newsletter$" }, "description": "Newsletter JID, e.g. 12345@newsletter." } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "newsletterId": { "type": "string", "description": "Newsletter JID, e.g. 120363201733549020@newsletter." }, "name": { "type": "string", "description": "Display name of the newsletter / WhatsApp channel." }, "description": { "type": "string", "description": "Optional description." }, "createdAt": { "type": "string", "format": "date-time" }, "subscribers": { "type": "integer", "minimum": 0 }, "invite": { "type": "string", "description": "Invite code (suffix of https://whatsapp.com/channel/)." }, "verification": { "type": "string", "enum": [ "VERIFIED", "UNVERIFIED" ] } }, "required": [ "newsletterId", "name" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "newsletters.get" } }, "/v1/contacts": { "get": { "tags": [ "Contacts" ], "summary": "List contacts", "description": "List your workspace contact book — everyone the connected WhatsApp account has messaged. Offset-paginated via `limit` + `skip`. Requires `contacts:read`.", "security": [ { "BearerAuth": [ "contacts:read" ] } ], "parameters": [ { "name": "searchToken", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Search token; when set, only items whose name matches are returned." }, { "name": "includeArchive", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Include archived chats (default false → archived excluded)." }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Number of contacts to skip before the page (default 0)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Page size (default 10, max 200). Pass `-1` to return every contact in a single page." } ], "responses": { "200": { "description": "contacts", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "array", "items": { "type": "object", "properties": { "chatId": { "type": "string", "description": "WhatsApp JID of the contact (`@c.us`)." }, "name": { "type": "string", "description": "Saved/pushname of the contact. Null or absent when WhatsApp has no name for it." }, "isBusiness": { "type": "boolean", "description": "True when the contact is a WhatsApp Business account. Absent when unknown." } }, "required": [ "chatId" ], "additionalProperties": false, "description": "A WhatsApp contact from the connected account's address book." } }, "limit": { "type": "integer", "description": "Page size echoed back from the request." }, "skip": { "type": "integer", "description": "Offset echoed back from the request." }, "total": { "type": "integer", "description": "Total number of items matching the query, across all pages." } }, "required": [ "success", "data", "limit", "skip", "total" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "contacts.list" } }, "/v1/engines": { "get": { "tags": [ "Engines" ], "summary": "List engines", "description": "List the WhatsApp engines connected to this workspace — one entry per online engine (a workspace with two paired WhatsApp Web tabs returns two entries). Each entry carries its own `id` (the engine session's MQTT presence client id, same id space as ping's `whatsapp_connections[].id`), its `type` (`gateway` or `regular`), and its connectivity status. When no engine is connected, `data` is an empty array — this is not an error.", "security": [ { "BearerAuth": [ "engines:read" ] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable id of this engine session (its MQTT presence client id). Same id space as ping's whatsapp_connections[].id." }, "type": { "type": "string", "enum": [ "gateway", "regular" ], "description": "Engine kind. \"gateway\" = a remote, server-side engine (Blueticks 24/7 gateway / baileys pod). \"regular\" = the user's own WhatsApp Web browser extension." }, "connected": { "type": "boolean", "description": "Whether this engine is currently online and serving requests." }, "state": { "type": "string", "description": "Engine-side connection state (e.g. CONNECTED, OPENING, PAIRING). Null when unknown." }, "stream": { "type": "string", "description": "Underlying WA stream state. Null when unknown." }, "hasSynced": { "type": "boolean", "description": "Whether the engine has completed its initial history sync." } }, "required": [ "id", "type", "connected" ], "additionalProperties": false }, "description": "Engines connected to this workspace. Empty when no engine is paired." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "engines.list" } }, "/v1/suno/songs/{id}": { "get": { "tags": [ "Suno" ], "summary": "Get song", "description": "Poll a single generated clip by id. When `status` is `complete`, `audioUrl` (MP3) and `imageUrl` are populated. Requires `suno:read`.", "security": [ { "BearerAuth": [ "suno:read" ] } ], "responses": { "200": { "description": "song", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Clip id — poll GET /v1/suno/songs/{id} for progress." }, "status": { "type": "string", "enum": [ "submitted", "queued", "running", "streaming", "complete", "error" ], "description": "Generation status. Terminal states: \"complete\" or \"error\"." }, "audioUrl": { "type": "string", "description": "MP3 URL once complete, else null." }, "imageUrl": { "type": "string", "description": "Cover-art URL once available, else null." }, "title": { "type": "string", "description": "Resolved song title, if any." }, "durationSec": { "type": "number", "description": "Audio duration in seconds once complete, else null." }, "model": { "type": "string", "description": "Model version that produced the clip (e.g. \"v5.5\")." }, "errorType": { "type": "string", "description": "Failure class when status is \"error\" (e.g. \"moderation_failure\"). Omitted otherwise." }, "errorMessage": { "type": "string", "description": "Human-readable reason a clip failed (e.g. \"Your lyrics contain copyrighted material\"). Only set when status is \"error\"." } }, "required": [ "id", "status" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "operationId": "suno.songs.get" } }, "/v1/suno/songs": { "post": { "tags": [ "Suno" ], "summary": "Generate song", "description": "Submit a song generation to Suno from `lyrics` + `style`, optionally steering `vocalGender`, `weirdness`, `styleInfluence`, and a reference recording (`uploadId` from POST /v1/suno/uploads, with `audioInfluence` controlling how closely the cover follows it). Returns two clip variants — poll each with `GET /v1/suno/songs/{id}` until `status` is `complete`. Requires `suno:write`.", "security": [ { "BearerAuth": [ "suno:write" ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "lyrics": { "type": "string", "minLength": 1, "maxLength": 5000, "description": "The song lyrics. Maps to Suno `prompt`. Ignored when `instrumental` is true." }, "style": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Style / genre text, e.g. \"pop ballad, acoustic guitar\". Maps to Suno `tags`." }, "negativeStyle": { "type": "string", "maxLength": 1000, "description": "Styles to steer away from. Maps to Suno `negative_tags`." }, "vocalGender": { "type": "string", "enum": [ "m", "f" ], "description": "Preferred vocal gender: \"m\" (male) or \"f\" (female). Omit to let Suno decide." }, "weirdness": { "type": "number", "minimum": 0, "maximum": 1, "description": "Creative deviation 0–1 (Suno \"Weirdness\"). Maps to `control_sliders.weirdness_constraint`." }, "styleInfluence": { "type": "number", "minimum": 0, "maximum": 1, "description": "How strongly the style is applied, 0–1 (Suno \"Style Influence\"). Maps to `control_sliders.style_weight`." }, "audioInfluence": { "type": "number", "minimum": 0, "maximum": 1, "description": "How closely a cover follows the reference recording, 0–1 (Suno \"Audio Influence\"). Only meaningful when `uploadId` is set. Maps to `control_sliders.audio_weight`." }, "instrumental": { "type": "boolean", "description": "Generate without vocals. Maps to Suno `make_instrumental`." }, "model": { "type": "string", "description": "Model version, e.g. \"v5.5\" or \"v4\". Defaults to v5.5. Mapped to Suno `mv`." }, "title": { "type": "string", "maxLength": 200, "description": "Optional song title." }, "uploadId": { "type": "string", "description": "Reference-audio id from POST /v1/suno/uploads, to cover/transform your own recording." }, "captchaToken": { "type": "string", "description": "Cloudflare Turnstile token for cover generations (when `uploadId` is set) — Suno gates upload/voice-clone generations behind a captcha. Not needed for plain text→song. Optional here: if omitted and the server has a solver configured (SUNO_CAPTCHA_PROVIDER + key), the token is minted automatically. Supply your own (minted by a real browser) to skip the solver." } }, "required": [ "lyrics", "style" ], "additionalProperties": false }, "examples": { "basic": { "summary": "Lyrics + style, female vocal", "value": { "lyrics": "[Verse]\nSunlight on the open road\n[Chorus]\nWe are the morning", "style": "upbeat pop, acoustic guitar", "vocalGender": "f", "weirdness": 0.4, "styleInfluence": 0.7 } }, "cover": { "summary": "Cover a user recording", "value": { "lyrics": "[Verse]\nMy own words here", "style": "lo-fi hip hop", "uploadId": "00000000-0000-0000-0000-000000000000", "audioInfluence": 0.8 } } } } } }, "responses": { "200": { "description": "generation submitted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "jobId": { "type": "string", "description": "Batch id for this generation request." }, "clips": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Clip id — poll GET /v1/suno/songs/{id} for progress." }, "status": { "type": "string", "enum": [ "submitted", "queued", "running", "streaming", "complete", "error" ], "description": "Generation status. Terminal states: \"complete\" or \"error\"." }, "audioUrl": { "type": "string", "description": "MP3 URL once complete, else null." }, "imageUrl": { "type": "string", "description": "Cover-art URL once available, else null." }, "title": { "type": "string", "description": "Resolved song title, if any." }, "durationSec": { "type": "number", "description": "Audio duration in seconds once complete, else null." }, "model": { "type": "string", "description": "Model version that produced the clip (e.g. \"v5.5\")." }, "errorType": { "type": "string", "description": "Failure class when status is \"error\" (e.g. \"moderation_failure\"). Omitted otherwise." }, "errorMessage": { "type": "string", "description": "Human-readable reason a clip failed (e.g. \"Your lyrics contain copyrighted material\"). Only set when status is \"error\"." } }, "required": [ "id", "status" ], "additionalProperties": false }, "description": "The generated song variants (typically two). Poll each by id." } }, "required": [ "jobId", "clips" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "suno.songs" } }, "/v1/suno/uploads": { "post": { "tags": [ "Suno" ], "summary": "Upload reference audio", "description": "Upload an audio recording (via `audioUrl` or base64 `audioBase64`) to Suno. Returns an `uploadId` to pass to POST /v1/suno/songs as `uploadId` to cover/transform it. Max 500 MB. Requires `suno:write`.", "security": [ { "BearerAuth": [ "suno:write" ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "audioUrl": { "type": "string", "format": "uri", "description": "Public URL of the reference audio to fetch and upload. Provide this OR `audioBase64` (or send multipart file)." }, "audioBase64": { "type": "string", "description": "Base64-encoded audio bytes. Provide this OR `audioUrl` (or send multipart file)." }, "fileName": { "type": "string", "maxLength": 200, "description": "Original file name, used for the extension (defaults to \"audio.mp3\")." } }, "additionalProperties": false }, "examples": { "fromUrl": { "summary": "From a URL", "value": { "audioUrl": "https://example.com/me-singing.mp3", "fileName": "me-singing.mp3" } } } } } }, "responses": { "200": { "description": "upload ready", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "uploadId": { "type": "string", "description": "Pass as `uploadId` to POST /v1/suno/songs to cover/transform this audio." }, "status": { "type": "string", "description": "Upload processing status (e.g. \"complete\")." } }, "required": [ "uploadId", "status" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "suno.uploads" } }, "/v1/suno/account": { "get": { "tags": [ "Suno" ], "summary": "Get Suno account", "description": "Remaining credits, monthly usage, and plan on the connected Suno account. Requires `suno:read`.", "security": [ { "BearerAuth": [ "suno:read" ] } ], "responses": { "200": { "description": "suno account", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "creditsLeft": { "type": "number", "description": "Remaining generation credits on the connected Suno account." }, "monthlyLimit": { "type": "number", "description": "Monthly credit allowance, if known." }, "monthlyUsage": { "type": "number", "description": "Credits used this month, if known." }, "plan": { "type": "string", "description": "Suno plan name (e.g. \"Pro Plan\")." } }, "required": [ "creditsLeft" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "suno.account" } }, "/v1/audiences/{id}/contacts": { "post": { "tags": [ "Audiences" ], "summary": "Append contacts to audience", "description": "Append contacts to an audience. Duplicates (by `to`) are skipped. Requires `audiences:write`.", "security": [ { "BearerAuth": [ "audiences:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contacts": { "type": "array", "items": { "type": "object", "properties": { "to": { "type": "string", "description": "Recipient. A phone number (+E164), or a WhatsApp JID — individual (…@c.us), group (…@g.us), or newsletter (…@newsletter). Individual recipients are stored in international format; group/newsletter ids are stored verbatim." }, "variables": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 1024 }, "description": "Per-contact substitution values used by campaign templates.\nEach key becomes a token usable as `{key}` in a campaign `text`. Lookup is case-insensitive (e.g. `{firstName}` resolves `firstname`).\nBuilt-in tokens always available regardless of variables: `{whatsappname}`, `{displayname}`, `{phone}`, `{mobile}`. Setting a variable with the same name overrides the built-in.\nStorage: keys are persisted as text-cell column titles on the audience board, so values flow back via audiences.get under the same names.\nLimits: at most 32 keys per contact; values up to 1024 chars; keys must match /^[A-Za-z_][A-Za-z0-9_]{0,31}$/." } }, "required": [ "to" ], "additionalProperties": false }, "minItems": 1, "maxItems": 1000 } }, "required": [ "contacts" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "appended", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "added": { "type": "integer", "minimum": 0 }, "contactCount": { "type": "integer", "minimum": 0 } }, "required": [ "added", "contactCount" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "audiences.contacts.create" } }, "/v1/audiences/{id}/contacts/{contactId}": { "patch": { "tags": [ "Audiences" ], "summary": "Update audience contact", "description": "Edit a contact's phone or variables. Requires `audiences:write`.", "security": [ { "BearerAuth": [ "audiences:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "type": "string" }, "variables": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 1024 }, "description": "Per-contact substitution values used by campaign templates.\nEach key becomes a token usable as `{key}` in a campaign `text`. Lookup is case-insensitive (e.g. `{firstName}` resolves `firstname`).\nBuilt-in tokens always available regardless of variables: `{whatsappname}`, `{displayname}`, `{phone}`, `{mobile}`. Setting a variable with the same name overrides the built-in.\nStorage: keys are persisted as text-cell column titles on the audience board, so values flow back via audiences.get under the same names.\nLimits: at most 32 keys per contact; values up to 1024 chars; keys must match /^[A-Za-z_][A-Za-z0-9_]{0,31}$/." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "to": { "type": "string" }, "variables": { "type": "object", "additionalProperties": { "type": "string" } }, "addedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "to", "variables", "addedAt" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "audiences.contacts.update" }, "delete": { "tags": [ "Audiences" ], "summary": "Remove audience contact", "description": "Remove a contact from an audience. Requires `audiences:write`.", "security": [ { "BearerAuth": [ "audiences:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "audiences.contacts.delete" } }, "/v1/campaigns/{id}/pause": { "post": { "tags": [ "Campaigns" ], "summary": "Pause campaign", "description": "Pause a running campaign. 409 if not `running`. Requires `campaigns:write`.", "security": [ { "BearerAuth": [ "campaigns:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "paused", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "cmpId": { "type": "string" }, "name": { "type": "string" }, "audienceId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "running", "paused", "complete_sent", "complete_delivered", "aborted" ] }, "totalCount": { "type": "integer", "minimum": 0 }, "sentCount": { "type": "integer", "minimum": 0 }, "deliveredCount": { "type": "integer", "minimum": 0 }, "readCount": { "type": "integer", "minimum": 0 }, "failedCount": { "type": "integer", "minimum": 0 }, "createdAt": { "type": "string", "format": "date-time" }, "startedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time" }, "abortedAt": { "type": "string", "format": "date-time" } }, "required": [ "cmpId", "name", "audienceId", "status", "totalCount", "sentCount", "deliveredCount", "readCount", "failedCount", "createdAt" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "campaigns.pause.create" } }, "/v1/campaigns/{id}/resume": { "post": { "tags": [ "Campaigns" ], "summary": "Resume campaign", "description": "Resume a paused campaign. 409 if not `paused`. Requires `campaigns:write`.", "security": [ { "BearerAuth": [ "campaigns:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "resumed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "cmpId": { "type": "string" }, "name": { "type": "string" }, "audienceId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "running", "paused", "complete_sent", "complete_delivered", "aborted" ] }, "totalCount": { "type": "integer", "minimum": 0 }, "sentCount": { "type": "integer", "minimum": 0 }, "deliveredCount": { "type": "integer", "minimum": 0 }, "readCount": { "type": "integer", "minimum": 0 }, "failedCount": { "type": "integer", "minimum": 0 }, "createdAt": { "type": "string", "format": "date-time" }, "startedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time" }, "abortedAt": { "type": "string", "format": "date-time" } }, "required": [ "cmpId", "name", "audienceId", "status", "totalCount", "sentCount", "deliveredCount", "readCount", "failedCount", "createdAt" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "campaigns.resume.create" } }, "/v1/campaigns/{id}/cancel": { "post": { "tags": [ "Campaigns" ], "summary": "Cancel campaign", "description": "Cancel a campaign. 409 if already terminal. Requires `campaigns:write`.", "security": [ { "BearerAuth": [ "campaigns:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "aborted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "cmpId": { "type": "string" }, "name": { "type": "string" }, "audienceId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "running", "paused", "complete_sent", "complete_delivered", "aborted" ] }, "totalCount": { "type": "integer", "minimum": 0 }, "sentCount": { "type": "integer", "minimum": 0 }, "deliveredCount": { "type": "integer", "minimum": 0 }, "readCount": { "type": "integer", "minimum": 0 }, "failedCount": { "type": "integer", "minimum": 0 }, "createdAt": { "type": "string", "format": "date-time" }, "startedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time" }, "abortedAt": { "type": "string", "format": "date-time" } }, "required": [ "cmpId", "name", "audienceId", "status", "totalCount", "sentCount", "deliveredCount", "readCount", "failedCount", "createdAt" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "campaigns.cancel.create" } }, "/v1/messages": { "get": { "tags": [ "Messages" ], "summary": "List messages (all chats)", "description": "Offset-paginated list of messages across the whole account. Pass `chatId` to scope to a single chat, or omit it to search across all chats. Supports free-text search (`searchToken`), date range (`since`/`until`), and message-kind filtering (`messageTypes`). Requires `chats:read`.", "security": [ { "BearerAuth": [ "chats:read" ] } ], "parameters": [ { "name": "chatId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d+(?:-\\d+)?@(?:c\\.us|s\\.whatsapp\\.net|g\\.us|lid|broadcast|newsletter)$" }, "description": "Optional WhatsApp JID to scope results to a single chat. Omit to search across all chats." }, { "name": "searchToken", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Search token; when set, only items whose name matches are returned." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "description": "Result ordering. asc = oldest-first; desc = newest-first (default)." }, { "name": "since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Lower bound (ISO 8601, offset allowed). Only messages with timestamp >= since." }, { "name": "until", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Upper bound (ISO 8601, offset allowed). Only messages with timestamp <= until." }, { "name": "messageTypes", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "chat", "image", "video", "document", "audio", "ptt", "sticker", "gif", "ptv", "poll_creation", "location", "vcard", "revoked" ] } }, "description": "Filter to specific message kinds. Comma-separated or repeated. Useful for \"all PDFs\" (`document`) or \"images today\" (`image`). System events (gp2/revoked/newsletter_notification) are excluded by default unless explicitly listed here.", "style": "form", "explode": false }, { "name": "queryAny", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "maxItems": 24 }, "description": "Keyword-set OR search: match if body/caption/filename contains ANY term." }, { "name": "mime", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "MIME prefix filter, e.g. \"application/pdf\" or \"image/\"." }, { "name": "filenameContains", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Case-insensitive substring match on the document filename." }, { "name": "hasMedia", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "true = only messages with a media attachment; false = only non-media." }, { "name": "sender", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Case-insensitive substring match on the sender JID/phone." }, { "name": "loadFromPhoneIfNeeded", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "When the local store is exhausted, fetch older messages from the phone (chrome only)." }, { "name": "includeMediaContent", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Include inline media payload on rows (heavy; default false — use /messages/{key}/media)." }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of messages to skip before the page (default 0)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Max messages to return." } ], "responses": { "200": { "description": "messages", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "array", "items": { "type": "object", "properties": { "waMessageKey": { "type": "object", "properties": { "fromMe": { "type": "boolean" }, "remote": { "type": "string" }, "id": { "type": "string" }, "_serialized": { "type": "string" }, "participant": { "type": "string" } }, "required": [ "fromMe" ], "additionalProperties": false }, "chatId": { "type": "string" }, "from": { "type": "string" }, "author": { "type": "string" }, "senderName": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "text": { "type": "string" }, "type": { "type": "string" }, "fromMe": { "type": "boolean" }, "ack": { "type": "integer" }, "mediaUrl": { "type": "string" }, "filename": { "type": "string" }, "linkPreview": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "canonicalUrl": { "type": "string" }, "thumbnail": { "type": "string" } }, "additionalProperties": false }, "quotedMessage": { "type": "object", "properties": { "waMessageKey": { "type": "object", "properties": { "fromMe": { "type": "boolean" }, "remote": { "type": "string" }, "id": { "type": "string" }, "_serialized": { "type": "string" }, "participant": { "type": "string" } }, "required": [ "fromMe" ], "additionalProperties": false }, "text": { "type": "string" }, "type": { "type": "string" }, "author": { "type": "string" } }, "required": [ "waMessageKey" ], "additionalProperties": false } }, "required": [ "waMessageKey", "chatId", "from", "type", "fromMe" ], "additionalProperties": false } }, "limit": { "type": "integer", "description": "Page size echoed back from the request." }, "skip": { "type": "integer", "description": "Offset echoed back from the request." }, "total": { "type": "integer", "description": "Total number of items matching the query, across all pages." }, "hasMore": { "type": "boolean", "description": "True when more messages exist in the store beyond this page." }, "coverage": { "type": "object", "properties": { "oldestLoadedTimestamp": { "type": "number", "description": "Epoch MILLISECONDS of the oldest currently-loaded message for this chat. Omitted when unknown (empty chat / probe unavailable)." }, "oldestLoadedIso": { "type": "string", "description": "ISO 8601 form of `oldestLoadedTimestamp`. Use it to verify range coverage (\"did I reach a year back?\") deterministically." } }, "additionalProperties": false, "description": "How far back this page reaches: oldest message timestamp in the returned page (epoch ms + ISO). Present when the page has at least one dated message." } }, "required": [ "success", "data", "limit", "skip", "total" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "messages.list" } }, "/v1/messages/{chatId}": { "post": { "tags": [ "Messages" ], "summary": "Send message", "description": "Send a message immediately to a specific chat. The body is the same FLAT shape as `POST /v1/scheduled-messages` minus `to` (derived from the URL path) and `sendAt` (this endpoint is fire-and-forget). Set `type` to `text`, `media`, or `poll`. The dispatch is direct — no DB row is created; the response carries the WhatsApp wire key under `key`. For scheduled or queue-managed sends use `POST /v1/scheduled-messages` instead. Requires `messages:write`.\n\n### Sending media (`type: \"media\"`)\n\nProvide the media **one** of these ways:\n\n- **`mediaUrl`** — a public `https://` URL to the file.\n- **`mediaBase64`** — the file bytes base64-encoded (or a `data:` URL), inline in the JSON body.\n- **Upload a file** — send the request as `multipart/form-data` with the file in a **`mediaFile`** part. See the cURL example below.\n\nIf both `mediaUrl` and `mediaBase64` are present, `mediaUrl` wins. Optional: `mediaFilename` (display name) and `mediaKind` (`image` · `video` · `audio` · `document` · `sticker` · `voice` · `gif`; auto-detected otherwise).\n\n> In the Body panel, the **Attach a file** control has a content-type dropdown next to it. Pick `application/json` to inline a small file as base64 in `mediaBase64`, or `multipart/form-data` to upload the raw file (no 10 MB JSON-body limit) — then just press **Send**. The cURL below is the multipart equivalent.\n\n```bash\ncurl -X POST \"https://api.blueticks.co/v1/messages/120363000000000000@g.us\" \\\n -H \"Authorization: Bearer $BLUETICKS_API_KEY\" \\\n -F \"type=media\" \\\n -F \"text=Here is the file\" \\\n -F \"mediaFile=@/path/to/photo.png\"\n```\n\n### Mentioning contacts\n\nMentions are written **inline in `text`** — there is no separate field. Use `@[Display Name]()`:\n\n```\nHi @[Jon Daw](xxxxxxxxxxxx@c.us) this is a test\n```", "security": [ { "BearerAuth": [ "messages:write" ] } ], "parameters": [ { "name": "chatId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text", "media", "poll" ] }, "replyTo": { "type": "string", "maxLength": 256, "description": "Wire `key` of a prior message to quote-reply (from MessageResponse.key). Empty string = no reply." }, "text": { "type": "string", "maxLength": 4096, "description": "Text body (required for type=text) or optional media caption (type=media). Up to 4096 chars. Mention a contact inline with `@[Display Name]()`, e.g. `Hi @[Jon Daw](xxxxxxxxxxxx@c.us)`." }, "mediaUrl": { "type": "string", "maxLength": 2048, "description": "Media source URL (https only). One of mediaUrl or mediaBase64 is required for media sends; mediaUrl wins when both are present." }, "mediaBase64": { "type": "string", "maxLength": 15728640, "description": "Raw media bytes, base64-encoded (or a data: URL). Used when mediaUrl is absent. For a file upload, send multipart/form-data with a `mediaFile` part instead — it is converted to this." }, "mediaKind": { "type": "string", "enum": [ "image", "video", "audio", "document", "sticker", "voice", "gif" ], "description": "Media kind (image · video · audio · document · sticker · voice · gif). Optional — auto-detected from the URL / content-type when omitted." }, "mediaFilename": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Filename shown on the attachment (type=media). Optional — derived from the URL / uploaded file when omitted." }, "pollQuestion": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Poll question (type=poll). Required for poll sends." }, "pollOptions": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": "Poll options (type=poll). 2–12 items." }, "pollAllowMultiple": { "type": "boolean", "description": "Allow selecting multiple poll options (type=poll). Default false." }, "secret": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Opaque correlation token you choose to tag this message with. It is stored on the message and carried into WhatsApp's `messageSecret`, so you can match it back to your own records later. NOT a deduplication key: sending the same `secret` twice creates two separate messages. To make retries safe (at-most-once send), use the `Idempotency-Key` header instead. When omitted, the API encodes the internal message id here for delivery-status matching — only set this if you have your own correlation scheme." }, "withTyping": { "type": "boolean", "description": "Briefly show the \"typing…\" indicator before sending a text message. Default true. Ignored for media/poll sends." }, "typingSeconds": { "type": "number", "minimum": 0, "maximum": 25, "description": "Extra typing duration in seconds, added on top of the built-in 0.4–0.8s random jitter. Default 0. Capped at 25s (WhatsApp clears the indicator after ~25s)." } }, "required": [ "type" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Primary handle for the message. Scheduled sends: the queue id (accepted by GET/cancel /v1/scheduled-messages/{id}). Direct sends: the serialized WhatsApp message key (== waMessageKey._serialized), accepted by GET /v1/messages/{id}." }, "waMessageKey": { "type": "object", "properties": { "fromMe": { "type": "boolean" }, "remote": { "type": "string" }, "id": { "type": "string" }, "_serialized": { "type": "string" }, "participant": { "type": "string" } }, "required": [ "fromMe" ], "additionalProperties": false }, "to": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "media", "poll" ], "description": "Message kind that was sent." }, "text": { "type": "string" }, "mediaUrl": { "type": "string" }, "mediaKind": { "type": "string", "enum": [ "image", "video", "audio", "document", "sticker", "voice", "gif" ] }, "pollQuestion": { "type": "string" }, "pollOptions": { "type": "array", "items": { "type": "string" }, "description": "Poll option labels in order (type=poll). Null for non-poll messages." }, "pollAllowMultiple": { "type": "boolean", "description": "Whether the poll accepts multiple selections (type=poll). Null for non-poll messages." }, "status": { "type": "string", "enum": [ "pending", "before-wa-send", "bt-sent", "sending", "sent", "sent_pending_ack", "confirmed", "delivered", "received", "read", "played", "cancelled", "error", "failed", "expired" ] }, "sendAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "confirmedAt": { "type": "string", "format": "date-time" }, "receivedAt": { "type": "string", "format": "date-time" }, "readAt": { "type": "string", "format": "date-time" }, "playedAt": { "type": "string", "format": "date-time" }, "failedAt": { "type": "string", "format": "date-time" }, "failureReason": { "type": "string" }, "secret": { "type": "string", "description": "Opaque correlation token carried on the message. Echoes the `secret` you sent (or the engine-encoded internal id when you omitted it), and is carried into WhatsApp's `messageSecret`. Null until a queued/scheduled send dispatches." }, "linkPreview": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "canonicalUrl": { "type": "string" }, "thumbnail": { "type": "string" } }, "additionalProperties": false } }, "required": [ "to", "type", "status", "createdAt" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "messages.create" } }, "/v1/scheduled-messages/{chatId}": { "post": { "tags": [ "Scheduled Messages" ], "summary": "Schedule message", "description": "Send or schedule a WhatsApp message to the chat named in the URL path (`{chatId}` — a phone number in E.164 format, e.g. `+15551234567`, or a WhatsApp chat id like `12345@c.us` / `1234567890@g.us` / `12345@newsletter`). Omit `sendAt` to send immediately; set it (RFC 3339, ≥10s and ≤365d in the future) to defer delivery.\n\nThe body is a FLAT object — set the `type` field to one of `text`, `media`, or `poll`; `type` selects which top-level fields are relevant.\n\n**Variants:**\n\n- `type: \"text\"` — required `text` (1–4096 chars). A rich link-preview card is attached automatically when the text contains a URL. Example:\n ```bash\n curl -X POST \"https://api.blueticks.co/v1/scheduled-messages/+15551234567\" \\\n -H \"Authorization: Bearer $BLUETICKS_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"type\":\"text\",\"text\":\"hello\"}'\n ```\n- `type: \"media\"` — provide the media as `mediaUrl` (HTTPS) **or** `mediaBase64` (base64 / data: URL); `mediaUrl` wins if both are sent. The bytes are uploaded server-side and only a URL is sent on to the engine. Optional `mediaKind` (`image` · `video` · `audio` · `document` · `sticker` · `voice` · `gif`; auto-detected when omitted), `text` (caption), `mediaFilename`. You can also upload a file as `multipart/form-data` with the bytes in a `mediaFile` part.\n- `type: \"poll\"` — required `pollQuestion` and `pollOptions` (2–12 items). Optional `pollAllowMultiple` (default false).\n\nAll variants accept optional `sendAt` (defer) and `replyTo` (wire `key` of a prior message to quote). Pass an `Idempotency-Key` header to make retries safe (at most one send per key). Requires `messages:write`.\n\nSee [Sending messages](/docs/messages) for runnable Python / Node / PHP / cURL examples per variant.", "security": [ { "BearerAuth": [ "messages:write" ] } ], "parameters": [ { "name": "chatId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 64 }, "description": "Optional key for safe retries — guarantees a request runs at most once, so a network timeout + retry never double-sends. Reuse the same key to retry: an identical body replays the original response (HTTP 200 instead of 201, no second message); a different body with the same key returns 409 Conflict. Keys are scoped per workspace (max 64 chars). This is the request-level dedup control — distinct from the body `secret` field, which is only a correlation tag and does NOT prevent duplicate sends." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text", "media", "poll" ] }, "replyTo": { "type": "string", "maxLength": 256, "description": "Wire `key` of a prior message to quote-reply (from MessageResponse.key). Empty string = no reply." }, "text": { "type": "string", "maxLength": 4096, "description": "Text body (required for type=text) or optional media caption (type=media). Up to 4096 chars. Mention a contact inline with `@[Display Name]()`, e.g. `Hi @[Jon Daw](xxxxxxxxxxxx@c.us)`." }, "mediaUrl": { "type": "string", "maxLength": 2048, "description": "Media source URL (https only). One of mediaUrl or mediaBase64 is required for media sends; mediaUrl wins when both are present." }, "mediaBase64": { "type": "string", "maxLength": 15728640, "description": "Raw media bytes, base64-encoded (or a data: URL). Used when mediaUrl is absent. For a file upload, send multipart/form-data with a `mediaFile` part instead — it is converted to this." }, "mediaKind": { "type": "string", "enum": [ "image", "video", "audio", "document", "sticker", "voice", "gif" ], "description": "Media kind (image · video · audio · document · sticker · voice · gif). Optional — auto-detected from the URL / content-type when omitted." }, "mediaFilename": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Filename shown on the attachment (type=media). Optional — derived from the URL / uploaded file when omitted." }, "pollQuestion": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Poll question (type=poll). Required for poll sends." }, "pollOptions": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": "Poll options (type=poll). 2–12 items." }, "pollAllowMultiple": { "type": "boolean", "description": "Allow selecting multiple poll options (type=poll). Default false." }, "secret": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Opaque correlation token you choose to tag this message with. It is stored on the message and carried into WhatsApp's `messageSecret`, so you can match it back to your own records later. NOT a deduplication key: sending the same `secret` twice creates two separate messages. To make retries safe (at-most-once send), use the `Idempotency-Key` header instead. When omitted, the API encodes the internal message id here for delivery-status matching — only set this if you have your own correlation scheme." }, "sendAt": { "type": "string", "format": "date-time" } }, "required": [ "type" ], "additionalProperties": false }, "examples": { "text": { "summary": "Plain text", "value": { "type": "text", "text": "Hello from Blueticks!" } }, "text_with_link": { "summary": "Text with a URL (link preview auto-attached)", "value": { "type": "text", "text": "Check this out: https://blueticks.co" } }, "media_url": { "summary": "Image from URL", "value": { "type": "media", "mediaKind": "image", "mediaUrl": "https://blueticks.co/favicon.ico", "text": "Our logo" } }, "media_document": { "summary": "Document attachment", "value": { "type": "media", "mediaKind": "document", "mediaUrl": "https://example.com/invoice.pdf", "mediaFilename": "invoice.pdf" } }, "poll": { "summary": "Poll", "value": { "type": "poll", "pollQuestion": "Pizza tonight?", "pollOptions": [ "Yes", "No", "Maybe" ] } }, "scheduled_text": { "summary": "Scheduled text (deferred send)", "value": { "type": "text", "text": "Reminder: meeting in 3 hours", "sendAt": "2026-12-31T12:00:00Z" } }, "replyTo": { "summary": "Reply quoting a prior message", "value": { "type": "text", "text": "Sounds good!", "replyTo": "true_15555550100@c.us_3EB0ABCDEF1234567890" } } } } } }, "responses": { "200": { "description": "Idempotency replay", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Primary handle for the message. Scheduled sends: the queue id (accepted by GET/cancel /v1/scheduled-messages/{id}). Direct sends: the serialized WhatsApp message key (== waMessageKey._serialized), accepted by GET /v1/messages/{id}." }, "waMessageKey": { "type": "object", "properties": { "fromMe": { "type": "boolean" }, "remote": { "type": "string" }, "id": { "type": "string" }, "_serialized": { "type": "string" }, "participant": { "type": "string" } }, "required": [ "fromMe" ], "additionalProperties": false }, "to": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "media", "poll" ], "description": "Message kind that was sent." }, "text": { "type": "string" }, "mediaUrl": { "type": "string" }, "mediaKind": { "type": "string", "enum": [ "image", "video", "audio", "document", "sticker", "voice", "gif" ] }, "pollQuestion": { "type": "string" }, "pollOptions": { "type": "array", "items": { "type": "string" }, "description": "Poll option labels in order (type=poll). Null for non-poll messages." }, "pollAllowMultiple": { "type": "boolean", "description": "Whether the poll accepts multiple selections (type=poll). Null for non-poll messages." }, "status": { "type": "string", "enum": [ "pending", "before-wa-send", "bt-sent", "sending", "sent", "sent_pending_ack", "confirmed", "delivered", "received", "read", "played", "cancelled", "error", "failed", "expired" ] }, "sendAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "confirmedAt": { "type": "string", "format": "date-time" }, "receivedAt": { "type": "string", "format": "date-time" }, "readAt": { "type": "string", "format": "date-time" }, "playedAt": { "type": "string", "format": "date-time" }, "failedAt": { "type": "string", "format": "date-time" }, "failureReason": { "type": "string" }, "secret": { "type": "string", "description": "Opaque correlation token carried on the message. Echoes the `secret` you sent (or the engine-encoded internal id when you omitted it), and is carried into WhatsApp's `messageSecret`. Null until a queued/scheduled send dispatches." }, "linkPreview": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "canonicalUrl": { "type": "string" }, "thumbnail": { "type": "string" } }, "additionalProperties": false } }, "required": [ "to", "type", "status", "createdAt" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Primary handle for the message. Scheduled sends: the queue id (accepted by GET/cancel /v1/scheduled-messages/{id}). Direct sends: the serialized WhatsApp message key (== waMessageKey._serialized), accepted by GET /v1/messages/{id}." }, "waMessageKey": { "type": "object", "properties": { "fromMe": { "type": "boolean" }, "remote": { "type": "string" }, "id": { "type": "string" }, "_serialized": { "type": "string" }, "participant": { "type": "string" } }, "required": [ "fromMe" ], "additionalProperties": false }, "to": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "media", "poll" ], "description": "Message kind that was sent." }, "text": { "type": "string" }, "mediaUrl": { "type": "string" }, "mediaKind": { "type": "string", "enum": [ "image", "video", "audio", "document", "sticker", "voice", "gif" ] }, "pollQuestion": { "type": "string" }, "pollOptions": { "type": "array", "items": { "type": "string" }, "description": "Poll option labels in order (type=poll). Null for non-poll messages." }, "pollAllowMultiple": { "type": "boolean", "description": "Whether the poll accepts multiple selections (type=poll). Null for non-poll messages." }, "status": { "type": "string", "enum": [ "pending", "before-wa-send", "bt-sent", "sending", "sent", "sent_pending_ack", "confirmed", "delivered", "received", "read", "played", "cancelled", "error", "failed", "expired" ] }, "sendAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "confirmedAt": { "type": "string", "format": "date-time" }, "receivedAt": { "type": "string", "format": "date-time" }, "readAt": { "type": "string", "format": "date-time" }, "playedAt": { "type": "string", "format": "date-time" }, "failedAt": { "type": "string", "format": "date-time" }, "failureReason": { "type": "string" }, "secret": { "type": "string", "description": "Opaque correlation token carried on the message. Echoes the `secret` you sent (or the engine-encoded internal id when you omitted it), and is carried into WhatsApp's `messageSecret`. Null until a queued/scheduled send dispatches." }, "linkPreview": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "canonicalUrl": { "type": "string" }, "thumbnail": { "type": "string" } }, "additionalProperties": false } }, "required": [ "to", "type", "status", "createdAt" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "scheduled-messages.create" } }, "/v1/messages/{waMessageKey}": { "get": { "tags": [ "Messages" ], "summary": "Get message", "description": "Fetch a single message by its complete WhatsApp message key. Requires `chats:read`.", "security": [ { "BearerAuth": [ "chats:read" ] } ], "parameters": [ { "name": "waMessageKey", "in": "path", "required": true, "description": "The complete WhatsApp message key (`__[_]`), e.g. `false_120363426216988013@g.us_3EB0659D13650092D677AD_188450464616609@lid`.", "schema": { "type": "string" } }, { "name": "chatId", "in": "query", "required": false, "description": "Optional. Only used to find the message faster — when you pass a bare message id instead of the complete key, `chatId` lets the server rebuild the full key. If you pass the complete `waMessageKey` you can omit it.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "message", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "waMessageKey": { "type": "object", "properties": { "fromMe": { "type": "boolean" }, "remote": { "type": "string" }, "id": { "type": "string" }, "_serialized": { "type": "string" }, "participant": { "type": "string" } }, "required": [ "fromMe" ], "additionalProperties": false }, "chatId": { "type": "string" }, "from": { "type": "string" }, "author": { "type": "string" }, "senderName": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "text": { "type": "string" }, "type": { "type": "string" }, "fromMe": { "type": "boolean" }, "ack": { "type": "integer" }, "mediaUrl": { "type": "string" }, "filename": { "type": "string" }, "linkPreview": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "canonicalUrl": { "type": "string" }, "thumbnail": { "type": "string" } }, "additionalProperties": false }, "quotedMessage": { "type": "object", "properties": { "waMessageKey": { "type": "object", "properties": { "fromMe": { "type": "boolean" }, "remote": { "type": "string" }, "id": { "type": "string" }, "_serialized": { "type": "string" }, "participant": { "type": "string" } }, "required": [ "fromMe" ], "additionalProperties": false }, "text": { "type": "string" }, "type": { "type": "string" }, "author": { "type": "string" } }, "required": [ "waMessageKey" ], "additionalProperties": false } }, "required": [ "waMessageKey", "chatId", "from", "type", "fromMe" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "messages.get" } }, "/v1/groups/{id}/members": { "post": { "tags": [ "Groups" ], "summary": "Add member to group", "description": "Add a participant to the group by chatId (JID) or phone number in international format (e.g. +14155551234). Requires `groups:write`.", "security": [ { "BearerAuth": [ "groups:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chatId": { "type": "string" }, "participants": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 256 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "updated group", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "owner": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "lastMessageAt": { "type": "string", "format": "date-time" }, "participantCount": { "type": "integer", "minimum": 0 }, "announce": { "type": "boolean" }, "restrict": { "type": "boolean" }, "participants": { "type": "array", "items": { "type": "object", "properties": { "chatId": { "type": "string" }, "isAdmin": { "type": "boolean" }, "isSuperAdmin": { "type": "boolean" }, "name": { "type": "string" } }, "required": [ "chatId", "isAdmin", "isSuperAdmin" ], "additionalProperties": false } } }, "required": [ "id" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "groups.members.create" } }, "/v1/groups/{id}/members/me": { "delete": { "tags": [ "Groups" ], "summary": "Leave group", "description": "Leave the group as the authenticated identity. Idempotent — succeeds with 204 even if already not a member. Requires `groups:write`.", "security": [ { "BearerAuth": [ "groups:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "left" }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "groups.members.me.delete" } }, "/v1/groups/{id}/members/{chatId}": { "delete": { "tags": [ "Groups" ], "summary": "Remove member from group", "description": "Remove a participant from the group. Requires `groups:write`.", "security": [ { "BearerAuth": [ "groups:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "chatId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "updated group", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "owner": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "lastMessageAt": { "type": "string", "format": "date-time" }, "participantCount": { "type": "integer", "minimum": 0 }, "announce": { "type": "boolean" }, "restrict": { "type": "boolean" }, "participants": { "type": "array", "items": { "type": "object", "properties": { "chatId": { "type": "string" }, "isAdmin": { "type": "boolean" }, "isSuperAdmin": { "type": "boolean" }, "name": { "type": "string" } }, "required": [ "chatId", "isAdmin", "isSuperAdmin" ], "additionalProperties": false } } }, "required": [ "id" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "groups.members.delete" } }, "/v1/groups/{id}/members/{chatId}/admin": { "post": { "tags": [ "Groups" ], "summary": "Promote member to admin", "description": "Grant admin privileges to a group member. Requires `groups:write`.", "security": [ { "BearerAuth": [ "groups:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "chatId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "updated group", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "owner": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "lastMessageAt": { "type": "string", "format": "date-time" }, "participantCount": { "type": "integer", "minimum": 0 }, "announce": { "type": "boolean" }, "restrict": { "type": "boolean" }, "participants": { "type": "array", "items": { "type": "object", "properties": { "chatId": { "type": "string" }, "isAdmin": { "type": "boolean" }, "isSuperAdmin": { "type": "boolean" }, "name": { "type": "string" } }, "required": [ "chatId", "isAdmin", "isSuperAdmin" ], "additionalProperties": false } } }, "required": [ "id" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "groups.members.admin.create" }, "delete": { "tags": [ "Groups" ], "summary": "Demote admin to member", "description": "Revoke admin privileges from a group member. Requires `groups:write`.", "security": [ { "BearerAuth": [ "groups:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "chatId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "updated group", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "owner": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "lastMessageAt": { "type": "string", "format": "date-time" }, "participantCount": { "type": "integer", "minimum": 0 }, "announce": { "type": "boolean" }, "restrict": { "type": "boolean" }, "participants": { "type": "array", "items": { "type": "object", "properties": { "chatId": { "type": "string" }, "isAdmin": { "type": "boolean" }, "isSuperAdmin": { "type": "boolean" }, "name": { "type": "string" } }, "required": [ "chatId", "isAdmin", "isSuperAdmin" ], "additionalProperties": false } } }, "required": [ "id" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "groups.members.admin.delete" } }, "/v1/groups/{id}/picture": { "put": { "tags": [ "Groups" ], "summary": "Set group picture", "description": "Replace the group picture. Provide the image as `fileDataUrl` (base64 data URL, PNG/JPEG, ≤20 MiB) or `url` (https). You can also upload a file as `multipart/form-data` with a `file` part. Requires `groups:write`.\n\n> In the Body panel, the **Attach a file** control has a content-type dropdown: `application/json` inlines the file as base64 in `fileDataUrl`, or `multipart/form-data` uploads the raw file — then press **Send**.", "security": [ { "BearerAuth": [ "groups:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fileDataUrl": { "type": "string", "minLength": 1, "maxLength": 20971520 }, "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "fileName": { "type": "string", "maxLength": 255 }, "fileMimeType": { "type": "string", "maxLength": 127 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "picture updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "owner": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "lastMessageAt": { "type": "string", "format": "date-time" }, "participantCount": { "type": "integer", "minimum": 0 }, "announce": { "type": "boolean" }, "restrict": { "type": "boolean" }, "participants": { "type": "array", "items": { "type": "object", "properties": { "chatId": { "type": "string" }, "isAdmin": { "type": "boolean" }, "isSuperAdmin": { "type": "boolean" }, "name": { "type": "string" } }, "required": [ "chatId", "isAdmin", "isSuperAdmin" ], "additionalProperties": false } } }, "required": [ "id" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "groups.picture.update" } }, "/v1/contacts/{id}/common_groups": { "get": { "tags": [ "Contacts" ], "summary": "Get common groups", "description": "List the groups the connected WhatsApp account shares with this contact (WhatsApp’s \"groups in common\"). `id` is the contact’s JID (e.g. `12345@c.us`). Returns the same group list-item shape as `GET /v1/groups`. Requires `groups:read`.", "security": [ { "BearerAuth": [ "groups:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "common groups", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "owner": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "lastMessageAt": { "type": "string", "format": "date-time" }, "participantCount": { "type": "integer", "minimum": 0 }, "restrict": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false } }, "limit": { "type": "integer", "description": "Page size echoed back from the request." }, "skip": { "type": "integer", "description": "Offset echoed back from the request." }, "total": { "type": "integer", "description": "Total number of items matching the query, across all pages." } }, "required": [ "success", "data", "limit", "skip", "total" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "contacts.commongroups.list" } }, "/v1/boards/{boardId}/items": { "get": { "tags": [ "Boards" ], "summary": "List board items", "description": "List a board's items (tasks). Pass `active_only=true` to return only items updated within the retention window whose status is non-terminal (the AI's \"active memory\" view). Filter by `status` label or `updated_since`. Requires `boards:read`.", "security": [ { "BearerAuth": [ "boards:read" ] } ], "parameters": [ { "name": "boardId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by denormalized status label." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Sort direction by timestamp: `asc` (oldest first) or `desc` (newest first, default)." }, { "name": "active_only", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "When true: only items updated within the retention window whose status is non-terminal and not deleted." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string" }, "description": "ISO 8601 / epoch-ms cutoff; only items updated at or after this time." }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of items to skip before the page (default 0)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Page size (default 50, max 200)." } ], "responses": { "200": { "description": "items", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "array", "items": { "type": "object", "properties": { "item_id": { "type": "string" }, "text": { "type": "string" }, "status": { "type": "object", "properties": { "label": { "type": "string" }, "bgcolor": { "type": "string" } }, "required": [ "label", "bgcolor" ], "additionalProperties": false }, "priority": { "type": "object", "properties": { "label": { "type": "string" }, "bgcolor": { "type": "string" } }, "required": [ "label", "bgcolor" ], "additionalProperties": false }, "due_date": { "type": "string" }, "cells": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "description": "Custom cell values keyed by column title (e.g. `Source`, `Company`, `Value`)." }, "source": { "type": "object", "properties": { "chat_id": { "type": "string", "description": "WhatsApp chat id the item was extracted from." }, "chat_name": { "type": "string", "maxLength": 200, "description": "Human-readable chat/contact name the item was extracted from (surfaced on the board Source cell)." }, "message_key": { "type": "string", "description": "WhatsApp message key the item was extracted from." }, "excerpt": { "type": "string", "maxLength": 2000, "description": "Short verbatim source excerpt." }, "extracted_at": { "type": "integer", "description": "Extraction time (epoch ms)." } }, "additionalProperties": false }, "confidence": { "type": "number" }, "last_seen_at": { "type": "integer" }, "web_url": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "item_id", "text", "web_url", "created_at", "updated_at" ], "additionalProperties": false } }, "limit": { "type": "integer", "description": "Page size echoed back from the request." }, "skip": { "type": "integer", "description": "Offset echoed back from the request." }, "total": { "type": "integer", "description": "Total number of items matching the query, across all pages." } }, "required": [ "success", "data", "limit", "skip", "total" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "boards.items.list" }, "post": { "tags": [ "Boards" ], "summary": "Create board item", "description": "Create one item. `status`/`priority` are given as LABELS and resolved to the board's options server-side (unknown label → 422 with the valid labels). Dedupe fingerprint + provenance are stamped into aiMeta. Requires `boards:write`.", "security": [ { "BearerAuth": [ "boards:write" ] } ], "parameters": [ { "name": "boardId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Item title." }, "status": { "type": "string", "maxLength": 120, "description": "Status LABEL (resolved to the board option; unknown label → 422)." }, "priority": { "type": "string", "maxLength": 120, "description": "Priority LABEL (resolved to the board option; unknown label → 422)." }, "due_date": { "type": "string", "maxLength": 64, "description": "Due date (ISO 8601 or date string), stored on the Date column." }, "cells": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "description": "Custom cell values keyed by column title (e.g. `Source`, `Company`, `Value`)." }, "source": { "type": "object", "properties": { "chat_id": { "type": "string", "description": "WhatsApp chat id the item was extracted from." }, "chat_name": { "type": "string", "maxLength": 200, "description": "Human-readable chat/contact name the item was extracted from (surfaced on the board Source cell)." }, "message_key": { "type": "string", "description": "WhatsApp message key the item was extracted from." }, "excerpt": { "type": "string", "maxLength": 2000, "description": "Short verbatim source excerpt." }, "extracted_at": { "type": "integer", "description": "Extraction time (epoch ms)." } }, "additionalProperties": false }, "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Extraction confidence 0..1." }, "allow_duplicate": { "type": "boolean", "description": "By default, creating an item that matches an existing active item (fingerprint or fuzzy title) MERGES into it instead of creating a duplicate (the response then carries `merged: true`). Pass `true` to force creation." } }, "required": [ "text" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "item_id": { "type": "string" }, "text": { "type": "string" }, "status": { "type": "object", "properties": { "label": { "type": "string" }, "bgcolor": { "type": "string" } }, "required": [ "label", "bgcolor" ], "additionalProperties": false }, "priority": { "type": "object", "properties": { "label": { "type": "string" }, "bgcolor": { "type": "string" } }, "required": [ "label", "bgcolor" ], "additionalProperties": false }, "due_date": { "type": "string" }, "cells": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "description": "Custom cell values keyed by column title (e.g. `Source`, `Company`, `Value`)." }, "source": { "type": "object", "properties": { "chat_id": { "type": "string", "description": "WhatsApp chat id the item was extracted from." }, "chat_name": { "type": "string", "maxLength": 200, "description": "Human-readable chat/contact name the item was extracted from (surfaced on the board Source cell)." }, "message_key": { "type": "string", "description": "WhatsApp message key the item was extracted from." }, "excerpt": { "type": "string", "maxLength": 2000, "description": "Short verbatim source excerpt." }, "extracted_at": { "type": "integer", "description": "Extraction time (epoch ms)." } }, "additionalProperties": false }, "confidence": { "type": "number" }, "last_seen_at": { "type": "integer" }, "web_url": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "item_id", "text", "web_url", "created_at", "updated_at" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "boards.items.create" } }, "/v1/boards/{boardId}/items/{itemId}": { "patch": { "tags": [ "Boards" ], "summary": "Update board item", "description": "Update cells, soft-delete (`deleted:true`) or restore (`deleted:false`) an item. `note` is recorded in aiMeta.history. Requires `boards:write`.", "security": [ { "BearerAuth": [ "boards:write" ] } ], "parameters": [ { "name": "boardId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 2000 }, "status": { "type": "string", "maxLength": 120 }, "priority": { "type": "string", "maxLength": 120 }, "due_date": { "type": "string", "maxLength": 64 }, "cells": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "description": "Custom cell values keyed by column title (e.g. `Source`, `Company`, `Value`)." }, "source": { "type": "object", "properties": { "chat_id": { "type": "string", "description": "WhatsApp chat id the item was extracted from." }, "chat_name": { "type": "string", "maxLength": 200, "description": "Human-readable chat/contact name the item was extracted from (surfaced on the board Source cell)." }, "message_key": { "type": "string", "description": "WhatsApp message key the item was extracted from." }, "excerpt": { "type": "string", "maxLength": 2000, "description": "Short verbatim source excerpt." }, "extracted_at": { "type": "integer", "description": "Extraction time (epoch ms)." } }, "additionalProperties": false }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "deleted": { "type": "boolean", "description": "Soft-delete (`true`) or restore (`false`)." }, "note": { "type": "string", "maxLength": 500, "description": "Note recorded in aiMeta.history for this change." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "item_id": { "type": "string" }, "text": { "type": "string" }, "status": { "type": "object", "properties": { "label": { "type": "string" }, "bgcolor": { "type": "string" } }, "required": [ "label", "bgcolor" ], "additionalProperties": false }, "priority": { "type": "object", "properties": { "label": { "type": "string" }, "bgcolor": { "type": "string" } }, "required": [ "label", "bgcolor" ], "additionalProperties": false }, "due_date": { "type": "string" }, "cells": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "description": "Custom cell values keyed by column title (e.g. `Source`, `Company`, `Value`)." }, "source": { "type": "object", "properties": { "chat_id": { "type": "string", "description": "WhatsApp chat id the item was extracted from." }, "chat_name": { "type": "string", "maxLength": 200, "description": "Human-readable chat/contact name the item was extracted from (surfaced on the board Source cell)." }, "message_key": { "type": "string", "description": "WhatsApp message key the item was extracted from." }, "excerpt": { "type": "string", "maxLength": 2000, "description": "Short verbatim source excerpt." }, "extracted_at": { "type": "integer", "description": "Extraction time (epoch ms)." } }, "additionalProperties": false }, "confidence": { "type": "number" }, "last_seen_at": { "type": "integer" }, "web_url": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "item_id", "text", "web_url", "created_at", "updated_at" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "boards.items.update" } }, "/v1/boards/{boardId}/items/bulk": { "post": { "tags": [ "Boards" ], "summary": "Bulk upsert board items", "description": "Create or merge many items in one call. Each item is fingerprinted and matched against the board's existing items — a match is patched (merging richer fields, bumping last-seen), a miss is created. Keeps scan-merge token cost flat. Requires `boards:write`.", "security": [ { "BearerAuth": [ "boards:write" ] } ], "parameters": [ { "name": "boardId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Item title." }, "status": { "type": "string", "maxLength": 120, "description": "Status LABEL (resolved to the board option; unknown label → 422)." }, "priority": { "type": "string", "maxLength": 120, "description": "Priority LABEL (resolved to the board option; unknown label → 422)." }, "due_date": { "type": "string", "maxLength": 64, "description": "Due date (ISO 8601 or date string), stored on the Date column." }, "cells": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "description": "Custom cell values keyed by column title (e.g. `Source`, `Company`, `Value`)." }, "source": { "type": "object", "properties": { "chat_id": { "type": "string", "description": "WhatsApp chat id the item was extracted from." }, "chat_name": { "type": "string", "maxLength": 200, "description": "Human-readable chat/contact name the item was extracted from (surfaced on the board Source cell)." }, "message_key": { "type": "string", "description": "WhatsApp message key the item was extracted from." }, "excerpt": { "type": "string", "maxLength": 2000, "description": "Short verbatim source excerpt." }, "extracted_at": { "type": "integer", "description": "Extraction time (epoch ms)." } }, "additionalProperties": false }, "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Extraction confidence 0..1." }, "allow_duplicate": { "type": "boolean", "description": "By default, creating an item that matches an existing active item (fingerprint or fuzzy title) MERGES into it instead of creating a duplicate (the response then carries `merged: true`). Pass `true` to force creation." } }, "required": [ "text" ], "additionalProperties": false }, "minItems": 1, "maxItems": 500 }, "mode": { "type": "string", "enum": [ "upsert" ], "default": "upsert", "description": "Merge strategy. `upsert` (default): fingerprint-match existing items → patch, else create." } }, "required": [ "items" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "merge report", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "created": { "type": "array", "items": { "type": "object", "properties": { "item_id": { "type": "string" }, "text": { "type": "string" }, "status": { "type": "object", "properties": { "label": { "type": "string" }, "bgcolor": { "type": "string" } }, "required": [ "label", "bgcolor" ], "additionalProperties": false }, "priority": { "type": "object", "properties": { "label": { "type": "string" }, "bgcolor": { "type": "string" } }, "required": [ "label", "bgcolor" ], "additionalProperties": false }, "due_date": { "type": "string" }, "cells": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "description": "Custom cell values keyed by column title (e.g. `Source`, `Company`, `Value`)." }, "source": { "type": "object", "properties": { "chat_id": { "type": "string", "description": "WhatsApp chat id the item was extracted from." }, "chat_name": { "type": "string", "maxLength": 200, "description": "Human-readable chat/contact name the item was extracted from (surfaced on the board Source cell)." }, "message_key": { "type": "string", "description": "WhatsApp message key the item was extracted from." }, "excerpt": { "type": "string", "maxLength": 2000, "description": "Short verbatim source excerpt." }, "extracted_at": { "type": "integer", "description": "Extraction time (epoch ms)." } }, "additionalProperties": false }, "confidence": { "type": "number" }, "last_seen_at": { "type": "integer" }, "web_url": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "item_id", "text", "web_url", "created_at", "updated_at" ], "additionalProperties": false } }, "updated": { "type": "array", "items": { "type": "object", "properties": { "item_id": { "type": "string" }, "text": { "type": "string" }, "status": { "type": "object", "properties": { "label": { "type": "string" }, "bgcolor": { "type": "string" } }, "required": [ "label", "bgcolor" ], "additionalProperties": false }, "priority": { "type": "object", "properties": { "label": { "type": "string" }, "bgcolor": { "type": "string" } }, "required": [ "label", "bgcolor" ], "additionalProperties": false }, "due_date": { "type": "string" }, "cells": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "description": "Custom cell values keyed by column title (e.g. `Source`, `Company`, `Value`)." }, "source": { "type": "object", "properties": { "chat_id": { "type": "string", "description": "WhatsApp chat id the item was extracted from." }, "chat_name": { "type": "string", "maxLength": 200, "description": "Human-readable chat/contact name the item was extracted from (surfaced on the board Source cell)." }, "message_key": { "type": "string", "description": "WhatsApp message key the item was extracted from." }, "excerpt": { "type": "string", "maxLength": 2000, "description": "Short verbatim source excerpt." }, "extracted_at": { "type": "integer", "description": "Extraction time (epoch ms)." } }, "additionalProperties": false }, "confidence": { "type": "number" }, "last_seen_at": { "type": "integer" }, "web_url": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "item_id", "text", "web_url", "created_at", "updated_at" ], "additionalProperties": false } }, "unchanged": { "type": "integer", "minimum": 0 }, "board": { "type": "object", "properties": { "board_id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "domain": { "type": "string" }, "web_url": { "type": "string" } }, "required": [ "board_id", "name", "web_url" ], "additionalProperties": false } }, "required": [ "created", "updated", "unchanged", "board" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "boards.items.bulk.create" } }, "/v1/boards/{boardId}/items/find-similar": { "post": { "tags": [ "Boards" ], "summary": "Find similar board items", "description": "Server-side dedupe: match each candidate text against the board's items by normalized fingerprint + fuzzy token overlap, returning match pairs (and the misses). Use before creating to avoid duplicates. Requires `boards:read`.", "security": [ { "BearerAuth": [ "boards:read" ] } ], "parameters": [ { "name": "boardId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "candidates": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "text" ], "additionalProperties": false }, "minItems": 1, "maxItems": 500 } }, "required": [ "candidates" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "matches", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "matches": { "type": "array", "items": { "type": "object", "properties": { "candidate_index": { "type": "integer" }, "item_id": { "type": "string" }, "text": { "type": "string" }, "score": { "type": "number" } }, "required": [ "candidate_index", "item_id", "text", "score" ], "additionalProperties": false } }, "misses": { "type": "array", "items": { "type": "integer" } } }, "required": [ "matches", "misses" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "boards.items.findsimilar.create" } }, "/v1/latest-chats": { "get": { "tags": [ "Chats" ], "summary": "Get latest chats & messages", "description": "Returns the most-recent non-archived chats (pinned first), each with its latest messages (newest-first). One call — no per-chat round-trips. Requires `chats:read`.", "security": [ { "BearerAuth": [ "chats:read" ] } ], "parameters": [ { "name": "numberOfChats", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Total chats to return, pinned first then most-recent (1-200, default 50)." }, { "name": "numberOfMessages", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 100, "default": 20 }, "description": "Latest messages to include per chat, newest-first (0-100, default 20)." } ], "responses": { "200": { "description": "latest chats with messages", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "chats": { "type": "array", "items": { "type": "object", "properties": { "chatId": { "type": "string", "description": "WhatsApp JID of the chat — `@c.us` for a 1:1 contact, `@g.us` for a group, `@newsletter` for a channel." }, "name": { "type": "string", "description": "Display name of the chat (contact name, group subject, or channel title). Null when WhatsApp has no name for it." }, "chatType": { "type": "string", "enum": [ "contact", "group", "newsletter" ], "description": "Kind of chat: `contact` (1:1), `group`, or `newsletter` (WhatsApp Channel). The three are mutually exclusive." }, "pinned": { "type": "boolean", "description": "True when the chat is pinned to the top of the chat list." }, "archived": { "type": "boolean", "description": "True when the chat is archived. Excluded from list responses unless `includeArchive=true`." }, "lastMessageAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp of the most recent message in this chat. Null when the chat has no messages." }, "unreadCount": { "type": "integer", "minimum": 0, "description": "Count of unseen incoming messages (>= 0). Excludes the \"manually marked unread\" sentinel — see `markedUnread`." }, "markedUnread": { "type": "boolean", "description": "True when the chat was manually flagged unread in WhatsApp (the dot badge), distinct from having N unread messages." }, "lastMessageText": { "type": "string", "description": "Preview text of the most recent message. Present only when includeLastMessage=true." }, "lastMessageFromMe": { "type": "boolean", "description": "True if the last message was sent by the connected account. Present only when includeLastMessage=true." }, "messages": { "type": "array", "items": { "type": "object", "properties": { "waMessageKey": { "type": "object", "properties": { "fromMe": { "type": "boolean" }, "remote": { "type": "string" }, "id": { "type": "string" }, "_serialized": { "type": "string" }, "participant": { "type": "string" } }, "required": [ "fromMe" ], "additionalProperties": false }, "chatId": { "type": "string" }, "from": { "type": "string" }, "author": { "type": "string" }, "senderName": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "text": { "type": "string" }, "type": { "type": "string" }, "fromMe": { "type": "boolean" }, "ack": { "type": "integer" }, "mediaUrl": { "type": "string" }, "filename": { "type": "string" }, "linkPreview": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "canonicalUrl": { "type": "string" }, "thumbnail": { "type": "string" } }, "additionalProperties": false }, "quotedMessage": { "type": "object", "properties": { "waMessageKey": { "type": "object", "properties": { "fromMe": { "type": "boolean" }, "remote": { "type": "string" }, "id": { "type": "string" }, "_serialized": { "type": "string" }, "participant": { "type": "string" } }, "required": [ "fromMe" ], "additionalProperties": false }, "text": { "type": "string" }, "type": { "type": "string" }, "author": { "type": "string" } }, "required": [ "waMessageKey" ], "additionalProperties": false } }, "required": [ "waMessageKey", "chatId", "from", "type", "fromMe" ], "additionalProperties": false }, "description": "Latest messages in this chat, newest-first (up to numberOfMessages)." } }, "required": [ "chatId", "chatType", "markedUnread", "messages" ], "additionalProperties": false, "description": "A WhatsApp chat with its most recent messages attached." } }, "totalChats": { "type": "integer", "description": "Non-archived, titled chat count before the numberOfChats slice." }, "numberOfChats": { "type": "integer", "description": "Effective chats cap applied." }, "numberOfMessages": { "type": "integer", "description": "Effective per-chat messages cap applied." } }, "required": [ "chats", "totalChats", "numberOfChats", "numberOfMessages" ], "additionalProperties": false, "description": "Most-recent non-archived chats (pinned first), each with their latest messages." } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "latest-chats.list" } }, "/v1/chats/{chatId}/participants": { "get": { "tags": [ "Chats" ], "summary": "List chat participants", "description": "For group chats, returns the participant list (paginated). For DMs, returns the single counterparty. Requires `chats:read`.", "security": [ { "BearerAuth": [ "chats:read" ] } ], "parameters": [ { "name": "chatId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "searchToken", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Search token; when set, only participants whose resolved name or phone/JID matches (case-insensitive substring) are returned, and `total` reflects the matched count." }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of participants to skip before the page (default 0)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }, "description": "Max participants to return." } ], "responses": { "200": { "description": "participants", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "array", "items": { "type": "object", "properties": { "chatId": { "type": "string", "description": "WhatsApp JID (`@c.us`) of this group participant." }, "name": { "type": "string", "description": "Participant's display name, or null when the engine couldn't resolve one." }, "isAdmin": { "type": "boolean", "description": "True when this participant is a group admin." }, "isSuperAdmin": { "type": "boolean", "description": "True when this participant is the group creator / super-admin." } }, "required": [ "chatId", "isAdmin" ], "additionalProperties": false, "description": "One member of a WhatsApp group, with their admin standing." } }, "limit": { "type": "integer", "description": "Page size echoed back from the request." }, "skip": { "type": "integer", "description": "Offset echoed back from the request." }, "total": { "type": "integer", "description": "Total number of items matching the query, across all pages." } }, "required": [ "success", "data", "limit", "skip", "total" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "chats.participants.list" } }, "/v1/chats/{chatId}/mark_read": { "post": { "tags": [ "Chats" ], "summary": "Mark chat as read", "description": "Clears the unread badge on the connected engine for the given chat. Requires `chats:write`.", "security": [ { "BearerAuth": [ "chats:write" ] } ], "parameters": [ { "name": "chatId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "marked read", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "chats.markread.create" } }, "/v1/chats/{chatId}/archive": { "post": { "tags": [ "Chats" ], "summary": "Archive chat", "description": "Archives the given chat on the connected engine, hiding it from the main chat list. Requires `chats:write`.", "security": [ { "BearerAuth": [ "chats:write" ] } ], "parameters": [ { "name": "chatId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "archived", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "chats.archive.create" } }, "/v1/chats/{chatId}/unarchive": { "post": { "tags": [ "Chats" ], "summary": "Unarchive chat", "description": "Removes the given chat from the archive, restoring it to the main chat list. Requires `chats:write`.", "security": [ { "BearerAuth": [ "chats:write" ] } ], "parameters": [ { "name": "chatId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "unarchived", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "chats.unarchive.create" } }, "/v1/messages/ack/{waMessageKey}": { "get": { "tags": [ "Messages" ], "summary": "Get message delivery status", "description": "Returns the WhatsApp ack value for a sent message: -1=error, 0=pending, 1=server, 2=device, 3=read, 4=played. Requires `chats:read`.", "security": [ { "BearerAuth": [ "chats:read" ] } ], "parameters": [ { "name": "waMessageKey", "in": "path", "required": true, "description": "The complete WhatsApp message key (`__[_]`), e.g. `false_120363426216988013@g.us_3EB0659D13650092D677AD_188450464616609@lid`.", "schema": { "type": "string" } }, { "name": "chatId", "in": "query", "required": false, "description": "Optional. Only used to find the message faster — when you pass a bare message id instead of the complete key, `chatId` lets the server rebuild the full key. If you pass the complete `waMessageKey` you can omit it.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "ack", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "ack": { "type": "integer", "description": "-1=error, 0=pending, 1=server, 2=device, 3=read, 4=played; null when no engine response." } }, "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "messages.ack.get" } }, "/v1/messages/reactions/{waMessageKey}": { "post": { "tags": [ "Messages" ], "summary": "React to message", "description": "Add or replace your reaction to a message. Pass an empty `emoji` string to remove. Requires `chats:write`.", "security": [ { "BearerAuth": [ "chats:write" ] } ], "parameters": [ { "name": "waMessageKey", "in": "path", "required": true, "description": "The complete WhatsApp message key (`__[_]`), e.g. `false_120363426216988013@g.us_3EB0659D13650092D677AD_188450464616609@lid`.", "schema": { "type": "string" } }, { "name": "chatId", "in": "query", "required": false, "description": "Optional. Only used to find the message faster — when you pass a bare message id instead of the complete key, `chatId` lets the server rebuild the full key. If you pass the complete `waMessageKey` you can omit it.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "emoji": { "type": "string", "minLength": 0, "maxLength": 32 } }, "required": [ "emoji" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "reaction set", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "messages.reactions.create" } }, "/v1/messages/load_older/{chatId}": { "post": { "tags": [ "Messages" ], "summary": "Load older messages", "description": "Asks the engine to pull older history from the connected phone for chats that haven't been fully synced yet. Use this before paginating with `since` if you need messages older than what's already cached. Optionally pull several pages in one call via `pages` (WA-paced ~2.5s apart) and/or stop at a target depth via `until_date`; the response reports how far back the chat is now loaded under `coverage`. Requires `chats:read`.", "security": [ { "BearerAuth": [ "chats:read" ] } ], "parameters": [ { "name": "chatId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "pages": { "type": "integer", "minimum": 1, "maximum": 10, "description": "How many older pages to pull in one call (1-10, default 1). Pages are WA-paced ~2.5s apart. Stops early on exhaustion, error, or reaching `until_date`." }, "until_date": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "Stop once the oldest loaded message is at/before this date (ISO 8601 string or epoch seconds/ms). Lets you page back to a target depth deterministically." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "load result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "totalMessages": { "type": "integer" }, "added": { "type": "integer", "description": "Total messages added to the store across the pages this call executed (sum). `0` with `canLoadMore:true` is a transient hiccup worth retrying; `canLoadMore:false` means genuinely exhausted." }, "canLoadMore": { "type": "boolean", "description": "From the LAST executed page: true = the engine believes more history may still be pulled; false = genuinely exhausted (stop paging)." }, "historyUnavailable": { "type": "boolean", "description": "True when no older messages could be pulled because the phone reported it has no retrievable history for this chat (or the phone is offline). When true, `added` is 0, `canLoadMore` is false, and `error` carries the reason. This is distinct from a chat that is simply already fully synced (historyUnavailable=false, added=0)." }, "error": { "type": "string", "description": "Human-readable reason older messages could not be loaded from the phone; null when the pull succeeded or the chat is already fully synced. First fatal error across the executed pages." }, "pagesExecuted": { "type": "integer", "description": "How many older pages this call actually pulled (1..pages). Fewer than requested when the loop stopped early on exhaustion, error, or reaching `until_date`." }, "coverage": { "type": "object", "properties": { "oldestLoadedTimestamp": { "type": "number", "description": "Epoch MILLISECONDS of the oldest currently-loaded message for this chat. Omitted when unknown (empty chat / probe unavailable)." }, "oldestLoadedIso": { "type": "string", "description": "ISO 8601 form of `oldestLoadedTimestamp`. Use it to verify range coverage (\"did I reach a year back?\") deterministically." } }, "additionalProperties": false, "description": "How far back the chat is now loaded. `coverage.oldestLoadedIso` is the deterministic answer to \"have I reached far enough back?\"." } }, "required": [ "canLoadMore", "historyUnavailable", "pagesExecuted", "coverage" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "messages.loadolder.create" } }, "/v1/messages/acks": { "post": { "tags": [ "Messages" ], "summary": "Batch get message acks", "description": "Get delivery status for up to 200 sent messages in one call. Useful for campaign dashboards / status reconciliation. Requires `chats:read`.", "security": [ { "BearerAuth": [ "chats:read" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "messageKeys": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 200 }, "chatId": { "type": "string", "minLength": 1 } }, "required": [ "messageKeys" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "ack data", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "ack": { "type": "integer", "description": "-1=error, 0=pending, 1=server, 2=device, 3=read, 4=played; null when the message has no determined ack — or when the key was not found (see `found`)." }, "found": { "type": "boolean", "description": "True when the message exists in the engine store. False when the requested key has no matching message; in that case `ack` is null by definition." } }, "required": [ "key", "found" ], "additionalProperties": false } }, "limit": { "type": "integer", "description": "Page size echoed back from the request." }, "skip": { "type": "integer", "description": "Offset echoed back from the request." }, "total": { "type": "integer", "description": "Total number of items matching the query, across all pages." } }, "required": [ "success", "data", "limit", "skip", "total" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "messages.acks" } }, "/v1/messages/media/{waMessageKey}": { "get": { "tags": [ "Messages" ], "summary": "Get message media", "description": "Download the media attached to a WhatsApp message (image, video, document, audio).\nReturns either a hosted URL (`url`) or inline `dataBase64`, plus mimetype + filename.\n\nThe engine fetches media lazily, so the first call right after a message arrives may still be in flight. By default the server polls up to 6 times (1.5s apart) until the bytes are ready. Pass `?maxAttempts=1` to skip the poll and return immediately (the fast path — useful when you only need the hosted `url` and can tolerate a retry yourself).\n\nCAVEAT: for own-sent newsletter media (messages you sent to a `@newsletter` chat), the bytes returned are a WA-generated preview JPEG (~7KB) rather than the original you uploaded — WA releases the original blob from memory immediately after the unencrypted upload. The response will include `originalQuality:false` when this fallback is in effect; the caller can warn the user or decide to retry from a different source.\n\nRequires `chats:read`.", "security": [ { "BearerAuth": [ "chats:read" ] } ], "parameters": [ { "name": "waMessageKey", "in": "path", "required": true, "description": "The complete WhatsApp message key (`__[_]`), e.g. `false_120363426216988013@g.us_3EB0659D13650092D677AD_188450464616609@lid`.", "schema": { "type": "string" } }, { "name": "chatId", "in": "query", "required": false, "description": "Optional. Only used to find the message faster — when you pass a bare message id instead of the complete key, `chatId` lets the server rebuild the full key. If you pass the complete `waMessageKey` you can omit it.", "schema": { "type": "string" } }, { "name": "maxAttempts", "in": "query", "required": false, "description": "Optional. Maximum number of engine attempts (including the first) while the media is still being fetched from the phone. Defaults to `6`; pass `1` to skip retries and return immediately. Range 1–10.", "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 6 } } ], "responses": { "200": { "description": "media", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "url": { "type": "string" }, "mimetype": { "type": "string" }, "filename": { "type": "string" }, "dataBase64": { "type": "string" }, "originalQuality": { "type": "boolean", "description": "Set to false when the bytes returned are NOT the original sender uploaded — i.e. WA released the original from memory and we synthesized from a smaller WA-generated preview (#113). Currently only happens for own-sent newsletter media (messages you sent to a @newsletter chat). When absent or true, the bytes are the genuine original. Consumers can use this to warn users / decide whether to retry from a different source." }, "mediaUnavailable": { "type": "string", "enum": [ "expired", "fetching", "awaiting_sender", "error", "no_media" ], "description": "Set when the bytes could not be downloaded or never existed. \"expired\" = WA aged the file out of CDN retention (typically older than ~30 days for documents) and there is nothing to retry. \"fetching\" = WA is mid-download from its CDN — transient, the server already retried for ~10s; calling again in a few seconds usually resolves to bytes. \"awaiting_sender\" = WA's CDN does not have the file but has asked the sender's device to reupload it. The reupload only completes when the sender's WhatsApp client is open and online; closed/backgrounded apps block it indefinitely. Tell the user to ask the sender to open WhatsApp; do not poll. \"error\" = unexpected failure; \"no_media\" = the message is text-only / revoked / location / vcard, i.e. it never carried media — caller should not have invoked this tool on this messageKey. Absent when bytes were not needed or when the fetch succeeded." } }, "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "messages.media.get" } }, "/v1/messages/pinned/{chatId}": { "get": { "tags": [ "Messages" ], "summary": "List pinned messages", "description": "List the currently pinned messages in a chat. Requires `chats:read`.", "security": [ { "BearerAuth": [ "chats:read" ] } ], "parameters": [ { "name": "chatId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "pinned messages", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "chatId": { "type": "string" }, "text": { "type": "string" } }, "required": [ "key", "chatId" ], "additionalProperties": false } }, "limit": { "type": "integer", "description": "Page size echoed back from the request." }, "skip": { "type": "integer", "description": "Offset echoed back from the request." }, "total": { "type": "integer", "description": "Total number of items matching the query, across all pages." } }, "required": [ "success", "data", "limit", "skip", "total" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "messages.pinned.get" } }, "/v1/messages/pin/{waMessageKey}": { "post": { "tags": [ "Messages" ], "summary": "Pin message", "description": "Pin a message to the top of its chat. Optionally pass a `duration` (seconds) in the body to control when the pin expires — defaults to 7 days. Requires `chats:write`.", "security": [ { "BearerAuth": [ "chats:write" ] } ], "parameters": [ { "name": "waMessageKey", "in": "path", "required": true, "description": "The complete WhatsApp message key (`__[_]`), e.g. `false_120363426216988013@g.us_3EB0659D13650092D677AD_188450464616609@lid`.", "schema": { "type": "string" } }, { "name": "chatId", "in": "query", "required": false, "description": "Optional. Only used to find the message faster — when you pass a bare message id instead of the complete key, `chatId` lets the server rebuild the full key. If you pass the complete `waMessageKey` you can omit it.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "duration": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "message pinned", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "messages.pin.create" } }, "/v1/messages/unpin/{waMessageKey}": { "post": { "tags": [ "Messages" ], "summary": "Unpin message", "description": "Remove an existing pin from a message. Requires `chats:write`.", "security": [ { "BearerAuth": [ "chats:write" ] } ], "parameters": [ { "name": "waMessageKey", "in": "path", "required": true, "description": "The complete WhatsApp message key (`__[_]`), e.g. `false_120363426216988013@g.us_3EB0659D13650092D677AD_188450464616609@lid`.", "schema": { "type": "string" } }, { "name": "chatId", "in": "query", "required": false, "description": "Optional. Only used to find the message faster — when you pass a bare message id instead of the complete key, `chatId` lets the server rebuild the full key. If you pass the complete `waMessageKey` you can omit it.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "message unpinned", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always `true` on success responses." }, "data": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request — invalid params or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed — see `error.details` for per-field issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "messages.unpin.create" } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "bt__..." } }, "schemas": { "AccountResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier for the account." }, "name": { "type": "string", "description": "Account display name." }, "userEmail": { "type": "string", "nullable": true, "description": "Email address of the user the API key belongs to, or null if unavailable." }, "timezone": { "type": "string", "nullable": true, "description": "IANA timezone (e.g. \"America/New_York\"), or null if unset." }, "createdAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp of account creation." } }, "required": [ "id", "name", "userEmail", "timezone", "createdAt" ] }, "AppendContactsRequest": { "type": "object", "properties": { "contacts": { "type": "array", "items": { "type": "object", "properties": { "to": { "type": "string", "description": "Recipient. A phone number (+E164), or a WhatsApp JID — individual (…@c.us), group (…@g.us), or newsletter (…@newsletter). Individual recipients are stored in international format; group/newsletter ids are stored verbatim." }, "variables": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 1024 }, "description": "Per-contact substitution values used by campaign templates.\nEach key becomes a token usable as `{key}` in a campaign `text`. Lookup is case-insensitive (e.g. `{firstName}` resolves `firstname`).\nBuilt-in tokens always available regardless of variables: `{whatsappname}`, `{displayname}`, `{phone}`, `{mobile}`. Setting a variable with the same name overrides the built-in.\nStorage: keys are persisted as text-cell column titles on the audience board, so values flow back via audiences.get under the same names.\nLimits: at most 32 keys per contact; values up to 1024 chars; keys must match /^[A-Za-z_][A-Za-z0-9_]{0,31}$/." } }, "required": [ "to" ], "additionalProperties": false }, "minItems": 1, "maxItems": 1000 } }, "required": [ "contacts" ], "additionalProperties": false }, "AudienceResponse": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "contactCount": { "type": "integer", "minimum": 0 }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "contactCount", "createdAt" ], "additionalProperties": false }, "ContactInput": { "type": "object", "properties": { "to": { "type": "string", "description": "Recipient. A phone number (+E164), or a WhatsApp JID — individual (…@c.us), group (…@g.us), or newsletter (…@newsletter). Individual recipients are stored in international format; group/newsletter ids are stored verbatim." }, "variables": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 1024 }, "description": "Per-contact substitution values used by campaign templates.\nEach key becomes a token usable as `{key}` in a campaign `text`. Lookup is case-insensitive (e.g. `{firstName}` resolves `firstname`).\nBuilt-in tokens always available regardless of variables: `{whatsappname}`, `{displayname}`, `{phone}`, `{mobile}`. Setting a variable with the same name overrides the built-in.\nStorage: keys are persisted as text-cell column titles on the audience board, so values flow back via audiences.get under the same names.\nLimits: at most 32 keys per contact; values up to 1024 chars; keys must match /^[A-Za-z_][A-Za-z0-9_]{0,31}$/." } }, "required": [ "to" ], "additionalProperties": false }, "ContactResponse": { "type": "object", "properties": { "id": { "type": "string" }, "to": { "type": "string" }, "variables": { "type": "object", "additionalProperties": { "type": "string" } }, "addedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "to", "variables", "addedAt" ], "additionalProperties": false }, "CreateAudienceRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "contacts": { "type": "array", "items": { "type": "object", "properties": { "to": { "type": "string", "description": "Recipient. A phone number (+E164), or a WhatsApp JID — individual (…@c.us), group (…@g.us), or newsletter (…@newsletter). Individual recipients are stored in international format; group/newsletter ids are stored verbatim." }, "variables": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 1024 }, "description": "Per-contact substitution values used by campaign templates.\nEach key becomes a token usable as `{key}` in a campaign `text`. Lookup is case-insensitive (e.g. `{firstName}` resolves `firstname`).\nBuilt-in tokens always available regardless of variables: `{whatsappname}`, `{displayname}`, `{phone}`, `{mobile}`. Setting a variable with the same name overrides the built-in.\nStorage: keys are persisted as text-cell column titles on the audience board, so values flow back via audiences.get under the same names.\nLimits: at most 32 keys per contact; values up to 1024 chars; keys must match /^[A-Za-z_][A-Za-z0-9_]{0,31}$/." } }, "required": [ "to" ], "additionalProperties": false }, "maxItems": 1000 } }, "required": [ "name" ], "additionalProperties": false }, "PatchAudienceRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "name" ], "additionalProperties": false }, "PatchContactRequest": { "type": "object", "properties": { "to": { "type": "string" }, "variables": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 1024 }, "description": "Per-contact substitution values used by campaign templates.\nEach key becomes a token usable as `{key}` in a campaign `text`. Lookup is case-insensitive (e.g. `{firstName}` resolves `firstname`).\nBuilt-in tokens always available regardless of variables: `{whatsappname}`, `{displayname}`, `{phone}`, `{mobile}`. Setting a variable with the same name overrides the built-in.\nStorage: keys are persisted as text-cell column titles on the audience board, so values flow back via audiences.get under the same names.\nLimits: at most 32 keys per contact; values up to 1024 chars; keys must match /^[A-Za-z_][A-Za-z0-9_]{0,31}$/." } }, "additionalProperties": false }, "BoardColumn": { "type": "object", "properties": { "column_id": { "type": "string" }, "title": { "type": "string" }, "type": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "bgcolor": { "type": "string" } }, "required": [ "label", "bgcolor" ], "additionalProperties": false }, "description": "Selectable options (status/priority columns); empty otherwise." } }, "required": [ "column_id", "title", "type", "options" ], "additionalProperties": false }, "BoardDetail": { "type": "object", "properties": { "board_id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "description": "One-line board purpose (subtitle + agent board-directory line)." }, "domain": { "type": "string" }, "agent_managed": { "type": "boolean" }, "memory_retention_days": { "type": "integer" }, "item_count": { "type": "integer" }, "web_url": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "columns": { "type": "array", "items": { "type": "object", "properties": { "column_id": { "type": "string" }, "title": { "type": "string" }, "type": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "bgcolor": { "type": "string" } }, "required": [ "label", "bgcolor" ], "additionalProperties": false }, "description": "Selectable options (status/priority columns); empty otherwise." } }, "required": [ "column_id", "title", "type", "options" ], "additionalProperties": false } } }, "required": [ "board_id", "name", "agent_managed", "web_url", "created_at", "updated_at", "columns" ], "additionalProperties": false }, "BoardItem": { "type": "object", "properties": { "item_id": { "type": "string" }, "text": { "type": "string" }, "status": { "type": "object", "nullable": true, "properties": { "label": { "type": "string" }, "bgcolor": { "type": "string" } }, "required": [ "label", "bgcolor" ], "additionalProperties": false }, "priority": { "type": "object", "nullable": true, "properties": { "label": { "type": "string" }, "bgcolor": { "type": "string" } }, "required": [ "label", "bgcolor" ], "additionalProperties": false }, "due_date": { "type": "string" }, "cells": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "description": "Custom cell values keyed by column title (e.g. `Source`, `Company`, `Value`)." }, "source": { "type": "object", "properties": { "chat_id": { "type": "string", "description": "WhatsApp chat id the item was extracted from." }, "chat_name": { "type": "string", "maxLength": 200, "description": "Human-readable chat/contact name the item was extracted from (surfaced on the board Source cell)." }, "message_key": { "type": "string", "description": "WhatsApp message key the item was extracted from." }, "excerpt": { "type": "string", "maxLength": 2000, "description": "Short verbatim source excerpt." }, "extracted_at": { "type": "integer", "description": "Extraction time (epoch ms)." } }, "additionalProperties": false }, "confidence": { "type": "number" }, "last_seen_at": { "type": "integer" }, "web_url": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "item_id", "text", "status", "priority", "web_url", "created_at", "updated_at" ], "additionalProperties": false }, "BoardRef": { "type": "object", "properties": { "board_id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "domain": { "type": "string" }, "web_url": { "type": "string" } }, "required": [ "board_id", "name", "web_url" ], "additionalProperties": false }, "BoardRow": { "type": "object", "properties": { "board_id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "description": "One-line board purpose (subtitle + agent board-directory line)." }, "domain": { "type": "string" }, "agent_managed": { "type": "boolean" }, "memory_retention_days": { "type": "integer" }, "item_count": { "type": "integer" }, "web_url": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "board_id", "name", "agent_managed", "web_url", "created_at", "updated_at" ], "additionalProperties": false }, "BulkItemsRequest": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Item title." }, "status": { "type": "string", "maxLength": 120, "description": "Status LABEL (resolved to the board option; unknown label → 422)." }, "priority": { "type": "string", "maxLength": 120, "description": "Priority LABEL (resolved to the board option; unknown label → 422)." }, "due_date": { "type": "string", "maxLength": 64, "description": "Due date (ISO 8601 or date string), stored on the Date column." }, "cells": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "description": "Custom cell values keyed by column title (e.g. `Source`, `Company`, `Value`)." }, "source": { "type": "object", "properties": { "chat_id": { "type": "string", "description": "WhatsApp chat id the item was extracted from." }, "chat_name": { "type": "string", "maxLength": 200, "description": "Human-readable chat/contact name the item was extracted from (surfaced on the board Source cell)." }, "message_key": { "type": "string", "description": "WhatsApp message key the item was extracted from." }, "excerpt": { "type": "string", "maxLength": 2000, "description": "Short verbatim source excerpt." }, "extracted_at": { "type": "integer", "description": "Extraction time (epoch ms)." } }, "additionalProperties": false }, "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Extraction confidence 0..1." }, "allow_duplicate": { "type": "boolean", "description": "By default, creating an item that matches an existing active item (fingerprint or fuzzy title) MERGES into it instead of creating a duplicate (the response then carries `merged: true`). Pass `true` to force creation." } }, "required": [ "text" ], "additionalProperties": false }, "minItems": 1, "maxItems": 500 }, "mode": { "type": "string", "enum": [ "upsert" ], "default": "upsert", "description": "Merge strategy. `upsert` (default): fingerprint-match existing items → patch, else create." } }, "required": [ "items" ], "additionalProperties": false }, "BulkItemsResponse": { "type": "object", "properties": { "created": { "type": "array", "items": { "type": "object", "properties": { "item_id": { "type": "string" }, "text": { "type": "string" }, "status": { "type": "object", "nullable": true, "properties": { "label": { "type": "string" }, "bgcolor": { "type": "string" } }, "required": [ "label", "bgcolor" ], "additionalProperties": false }, "priority": { "type": "object", "nullable": true, "properties": { "label": { "type": "string" }, "bgcolor": { "type": "string" } }, "required": [ "label", "bgcolor" ], "additionalProperties": false }, "due_date": { "type": "string" }, "cells": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "description": "Custom cell values keyed by column title (e.g. `Source`, `Company`, `Value`)." }, "source": { "type": "object", "properties": { "chat_id": { "type": "string", "description": "WhatsApp chat id the item was extracted from." }, "chat_name": { "type": "string", "maxLength": 200, "description": "Human-readable chat/contact name the item was extracted from (surfaced on the board Source cell)." }, "message_key": { "type": "string", "description": "WhatsApp message key the item was extracted from." }, "excerpt": { "type": "string", "maxLength": 2000, "description": "Short verbatim source excerpt." }, "extracted_at": { "type": "integer", "description": "Extraction time (epoch ms)." } }, "additionalProperties": false }, "confidence": { "type": "number" }, "last_seen_at": { "type": "integer" }, "web_url": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "item_id", "text", "status", "priority", "web_url", "created_at", "updated_at" ], "additionalProperties": false } }, "updated": { "type": "array", "items": { "type": "object", "properties": { "item_id": { "type": "string" }, "text": { "type": "string" }, "status": { "type": "object", "nullable": true, "properties": { "label": { "type": "string" }, "bgcolor": { "type": "string" } }, "required": [ "label", "bgcolor" ], "additionalProperties": false }, "priority": { "type": "object", "nullable": true, "properties": { "label": { "type": "string" }, "bgcolor": { "type": "string" } }, "required": [ "label", "bgcolor" ], "additionalProperties": false }, "due_date": { "type": "string" }, "cells": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "description": "Custom cell values keyed by column title (e.g. `Source`, `Company`, `Value`)." }, "source": { "type": "object", "properties": { "chat_id": { "type": "string", "description": "WhatsApp chat id the item was extracted from." }, "chat_name": { "type": "string", "maxLength": 200, "description": "Human-readable chat/contact name the item was extracted from (surfaced on the board Source cell)." }, "message_key": { "type": "string", "description": "WhatsApp message key the item was extracted from." }, "excerpt": { "type": "string", "maxLength": 2000, "description": "Short verbatim source excerpt." }, "extracted_at": { "type": "integer", "description": "Extraction time (epoch ms)." } }, "additionalProperties": false }, "confidence": { "type": "number" }, "last_seen_at": { "type": "integer" }, "web_url": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "item_id", "text", "status", "priority", "web_url", "created_at", "updated_at" ], "additionalProperties": false } }, "unchanged": { "type": "integer", "minimum": 0 }, "board": { "type": "object", "properties": { "board_id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "domain": { "type": "string" }, "web_url": { "type": "string" } }, "required": [ "board_id", "name", "web_url" ], "additionalProperties": false } }, "required": [ "created", "updated", "unchanged", "board" ], "additionalProperties": false }, "CellsMap": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "description": "Custom cell values keyed by column title (e.g. `Source`, `Company`, `Value`)." }, "CreateBoardRequest": { "type": "object", "properties": { "domain": { "type": "string", "minLength": 1, "description": "Memory domain id for a built-in board — `tasks`, `leads` or `invoices`. Omit and pass `entity_kind` to open a board for a NEW entity type." }, "entity_kind": { "type": "string", "minLength": 1, "maxLength": 40, "description": "The kind of entity this board tracks (e.g. `reminders`, `orders`, `follow-ups`). Opens a NEW dynamic board with a generic Status/Priority/Date/Source template. Slug-ified server-side; a `custom:` domain is derived unless the slug already names a built-in domain. `description` is REQUIRED for custom boards." }, "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Board name; defaults to the domain label (custom: `🤖 `)." }, "description": { "type": "string", "minLength": 1, "maxLength": 500, "description": "One-line purpose of the board (subtitle + board directory). Optional for built-in domains (falls back to the domain default); REQUIRED for custom `entity_kind` boards (422 if missing)." }, "agent_id": { "type": "string", "maxLength": 200, "description": "Owning agent id for memory isolation (e.g. `btgpt:` or `bot:`). Defaults to `user`." }, "memory_retention_days": { "type": "integer", "minimum": 0, "maximum": 3650, "description": "Retention window in days (default 30; 0 = never expires)." } }, "additionalProperties": false }, "CreateItemRequest": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Item title." }, "status": { "type": "string", "maxLength": 120, "description": "Status LABEL (resolved to the board option; unknown label → 422)." }, "priority": { "type": "string", "maxLength": 120, "description": "Priority LABEL (resolved to the board option; unknown label → 422)." }, "due_date": { "type": "string", "maxLength": 64, "description": "Due date (ISO 8601 or date string), stored on the Date column." }, "cells": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "description": "Custom cell values keyed by column title (e.g. `Source`, `Company`, `Value`)." }, "source": { "type": "object", "properties": { "chat_id": { "type": "string", "description": "WhatsApp chat id the item was extracted from." }, "chat_name": { "type": "string", "maxLength": 200, "description": "Human-readable chat/contact name the item was extracted from (surfaced on the board Source cell)." }, "message_key": { "type": "string", "description": "WhatsApp message key the item was extracted from." }, "excerpt": { "type": "string", "maxLength": 2000, "description": "Short verbatim source excerpt." }, "extracted_at": { "type": "integer", "description": "Extraction time (epoch ms)." } }, "additionalProperties": false }, "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Extraction confidence 0..1." }, "allow_duplicate": { "type": "boolean", "description": "By default, creating an item that matches an existing active item (fingerprint or fuzzy title) MERGES into it instead of creating a duplicate (the response then carries `merged: true`). Pass `true` to force creation." } }, "required": [ "text" ], "additionalProperties": false }, "FindSimilarRequest": { "type": "object", "properties": { "candidates": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "text" ], "additionalProperties": false }, "minItems": 1, "maxItems": 500 } }, "required": [ "candidates" ], "additionalProperties": false }, "FindSimilarResponse": { "type": "object", "properties": { "matches": { "type": "array", "items": { "type": "object", "properties": { "candidate_index": { "type": "integer" }, "item_id": { "type": "string" }, "text": { "type": "string" }, "score": { "type": "number" } }, "required": [ "candidate_index", "item_id", "text", "score" ], "additionalProperties": false } }, "misses": { "type": "array", "items": { "type": "integer" } } }, "required": [ "matches", "misses" ], "additionalProperties": false }, "ItemSource": { "type": "object", "properties": { "chat_id": { "type": "string", "description": "WhatsApp chat id the item was extracted from." }, "chat_name": { "type": "string", "maxLength": 200, "description": "Human-readable chat/contact name the item was extracted from (surfaced on the board Source cell)." }, "message_key": { "type": "string", "description": "WhatsApp message key the item was extracted from." }, "excerpt": { "type": "string", "maxLength": 2000, "description": "Short verbatim source excerpt." }, "extracted_at": { "type": "integer", "description": "Extraction time (epoch ms)." } }, "additionalProperties": false }, "ListBoardsQuery": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Page size (default 50, max 200)." }, "skip": { "type": "integer", "nullable": true, "minimum": 0, "default": 0, "description": "Number of items to skip before the page (default 0)." }, "order": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction by timestamp: `asc` (oldest first) or `desc` (newest first, default)." }, "domain": { "type": "string", "description": "Filter by memory domain id." }, "agent_managed": { "type": "boolean", "description": "When true, only boards with an `agentConfig` (agent-managed)." } } }, "ListItemsQuery": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Page size (default 50, max 200)." }, "skip": { "type": "integer", "nullable": true, "minimum": 0, "default": 0, "description": "Number of items to skip before the page (default 0)." }, "order": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction by timestamp: `asc` (oldest first) or `desc` (newest first, default)." }, "active_only": { "type": "boolean", "default": false, "description": "When true: only items updated within the retention window whose status is non-terminal and not deleted." }, "status": { "type": "string", "description": "Filter by denormalized status label." }, "updated_since": { "type": "string", "description": "ISO 8601 / epoch-ms cutoff; only items updated at or after this time." } } }, "OptionRef": { "type": "object", "properties": { "label": { "type": "string" }, "bgcolor": { "type": "string" } }, "required": [ "label", "bgcolor" ], "additionalProperties": false }, "PatchItemRequest": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 2000 }, "status": { "type": "string", "maxLength": 120 }, "priority": { "type": "string", "maxLength": 120 }, "due_date": { "type": "string", "maxLength": 64 }, "cells": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "description": "Custom cell values keyed by column title (e.g. `Source`, `Company`, `Value`)." }, "source": { "type": "object", "properties": { "chat_id": { "type": "string", "description": "WhatsApp chat id the item was extracted from." }, "chat_name": { "type": "string", "maxLength": 200, "description": "Human-readable chat/contact name the item was extracted from (surfaced on the board Source cell)." }, "message_key": { "type": "string", "description": "WhatsApp message key the item was extracted from." }, "excerpt": { "type": "string", "maxLength": 2000, "description": "Short verbatim source excerpt." }, "extracted_at": { "type": "integer", "description": "Extraction time (epoch ms)." } }, "additionalProperties": false }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "deleted": { "type": "boolean", "description": "Soft-delete (`true`) or restore (`false`)." }, "note": { "type": "string", "maxLength": 500, "description": "Note recorded in aiMeta.history for this change." } }, "additionalProperties": false }, "CampaignResponse": { "type": "object", "properties": { "cmpId": { "type": "string" }, "name": { "type": "string" }, "audienceId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "running", "paused", "complete_sent", "complete_delivered", "aborted" ] }, "totalCount": { "type": "integer", "minimum": 0 }, "sentCount": { "type": "integer", "minimum": 0 }, "deliveredCount": { "type": "integer", "minimum": 0 }, "readCount": { "type": "integer", "minimum": 0 }, "failedCount": { "type": "integer", "minimum": 0 }, "createdAt": { "type": "string", "format": "date-time" }, "startedAt": { "type": "string", "nullable": true, "format": "date-time" }, "completedAt": { "type": "string", "nullable": true, "format": "date-time" }, "abortedAt": { "type": "string", "nullable": true, "format": "date-time" } }, "required": [ "cmpId", "name", "audienceId", "status", "totalCount", "sentCount", "deliveredCount", "readCount", "failedCount", "createdAt", "startedAt", "completedAt", "abortedAt" ], "additionalProperties": false }, "CampaignStatus": { "type": "string", "enum": [ "pending", "running", "paused", "complete_sent", "complete_delivered", "aborted" ] }, "CreateCampaignRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Display name for the campaign." }, "audienceId": { "type": "string", "minLength": 1, "description": "ID of the audience to target. Each audience contact contributes one outgoing message." }, "text": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Message body. Supports per-contact substitution using single-brace tokens like `{firstName}` or `{product}`.\nResolution rules (case-insensitive, whitespace stripped):\n - Built-ins always available: `{whatsappname}` (WA profile name), `{displayname}` (firstname+lastname fallback), `{phone}` / `{mobile}`.\n - Custom variables: every property attached to a contact via audiences.append_contacts becomes a token of the same name.\n - Unresolved tokens are left as literal `{token}` in the sent message.\nTemplates use SINGLE braces `{var}` — `{{var}}` is treated as literal text." }, "mediaUrl": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Public https URL of an image/video/document to attach." }, "mediaCaption": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "Caption for the media attachment. Requires mediaUrl." }, "onMissingVariable": { "type": "string", "enum": [ "fail", "skip" ], "description": "Behavior when a template references a variable that is not present on a contact:\n - `fail` (default): reject the request at create time; no messages are sent. Returns 400 with `data.examples` listing offending contacts.\n - `skip`: accept the campaign; contacts missing variables receive the message with literal `{token}` left in place." } }, "required": [ "name", "audienceId" ], "additionalProperties": false }, "BatchMessageAckEntry": { "type": "object", "properties": { "key": { "type": "string" }, "ack": { "type": "integer", "nullable": true, "description": "-1=error, 0=pending, 1=server, 2=device, 3=read, 4=played; null when the message has no determined ack — or when the key was not found (see `found`)." }, "found": { "type": "boolean", "description": "True when the message exists in the engine store. False when the requested key has no matching message; in that case `ack` is null by definition." } }, "required": [ "key", "ack", "found" ], "additionalProperties": false }, "BatchMessageAcksRequest": { "type": "object", "properties": { "messageKeys": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 200 }, "chatId": { "type": "string", "minLength": 1 } }, "required": [ "messageKeys" ], "additionalProperties": false }, "ChangeLabelsRequest": { "type": "object", "properties": { "labelIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 50, "description": "Full replacement set of label ids for this chat." } }, "required": [ "labelIds" ], "additionalProperties": false }, "Chat": { "type": "object", "properties": { "chatId": { "type": "string", "description": "WhatsApp JID of the chat — `@c.us` for a 1:1 contact, `@g.us` for a group, `@newsletter` for a channel." }, "name": { "type": "string", "nullable": true, "description": "Display name of the chat (contact name, group subject, or channel title). Null when WhatsApp has no name for it." }, "chatType": { "type": "string", "enum": [ "contact", "group", "newsletter" ], "description": "Kind of chat: `contact` (1:1), `group`, or `newsletter` (WhatsApp Channel). The three are mutually exclusive." }, "pinned": { "type": "boolean", "description": "True when the chat is pinned to the top of the chat list." }, "archived": { "type": "boolean", "description": "True when the chat is archived. Excluded from list responses unless `includeArchive=true`." }, "lastMessageAt": { "type": "string", "nullable": true, "format": "date-time", "description": "ISO-8601 timestamp of the most recent message in this chat. Null when the chat has no messages." }, "unreadCount": { "type": "integer", "nullable": true, "minimum": 0, "description": "Count of unseen incoming messages (>= 0). Excludes the \"manually marked unread\" sentinel — see `markedUnread`." }, "markedUnread": { "type": "boolean", "description": "True when the chat was manually flagged unread in WhatsApp (the dot badge), distinct from having N unread messages." }, "lastMessageText": { "type": "string", "nullable": true, "description": "Preview text of the most recent message. Present only when includeLastMessage=true." }, "lastMessageFromMe": { "type": "boolean", "nullable": true, "description": "True if the last message was sent by the connected account. Present only when includeLastMessage=true." } }, "required": [ "chatId", "name", "chatType", "lastMessageAt", "unreadCount", "markedUnread" ], "additionalProperties": false, "description": "A WhatsApp chat (conversation) — a 1:1 contact, a group, or a channel — as seen by the connected engine." }, "ChatId": { "type": "string", "pattern": "^\\d+(?:-\\d+)?@(?:c\\.us|s\\.whatsapp\\.net|g\\.us|lid|broadcast|newsletter)$" }, "ChatLabel": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "nullable": true }, "color": { "type": "string", "nullable": true } }, "required": [ "id", "name", "color" ], "additionalProperties": false }, "ChatMutationResult": { "type": "object", "properties": { "result": { "type": "boolean", "description": "`true` when WAWeb accepted the mutation; `false` when WAWeb refused or the feature is unavailable on this account." }, "error": { "type": "string", "description": "Set when `result === false`. The literal `wa_business_required` signals the connected account is not a WhatsApp Business account; any other value is the underlying engine diagnostic." } }, "required": [ "result" ], "additionalProperties": false }, "ChatNoteRequest": { "type": "object", "properties": { "note": { "type": "string", "maxLength": 4096, "description": "Free-text note. Empty string clears the note." } }, "required": [ "note" ], "additionalProperties": false }, "ChatRef": { "type": "object", "properties": { "chatId": { "type": "string" } }, "required": [ "chatId" ], "additionalProperties": false }, "GetChatParticipantsQuery": { "type": "object", "properties": { "searchToken": { "type": "string", "maxLength": 200, "description": "Search token; when set, only participants whose resolved name or phone/JID matches (case-insensitive substring) are returned, and `total` reflects the matched count." }, "limit": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100, "description": "Max participants to return." }, "skip": { "type": "integer", "nullable": true, "minimum": 0, "default": 0, "description": "Number of participants to skip before the page (default 0)." } }, "additionalProperties": false }, "LatestChatWithMessages": { "type": "object", "properties": { "chatId": { "type": "string", "description": "WhatsApp JID of the chat — `@c.us` for a 1:1 contact, `@g.us` for a group, `@newsletter` for a channel." }, "name": { "type": "string", "nullable": true, "description": "Display name of the chat (contact name, group subject, or channel title). Null when WhatsApp has no name for it." }, "chatType": { "type": "string", "enum": [ "contact", "group", "newsletter" ], "description": "Kind of chat: `contact` (1:1), `group`, or `newsletter` (WhatsApp Channel). The three are mutually exclusive." }, "pinned": { "type": "boolean", "description": "True when the chat is pinned to the top of the chat list." }, "archived": { "type": "boolean", "description": "True when the chat is archived. Excluded from list responses unless `includeArchive=true`." }, "lastMessageAt": { "type": "string", "nullable": true, "format": "date-time", "description": "ISO-8601 timestamp of the most recent message in this chat. Null when the chat has no messages." }, "unreadCount": { "type": "integer", "nullable": true, "minimum": 0, "description": "Count of unseen incoming messages (>= 0). Excludes the \"manually marked unread\" sentinel — see `markedUnread`." }, "markedUnread": { "type": "boolean", "description": "True when the chat was manually flagged unread in WhatsApp (the dot badge), distinct from having N unread messages." }, "lastMessageText": { "type": "string", "nullable": true, "description": "Preview text of the most recent message. Present only when includeLastMessage=true." }, "lastMessageFromMe": { "type": "boolean", "nullable": true, "description": "True if the last message was sent by the connected account. Present only when includeLastMessage=true." }, "messages": { "type": "array", "items": { "type": "object", "properties": { "waMessageKey": { "type": "object", "properties": { "fromMe": { "type": "boolean" }, "remote": { "type": "string" }, "id": { "type": "string" }, "_serialized": { "type": "string" }, "participant": { "type": "string" } }, "required": [ "fromMe" ], "additionalProperties": false }, "chatId": { "type": "string" }, "from": { "type": "string" }, "author": { "type": "string" }, "senderName": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "text": { "type": "string" }, "type": { "type": "string" }, "fromMe": { "type": "boolean" }, "ack": { "type": "integer" }, "mediaUrl": { "type": "string" }, "filename": { "type": "string" }, "linkPreview": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "canonicalUrl": { "type": "string" }, "thumbnail": { "type": "string" } } }, "quotedMessage": { "type": "object", "properties": { "waMessageKey": { "type": "object", "properties": { "fromMe": { "type": "boolean" }, "remote": { "type": "string" }, "id": { "type": "string" }, "_serialized": { "type": "string" }, "participant": { "type": "string" } }, "required": [ "fromMe" ], "additionalProperties": false }, "text": { "type": "string" }, "type": { "type": "string" }, "author": { "type": "string" } }, "required": [ "waMessageKey" ], "additionalProperties": false } }, "required": [ "waMessageKey", "chatId", "from", "type", "fromMe" ], "additionalProperties": false }, "description": "Latest messages in this chat, newest-first (up to numberOfMessages)." } }, "required": [ "chatId", "name", "chatType", "lastMessageAt", "unreadCount", "markedUnread", "messages" ], "additionalProperties": false, "description": "A WhatsApp chat with its most recent messages attached." }, "LatestChatsQuery": { "type": "object", "properties": { "numberOfChats": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Total chats to return, pinned first then most-recent (1-200, default 50)." }, "numberOfMessages": { "type": "integer", "nullable": true, "minimum": 0, "maximum": 100, "default": 20, "description": "Latest messages to include per chat, newest-first (0-100, default 20)." } }, "additionalProperties": false }, "LatestChatsResponse": { "type": "object", "properties": { "chats": { "type": "array", "items": { "type": "object", "properties": { "chatId": { "type": "string", "description": "WhatsApp JID of the chat — `@c.us` for a 1:1 contact, `@g.us` for a group, `@newsletter` for a channel." }, "name": { "type": "string", "nullable": true, "description": "Display name of the chat (contact name, group subject, or channel title). Null when WhatsApp has no name for it." }, "chatType": { "type": "string", "enum": [ "contact", "group", "newsletter" ], "description": "Kind of chat: `contact` (1:1), `group`, or `newsletter` (WhatsApp Channel). The three are mutually exclusive." }, "pinned": { "type": "boolean", "description": "True when the chat is pinned to the top of the chat list." }, "archived": { "type": "boolean", "description": "True when the chat is archived. Excluded from list responses unless `includeArchive=true`." }, "lastMessageAt": { "type": "string", "nullable": true, "format": "date-time", "description": "ISO-8601 timestamp of the most recent message in this chat. Null when the chat has no messages." }, "unreadCount": { "type": "integer", "nullable": true, "minimum": 0, "description": "Count of unseen incoming messages (>= 0). Excludes the \"manually marked unread\" sentinel — see `markedUnread`." }, "markedUnread": { "type": "boolean", "description": "True when the chat was manually flagged unread in WhatsApp (the dot badge), distinct from having N unread messages." }, "lastMessageText": { "type": "string", "nullable": true, "description": "Preview text of the most recent message. Present only when includeLastMessage=true." }, "lastMessageFromMe": { "type": "boolean", "nullable": true, "description": "True if the last message was sent by the connected account. Present only when includeLastMessage=true." }, "messages": { "type": "array", "items": { "type": "object", "properties": { "waMessageKey": { "type": "object", "properties": { "fromMe": { "type": "boolean" }, "remote": { "type": "string" }, "id": { "type": "string" }, "_serialized": { "type": "string" }, "participant": { "type": "string" } }, "required": [ "fromMe" ], "additionalProperties": false }, "chatId": { "type": "string" }, "from": { "type": "string" }, "author": { "type": "string" }, "senderName": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "text": { "type": "string" }, "type": { "type": "string" }, "fromMe": { "type": "boolean" }, "ack": { "type": "integer" }, "mediaUrl": { "type": "string" }, "filename": { "type": "string" }, "linkPreview": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "canonicalUrl": { "type": "string" }, "thumbnail": { "type": "string" } } }, "quotedMessage": { "type": "object", "properties": { "waMessageKey": { "type": "object", "properties": { "fromMe": { "type": "boolean" }, "remote": { "type": "string" }, "id": { "type": "string" }, "_serialized": { "type": "string" }, "participant": { "type": "string" } }, "required": [ "fromMe" ], "additionalProperties": false }, "text": { "type": "string" }, "type": { "type": "string" }, "author": { "type": "string" } }, "required": [ "waMessageKey" ], "additionalProperties": false } }, "required": [ "waMessageKey", "chatId", "from", "type", "fromMe" ], "additionalProperties": false }, "description": "Latest messages in this chat, newest-first (up to numberOfMessages)." } }, "required": [ "chatId", "name", "chatType", "lastMessageAt", "unreadCount", "markedUnread", "messages" ], "additionalProperties": false, "description": "A WhatsApp chat with its most recent messages attached." } }, "totalChats": { "type": "integer", "description": "Non-archived, titled chat count before the numberOfChats slice." }, "numberOfChats": { "type": "integer", "description": "Effective chats cap applied." }, "numberOfMessages": { "type": "integer", "description": "Effective per-chat messages cap applied." } }, "required": [ "chats", "totalChats", "numberOfChats", "numberOfMessages" ], "description": "Most-recent non-archived chats (pinned first), each with their latest messages." }, "ListChatsQuery": { "type": "object", "properties": { "searchToken": { "type": "string", "maxLength": 200, "description": "Search token; when set, only items whose name matches are returned." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Page size (1-200, default 50)." }, "skip": { "type": "integer", "nullable": true, "minimum": 0, "default": 0, "description": "Number of items to skip before the page (default 0)." }, "filter": { "type": "string", "enum": [ "groups", "contacts", "newsletters" ], "description": "Restrict to one chat kind." }, "kinds": { "type": "array", "items": { "type": "string", "enum": [ "contact", "group", "newsletter" ] }, "minItems": 1, "description": "Keep only these chat kinds (INCLUDE semantics). Comma-separated or repeated." }, "since": { "type": "string", "format": "date-time", "description": "Keep only chats whose last message is at/after this ISO 8601 instant (offset allowed; approximate — see sinceApplied)." }, "includeLastMessage": { "type": "boolean", "description": "Include the last message snippet on each chat row." }, "includeExtendedInfo": { "type": "boolean", "description": "Include extended chat metadata (engine-side opt-in)." }, "includeWithoutName": { "type": "boolean", "description": "Include chats with no resolved name (default: skipped)." }, "includeArchive": { "type": "boolean", "description": "Include archived chats (default false → archived excluded)." } }, "additionalProperties": false }, "LoadCoverage": { "type": "object", "properties": { "oldestLoadedTimestamp": { "type": "number", "description": "Epoch MILLISECONDS of the oldest currently-loaded message for this chat. Omitted when unknown (empty chat / probe unavailable)." }, "oldestLoadedIso": { "type": "string", "description": "ISO 8601 form of `oldestLoadedTimestamp`. Use it to verify range coverage (\"did I reach a year back?\") deterministically." } }, "additionalProperties": false }, "LoadOlderRequest": { "type": "object", "properties": { "pages": { "type": "integer", "minimum": 1, "maximum": 10, "description": "How many older pages to pull in one call (1-10, default 1). Pages are WA-paced ~2.5s apart. Stops early on exhaustion, error, or reaching `until_date`." }, "until_date": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "Stop once the oldest loaded message is at/before this date (ISO 8601 string or epoch seconds/ms). Lets you page back to a target depth deterministically." } }, "additionalProperties": false }, "LoadOlderResult": { "type": "object", "properties": { "totalMessages": { "type": "integer", "nullable": true }, "added": { "type": "integer", "nullable": true, "description": "Total messages added to the store across the pages this call executed (sum). `0` with `canLoadMore:true` is a transient hiccup worth retrying; `canLoadMore:false` means genuinely exhausted." }, "canLoadMore": { "type": "boolean", "description": "From the LAST executed page: true = the engine believes more history may still be pulled; false = genuinely exhausted (stop paging)." }, "historyUnavailable": { "type": "boolean", "description": "True when no older messages could be pulled because the phone reported it has no retrievable history for this chat (or the phone is offline). When true, `added` is 0, `canLoadMore` is false, and `error` carries the reason. This is distinct from a chat that is simply already fully synced (historyUnavailable=false, added=0)." }, "error": { "type": "string", "nullable": true, "description": "Human-readable reason older messages could not be loaded from the phone; null when the pull succeeded or the chat is already fully synced. First fatal error across the executed pages." }, "pagesExecuted": { "type": "integer", "description": "How many older pages this call actually pulled (1..pages). Fewer than requested when the loop stopped early on exhaustion, error, or reaching `until_date`." }, "coverage": { "type": "object", "properties": { "oldestLoadedTimestamp": { "type": "number", "description": "Epoch MILLISECONDS of the oldest currently-loaded message for this chat. Omitted when unknown (empty chat / probe unavailable)." }, "oldestLoadedIso": { "type": "string", "description": "ISO 8601 form of `oldestLoadedTimestamp`. Use it to verify range coverage (\"did I reach a year back?\") deterministically." } }, "additionalProperties": false, "description": "How far back the chat is now loaded. `coverage.oldestLoadedIso` is the deterministic answer to \"have I reached far enough back?\"." } }, "required": [ "totalMessages", "added", "canLoadMore", "historyUnavailable", "error", "pagesExecuted", "coverage" ], "additionalProperties": false }, "Media": { "type": "object", "properties": { "url": { "type": "string" }, "mimetype": { "type": "string" }, "filename": { "type": "string" }, "dataBase64": { "type": "string" }, "originalQuality": { "type": "boolean", "description": "Set to false when the bytes returned are NOT the original sender uploaded — i.e. WA released the original from memory and we synthesized from a smaller WA-generated preview (#113). Currently only happens for own-sent newsletter media (messages you sent to a @newsletter chat). When absent or true, the bytes are the genuine original. Consumers can use this to warn users / decide whether to retry from a different source." }, "mediaUnavailable": { "type": "string", "enum": [ "expired", "fetching", "awaiting_sender", "error", "no_media" ], "description": "Set when the bytes could not be downloaded or never existed. \"expired\" = WA aged the file out of CDN retention (typically older than ~30 days for documents) and there is nothing to retry. \"fetching\" = WA is mid-download from its CDN — transient, the server already retried for ~10s; calling again in a few seconds usually resolves to bytes. \"awaiting_sender\" = WA's CDN does not have the file but has asked the sender's device to reupload it. The reupload only completes when the sender's WhatsApp client is open and online; closed/backgrounded apps block it indefinitely. Tell the user to ask the sender to open WhatsApp; do not poll. \"error\" = unexpected failure; \"no_media\" = the message is text-only / revoked / location / vcard, i.e. it never carried media — caller should not have invoked this tool on this messageKey. Absent when bytes were not needed or when the fetch succeeded." } }, "additionalProperties": false }, "MessageAck": { "type": "object", "properties": { "ack": { "type": "integer", "nullable": true, "description": "-1=error, 0=pending, 1=server, 2=device, 3=read, 4=played; null when no engine response." } }, "required": [ "ack" ], "additionalProperties": false }, "MessageKey": { "type": "string", "minLength": 1, "maxLength": 512 }, "MessagesQuery": { "type": "object", "properties": { "order": { "type": "string", "enum": [ "asc", "desc" ], "description": "Result ordering. asc = oldest-first; desc = newest-first (default)." }, "searchToken": { "type": "string", "maxLength": 200, "description": "Search token; when set, only items whose name matches are returned." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Max messages to return." }, "skip": { "type": "integer", "nullable": true, "minimum": 0, "default": 0, "description": "Number of messages to skip before the page (default 0)." }, "since": { "type": "string", "format": "date-time", "description": "Lower bound (ISO 8601, offset allowed). Only messages with timestamp >= since." }, "until": { "type": "string", "format": "date-time", "description": "Upper bound (ISO 8601, offset allowed). Only messages with timestamp <= until." }, "messageTypes": { "type": "array", "items": { "type": "string", "enum": [ "chat", "image", "video", "document", "audio", "ptt", "sticker", "gif", "ptv", "poll_creation", "location", "vcard", "revoked" ] }, "description": "Filter to specific message kinds. Comma-separated or repeated. Useful for \"all PDFs\" (`document`) or \"images today\" (`image`). System events (gp2/revoked/newsletter_notification) are excluded by default unless explicitly listed here." }, "queryAny": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "maxItems": 24, "description": "Keyword-set OR search: match if body/caption/filename contains ANY term." }, "mime": { "type": "string", "maxLength": 255, "description": "MIME prefix filter, e.g. \"application/pdf\" or \"image/\"." }, "filenameContains": { "type": "string", "maxLength": 255, "description": "Case-insensitive substring match on the document filename." }, "hasMedia": { "type": "boolean", "description": "true = only messages with a media attachment; false = only non-media." }, "sender": { "type": "string", "maxLength": 128, "description": "Case-insensitive substring match on the sender JID/phone." }, "loadFromPhoneIfNeeded": { "type": "boolean", "description": "When the local store is exhausted, fetch older messages from the phone (chrome only)." }, "includeMediaContent": { "type": "boolean", "description": "Include inline media payload on rows (heavy; default false — use /messages/{key}/media)." }, "chatId": { "type": "string", "pattern": "^\\d+(?:-\\d+)?@(?:c\\.us|s\\.whatsapp\\.net|g\\.us|lid|broadcast|newsletter)$", "description": "Optional WhatsApp JID to scope results to a single chat. Omit to search across all chats." } }, "additionalProperties": false }, "MuteChatRequest": { "type": "object", "properties": { "unmuteAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp at which the chat auto-unmutes. Omit for \"forever\"." } }, "additionalProperties": false }, "MuteState": { "type": "object", "properties": { "isMuted": { "type": "boolean" }, "muteExpirationAt": { "type": "string", "nullable": true, "format": "date-time" } }, "required": [ "isMuted", "muteExpirationAt" ], "additionalProperties": false }, "OkResult": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": false }, "Participant": { "type": "object", "properties": { "chatId": { "type": "string", "description": "WhatsApp JID (`@c.us`) of this group participant." }, "name": { "type": "string", "nullable": true, "description": "Participant's display name, or null when the engine couldn't resolve one." }, "isAdmin": { "type": "boolean", "description": "True when this participant is a group admin." }, "isSuperAdmin": { "type": "boolean", "description": "True when this participant is the group creator / super-admin." } }, "required": [ "chatId", "isAdmin" ], "additionalProperties": false, "description": "One member of a WhatsApp group, with their admin standing." }, "PinMessageRequest": { "type": "object", "properties": { "duration": { "type": "integer", "minimum": 0, "exclusiveMinimum": true } }, "additionalProperties": false }, "PinnedMessage": { "type": "object", "properties": { "key": { "type": "string" }, "chatId": { "type": "string" }, "text": { "type": "string", "nullable": true } }, "required": [ "key", "chatId", "text" ], "additionalProperties": false }, "PublicMessage": { "type": "object", "properties": { "waMessageKey": { "type": "object", "properties": { "fromMe": { "type": "boolean" }, "remote": { "type": "string" }, "id": { "type": "string" }, "_serialized": { "type": "string" }, "participant": { "type": "string" } }, "required": [ "fromMe" ], "additionalProperties": false }, "chatId": { "type": "string" }, "from": { "type": "string" }, "author": { "type": "string" }, "senderName": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "text": { "type": "string" }, "type": { "type": "string" }, "fromMe": { "type": "boolean" }, "ack": { "type": "integer" }, "mediaUrl": { "type": "string" }, "filename": { "type": "string" }, "linkPreview": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "canonicalUrl": { "type": "string" }, "thumbnail": { "type": "string" } } }, "quotedMessage": { "type": "object", "properties": { "waMessageKey": { "type": "object", "properties": { "fromMe": { "type": "boolean" }, "remote": { "type": "string" }, "id": { "type": "string" }, "_serialized": { "type": "string" }, "participant": { "type": "string" } }, "required": [ "fromMe" ], "additionalProperties": false }, "text": { "type": "string" }, "type": { "type": "string" }, "author": { "type": "string" } }, "required": [ "waMessageKey" ], "additionalProperties": false } }, "required": [ "waMessageKey", "chatId", "from", "type", "fromMe" ], "additionalProperties": false }, "PublicQuotedMessage": { "type": "object", "properties": { "waMessageKey": { "type": "object", "properties": { "fromMe": { "type": "boolean" }, "remote": { "type": "string" }, "id": { "type": "string" }, "_serialized": { "type": "string" }, "participant": { "type": "string" } }, "required": [ "fromMe" ], "additionalProperties": false }, "text": { "type": "string" }, "type": { "type": "string" }, "author": { "type": "string" } }, "required": [ "waMessageKey" ], "additionalProperties": false }, "PublicWaMessageKey": { "type": "object", "properties": { "fromMe": { "type": "boolean" }, "remote": { "type": "string" }, "id": { "type": "string" }, "_serialized": { "type": "string" }, "participant": { "type": "string" } }, "required": [ "fromMe" ], "additionalProperties": false }, "QueryMessagesQuery": { "type": "object", "properties": { "order": { "type": "string", "enum": [ "asc", "desc" ], "description": "Result ordering. asc = oldest-first; desc = newest-first (default)." }, "searchToken": { "type": "string", "maxLength": 200, "description": "Search token; when set, only items whose name matches are returned." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Max messages to return." }, "skip": { "type": "integer", "nullable": true, "minimum": 0, "default": 0, "description": "Number of messages to skip before the page (default 0)." }, "since": { "type": "string", "format": "date-time", "description": "Lower bound (ISO 8601, offset allowed). Only messages with timestamp >= since." }, "until": { "type": "string", "format": "date-time", "description": "Upper bound (ISO 8601, offset allowed). Only messages with timestamp <= until." }, "messageTypes": { "type": "array", "items": { "type": "string", "enum": [ "chat", "image", "video", "document", "audio", "ptt", "sticker", "gif", "ptv", "poll_creation", "location", "vcard", "revoked" ] }, "description": "Filter to specific message kinds. Comma-separated or repeated. Useful for \"all PDFs\" (`document`) or \"images today\" (`image`). System events (gp2/revoked/newsletter_notification) are excluded by default unless explicitly listed here." }, "queryAny": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "maxItems": 24, "description": "Keyword-set OR search: match if body/caption/filename contains ANY term." }, "mime": { "type": "string", "maxLength": 255, "description": "MIME prefix filter, e.g. \"application/pdf\" or \"image/\"." }, "filenameContains": { "type": "string", "maxLength": 255, "description": "Case-insensitive substring match on the document filename." }, "hasMedia": { "type": "boolean", "description": "true = only messages with a media attachment; false = only non-media." }, "sender": { "type": "string", "maxLength": 128, "description": "Case-insensitive substring match on the sender JID/phone." }, "loadFromPhoneIfNeeded": { "type": "boolean", "description": "When the local store is exhausted, fetch older messages from the phone (chrome only)." }, "includeMediaContent": { "type": "boolean", "description": "Include inline media payload on rows (heavy; default false — use /messages/{key}/media)." } }, "additionalProperties": false }, "ReactRequest": { "type": "object", "properties": { "emoji": { "type": "string", "minLength": 0, "maxLength": 32 } }, "required": [ "emoji" ], "additionalProperties": false }, "UnifiedSearchQuery": { "type": "object", "properties": { "searchToken": { "type": "string", "maxLength": 200, "description": "Search token matched against contact and chat names." }, "types": { "type": "array", "items": { "type": "string", "enum": [ "contacts", "chats", "newsletters" ] }, "description": "Restrict results to these kinds. Comma-separated or repeated. Default: all." } }, "additionalProperties": false }, "EngineListResponse": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable id of this engine session (its MQTT presence client id). Same id space as ping's whatsapp_connections[].id." }, "type": { "type": "string", "enum": [ "gateway", "regular" ], "description": "Engine kind. \"gateway\" = a remote, server-side engine (Blueticks 24/7 gateway / baileys pod). \"regular\" = the user's own WhatsApp Web browser extension." }, "connected": { "type": "boolean", "description": "Whether this engine is currently online and serving requests." }, "state": { "type": "string", "nullable": true, "description": "Engine-side connection state (e.g. CONNECTED, OPENING, PAIRING). Null when unknown." }, "stream": { "type": "string", "nullable": true, "description": "Underlying WA stream state. Null when unknown." }, "hasSynced": { "type": "boolean", "nullable": true, "description": "Whether the engine has completed its initial history sync." } }, "required": [ "id", "type", "connected", "state", "stream", "hasSynced" ], "additionalProperties": false }, "description": "Engines connected to this workspace. Empty when no engine is paired." }, "EngineStatus": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable id of this engine session (its MQTT presence client id). Same id space as ping's whatsapp_connections[].id." }, "type": { "type": "string", "enum": [ "gateway", "regular" ], "description": "Engine kind. \"gateway\" = a remote, server-side engine (Blueticks 24/7 gateway / baileys pod). \"regular\" = the user's own WhatsApp Web browser extension." }, "connected": { "type": "boolean", "description": "Whether this engine is currently online and serving requests." }, "state": { "type": "string", "nullable": true, "description": "Engine-side connection state (e.g. CONNECTED, OPENING, PAIRING). Null when unknown." }, "stream": { "type": "string", "nullable": true, "description": "Underlying WA stream state. Null when unknown." }, "hasSynced": { "type": "boolean", "nullable": true, "description": "Whether the engine has completed its initial history sync." } }, "required": [ "id", "type", "connected", "state", "stream", "hasSynced" ], "additionalProperties": false }, "AddMemberRequest": { "type": "object", "properties": { "chatId": { "type": "string" }, "participants": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 256 } }, "additionalProperties": false }, "CreateGroupRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "participants": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 256 } }, "required": [ "name", "participants" ], "additionalProperties": false }, "GetGroupQuery": { "type": "object", "properties": { "include": { "type": "string", "enum": [ "participants" ], "description": "Set to `participants` to inline the group members array on the response. Omit to leave `participants` null." } }, "additionalProperties": false }, "Group": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "owner": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "nullable": true, "format": "date-time" }, "lastMessageAt": { "type": "string", "nullable": true, "format": "date-time" }, "participantCount": { "type": "integer", "nullable": true, "minimum": 0 }, "announce": { "type": "boolean", "nullable": true }, "restrict": { "type": "boolean", "nullable": true }, "participants": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "chatId": { "type": "string" }, "isAdmin": { "type": "boolean" }, "isSuperAdmin": { "type": "boolean" }, "name": { "type": "string", "nullable": true } }, "required": [ "chatId", "isAdmin", "isSuperAdmin", "name" ], "additionalProperties": false } } }, "required": [ "id", "name", "description", "owner", "createdAt", "lastMessageAt", "participantCount", "announce", "restrict", "participants" ], "additionalProperties": false }, "GroupId": { "type": "string", "pattern": "^\\d+(?:-\\d+)?@g\\.us$" }, "GroupListItem": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "owner": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "nullable": true, "format": "date-time" }, "lastMessageAt": { "type": "string", "nullable": true, "format": "date-time" }, "participantCount": { "type": "integer", "nullable": true, "minimum": 0 }, "restrict": { "type": "boolean", "nullable": true } }, "required": [ "id", "name", "description", "owner", "createdAt", "lastMessageAt", "participantCount", "restrict" ], "additionalProperties": false }, "GroupParticipant": { "type": "object", "properties": { "chatId": { "type": "string" }, "isAdmin": { "type": "boolean" }, "isSuperAdmin": { "type": "boolean" }, "name": { "type": "string", "nullable": true } }, "required": [ "chatId", "isAdmin", "isSuperAdmin", "name" ], "additionalProperties": false }, "ListGroupsQuery": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Page size (1-200, default 50)." }, "skip": { "type": "integer", "nullable": true, "minimum": 0, "default": 0, "description": "Number of items to skip before the page (default 0)." }, "searchToken": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Search token; when set, only items whose name matches are returned." }, "includeArchive": { "type": "boolean", "description": "Include archived groups (default false → archived excluded)." } }, "additionalProperties": false }, "MemberChatId": { "type": "string" }, "SetPictureRequest": { "type": "object", "properties": { "fileDataUrl": { "type": "string", "minLength": 1, "maxLength": 20971520 }, "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "fileName": { "type": "string", "maxLength": 255 }, "fileMimeType": { "type": "string", "maxLength": 127 } }, "additionalProperties": false }, "UpdateGroupRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "settings": { "type": "object", "properties": { "announce": { "type": "boolean" }, "restrict": { "type": "boolean" }, "editInfoAdminsOnly": { "type": "boolean" }, "description": { "type": "string", "minLength": 1, "maxLength": 2048 } }, "additionalProperties": false } }, "additionalProperties": false }, "Error": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always `false` on error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable error code (e.g. `invalid_request`, `authentication_required`, `not_found`, `rate_limited`, `internal_error`)." }, "message": { "type": "string", "description": "Human-readable description of what went wrong." }, "requestId": { "type": "string", "nullable": true, "description": "Server-assigned request id; pass this when filing support tickets so engineering can trace the failure." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "Dotted path to the offending field within the request body." }, "code": { "type": "string", "description": "Zod-derived issue code (e.g. `invalid_type`, `too_small`)." }, "message": { "type": "string", "description": "Human-readable validation message." } }, "required": [ "path", "code", "message" ], "additionalProperties": false }, "description": "Per-field validation issues. Present on 400/422 when the request body failed Zod parsing." } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Standard error response envelope. Every 4xx/5xx response from the v1 API carries this exact shape." }, "ErrorEnvelope": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Always `false` on error responses." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable error code (e.g. `invalid_request`, `authentication_required`, `not_found`, `rate_limited`, `internal_error`)." }, "message": { "type": "string", "description": "Human-readable description of what went wrong." }, "requestId": { "type": "string", "nullable": true, "description": "Server-assigned request id; pass this when filing support tickets so engineering can trace the failure." }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "Dotted path to the offending field within the request body." }, "code": { "type": "string", "description": "Zod-derived issue code (e.g. `invalid_type`, `too_small`)." }, "message": { "type": "string", "description": "Human-readable validation message." } }, "required": [ "path", "code", "message" ], "additionalProperties": false }, "description": "Per-field validation issues. Present on 400/422 when the request body failed Zod parsing." } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "success", "error" ], "additionalProperties": false, "description": "Standard error response envelope. Every 4xx/5xx response from the v1 API carries this exact shape." }, "ValidationDetail": { "type": "object", "properties": { "path": { "type": "string", "description": "Dotted path to the offending field within the request body." }, "code": { "type": "string", "description": "Zod-derived issue code (e.g. `invalid_type`, `too_small`)." }, "message": { "type": "string", "description": "Human-readable validation message." } }, "required": [ "path", "code", "message" ], "additionalProperties": false }, "PaginatedResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": {} }, "description": "Page of items; the item shape is endpoint-specific." }, "limit": { "type": "integer", "description": "Page size echoed back from the request." }, "skip": { "type": "integer", "description": "Offset echoed back from the request." }, "total": { "type": "integer", "description": "Total number of items matching the query, across all pages." } }, "required": [ "data", "limit", "skip", "total" ], "additionalProperties": false, "description": "Offset-paginated response envelope. Every v1 list endpoint returns this shape (inside the `success`/`data` wrapper)." }, "CreateNewsletterRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 2048 } }, "required": [ "name" ], "additionalProperties": false }, "ListNewslettersQuery": { "type": "object", "properties": { "searchToken": { "type": "string", "maxLength": 200, "description": "Search token; when set, only newsletters whose name matches (case-insensitive substring) are returned, and `total` reflects the matched count." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Page size (1-200, default 50)." }, "skip": { "type": "integer", "nullable": true, "minimum": 0, "default": 0, "description": "Number of items to skip before the page (default 0)." }, "includeArchive": { "type": "boolean", "description": "Include archived newsletters (default false → archived excluded)." } } }, "NewsletterId": { "type": "string", "pattern": "^\\d+@newsletter$", "description": "Newsletter JID, e.g. 12345@newsletter." }, "NewsletterListItem": { "type": "object", "properties": { "chatId": { "type": "string", "description": "Newsletter JID, e.g. 120363201733549020@newsletter." }, "name": { "type": "string", "description": "Display name of the newsletter / WhatsApp channel." }, "description": { "type": "string", "nullable": true, "description": "Optional description." }, "createdAt": { "type": "string", "nullable": true, "format": "date-time" }, "subscribers": { "type": "integer", "nullable": true, "minimum": 0 }, "invite": { "type": "string", "nullable": true, "description": "Invite code (suffix of https://whatsapp.com/channel/)." }, "verification": { "type": "string", "nullable": true, "enum": [ "VERIFIED", "UNVERIFIED" ] } }, "required": [ "chatId", "name", "description", "createdAt", "subscribers", "invite", "verification" ], "additionalProperties": false }, "NewsletterResponse": { "type": "object", "properties": { "newsletterId": { "type": "string", "description": "Newsletter JID, e.g. 120363201733549020@newsletter." }, "name": { "type": "string", "description": "Display name of the newsletter / WhatsApp channel." }, "description": { "type": "string", "nullable": true, "description": "Optional description." }, "createdAt": { "type": "string", "nullable": true, "format": "date-time" }, "subscribers": { "type": "integer", "nullable": true, "minimum": 0 }, "invite": { "type": "string", "nullable": true, "description": "Invite code (suffix of https://whatsapp.com/channel/)." }, "verification": { "type": "string", "nullable": true, "enum": [ "VERIFIED", "UNVERIFIED" ] } }, "required": [ "newsletterId", "name", "description", "createdAt", "subscribers", "invite", "verification" ], "additionalProperties": false }, "PingConnection": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable id of the live engine session (its MQTT presence client id)." }, "type": { "type": "string", "enum": [ "gateway", "regular" ], "description": "Engine kind. \"gateway\" = a remote, server-side engine (Blueticks 24/7 gateway / baileys pod). \"regular\" = the user's own WhatsApp Web browser extension." }, "connected": { "type": "boolean", "enum": [ true ], "description": "Always true — an entry appears only while its presence heartbeat is live." } }, "required": [ "id", "type", "connected" ], "additionalProperties": false }, "PingResponse": { "type": "object", "properties": { "api": { "type": "string", "enum": [ "ok" ], "description": "Blueticks API server liveness. \"ok\" means the API server is up and served this request." }, "accountId": { "type": "string", "description": "The account (workspace) the API key belongs to." }, "whatsappConnections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable id of the live engine session (its MQTT presence client id)." }, "type": { "type": "string", "enum": [ "gateway", "regular" ], "description": "Engine kind. \"gateway\" = a remote, server-side engine (Blueticks 24/7 gateway / baileys pod). \"regular\" = the user's own WhatsApp Web browser extension." }, "connected": { "type": "boolean", "enum": [ true ], "description": "Always true — an entry appears only while its presence heartbeat is live." } }, "required": [ "id", "type", "connected" ], "additionalProperties": false }, "description": "WhatsApp engines currently connected for this account. Empty means no WhatsApp is connected." }, "message": { "type": "string", "description": "Present only when whatsappConnections is empty; explains the empty state." } }, "required": [ "api", "accountId", "whatsappConnections" ], "additionalProperties": false }, "DeletedMessageResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Id of the deleted message." }, "deleted": { "type": "boolean", "enum": [ true ], "description": "Always true on a successful delete." } }, "required": [ "id", "deleted" ], "additionalProperties": false }, "LinkPreviewResponse": { "type": "object", "properties": { "title": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "canonicalUrl": { "type": "string", "nullable": true }, "thumbnail": { "type": "string", "nullable": true } }, "required": [ "title", "description", "canonicalUrl", "thumbnail" ], "additionalProperties": false }, "ListMessagesQuery": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Page size (1-200, default 50)." }, "skip": { "type": "integer", "nullable": true, "minimum": 0, "default": 0, "description": "Number of items to skip before the page (default 0)." }, "chatId": { "type": "string", "pattern": "^[0-9]+(?:-[0-9]+)?@(?:c\\.us|g\\.us|newsletter)$", "description": "Filter to messages addressed to this WhatsApp JID. Matches the recipient stored on the queued/scheduled doc — for sends to a phone number, the JID is `@c.us`." }, "status": { "type": "string", "enum": [ "pending", "before-wa-send", "bt-sent", "sending", "sent", "sent_pending_ack", "confirmed", "delivered", "received", "read", "played", "cancelled", "error", "failed", "expired" ], "description": "Filter by lifecycle status: `pending` (accepted, waiting), `confirmed` (WhatsApp accepted — has waMessageKey), `received` (double grey tick), `read` (double blue tick), `played` (voice played), `failed`." }, "searchToken": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Search token; when set, only items whose name matches are returned." }, "order": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction by timestamp: `asc` (oldest first) or `desc` (newest first, default)." } }, "additionalProperties": false }, "MediaKind": { "type": "string", "enum": [ "image", "video", "audio", "document", "sticker", "voice", "gif" ] }, "MessageId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "MessageResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Primary handle for the message. Scheduled sends: the queue id (accepted by GET/cancel /v1/scheduled-messages/{id}). Direct sends: the serialized WhatsApp message key (== waMessageKey._serialized), accepted by GET /v1/messages/{id}." }, "waMessageKey": { "type": "object", "nullable": true, "properties": { "fromMe": { "type": "boolean" }, "remote": { "type": "string" }, "id": { "type": "string" }, "_serialized": { "type": "string" }, "participant": { "type": "string" } }, "required": [ "fromMe" ], "additionalProperties": false }, "to": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "media", "poll" ], "description": "Message kind that was sent." }, "text": { "type": "string", "nullable": true }, "mediaUrl": { "type": "string", "nullable": true }, "mediaKind": { "type": "string", "nullable": true, "enum": [ "image", "video", "audio", "document", "sticker", "voice", "gif" ] }, "pollQuestion": { "type": "string", "nullable": true }, "pollOptions": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Poll option labels in order (type=poll). Null for non-poll messages." }, "pollAllowMultiple": { "type": "boolean", "nullable": true, "description": "Whether the poll accepts multiple selections (type=poll). Null for non-poll messages." }, "status": { "type": "string", "enum": [ "pending", "before-wa-send", "bt-sent", "sending", "sent", "sent_pending_ack", "confirmed", "delivered", "received", "read", "played", "cancelled", "error", "failed", "expired" ] }, "sendAt": { "type": "string", "nullable": true, "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "confirmedAt": { "type": "string", "nullable": true, "format": "date-time" }, "receivedAt": { "type": "string", "nullable": true, "format": "date-time" }, "readAt": { "type": "string", "nullable": true, "format": "date-time" }, "playedAt": { "type": "string", "nullable": true, "format": "date-time" }, "failedAt": { "type": "string", "nullable": true, "format": "date-time" }, "failureReason": { "type": "string", "nullable": true }, "secret": { "type": "string", "nullable": true, "description": "Opaque correlation token carried on the message. Echoes the `secret` you sent (or the engine-encoded internal id when you omitted it), and is carried into WhatsApp's `messageSecret`. Null until a queued/scheduled send dispatches." }, "linkPreview": { "type": "object", "nullable": true, "properties": { "title": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "canonicalUrl": { "type": "string", "nullable": true }, "thumbnail": { "type": "string", "nullable": true } }, "required": [ "title", "description", "canonicalUrl", "thumbnail" ], "additionalProperties": false } }, "required": [ "waMessageKey", "to", "type", "text", "mediaUrl", "mediaKind", "pollQuestion", "pollOptions", "pollAllowMultiple", "status", "sendAt", "createdAt", "confirmedAt", "receivedAt", "readAt", "playedAt", "failedAt", "failureReason", "secret" ], "additionalProperties": false }, "MessageStatus": { "type": "string", "enum": [ "pending", "before-wa-send", "bt-sent", "sending", "sent", "sent_pending_ack", "confirmed", "delivered", "received", "read", "played", "cancelled", "error", "failed", "expired" ] }, "PatchMessageRequest": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text", "media", "poll" ] }, "text": { "type": "string", "maxLength": 4096, "description": "Text body (required for type=text) or optional media caption (type=media). Up to 4096 chars. Mention a contact inline with `@[Display Name]()`, e.g. `Hi @[Jon Daw](xxxxxxxxxxxx@c.us)`." }, "mediaUrl": { "type": "string", "maxLength": 2048, "description": "Media source URL (https only). One of mediaUrl or mediaBase64 is required for media sends; mediaUrl wins when both are present." }, "mediaBase64": { "type": "string", "maxLength": 15728640, "description": "Raw media bytes, base64-encoded (or a data: URL). Used when mediaUrl is absent. For a file upload, send multipart/form-data with a `mediaFile` part instead — it is converted to this." }, "mediaKind": { "type": "string", "enum": [ "image", "video", "audio", "document", "sticker", "voice", "gif" ], "description": "Media kind (image · video · audio · document · sticker · voice · gif). Optional — auto-detected from the URL / content-type when omitted." }, "mediaFilename": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Filename shown on the attachment (type=media). Optional — derived from the URL / uploaded file when omitted." }, "sendAt": { "type": "string", "format": "date-time" }, "replyTo": { "type": "string", "maxLength": 256, "description": "Wire `key` of a prior message to quote-reply (from MessageResponse.key). Empty string = no reply." }, "secret": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Opaque correlation token you choose to tag this message with. It is stored on the message and carried into WhatsApp's `messageSecret`, so you can match it back to your own records later. NOT a deduplication key: sending the same `secret` twice creates two separate messages. To make retries safe (at-most-once send), use the `Idempotency-Key` header instead. When omitted, the API encodes the internal message id here for delivery-status matching — only set this if you have your own correlation scheme." }, "pollQuestion": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Poll question (type=poll). Required for poll sends." }, "pollAllowMultiple": { "type": "boolean", "description": "Allow selecting multiple poll options (type=poll). Default false." }, "pollOptions": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": "Poll options (type=poll). 2–12 items." } }, "additionalProperties": false }, "PhoneOrChatId": { "type": "string", "description": "Recipient. Either an international phone number in E.164 format (e.g. +15551234567) for a 1:1 chat, or a WhatsApp chat id: `@g.us` for a group, `@newsletter` for a channel / newsletter, or `@c.us` for an individual." }, "SendInChatRequest": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text", "media", "poll" ] }, "replyTo": { "type": "string", "maxLength": 256, "description": "Wire `key` of a prior message to quote-reply (from MessageResponse.key). Empty string = no reply." }, "text": { "type": "string", "maxLength": 4096, "description": "Text body (required for type=text) or optional media caption (type=media). Up to 4096 chars. Mention a contact inline with `@[Display Name]()`, e.g. `Hi @[Jon Daw](xxxxxxxxxxxx@c.us)`." }, "mediaUrl": { "type": "string", "maxLength": 2048, "description": "Media source URL (https only). One of mediaUrl or mediaBase64 is required for media sends; mediaUrl wins when both are present." }, "mediaBase64": { "type": "string", "maxLength": 15728640, "description": "Raw media bytes, base64-encoded (or a data: URL). Used when mediaUrl is absent. For a file upload, send multipart/form-data with a `mediaFile` part instead — it is converted to this." }, "mediaKind": { "type": "string", "enum": [ "image", "video", "audio", "document", "sticker", "voice", "gif" ], "description": "Media kind (image · video · audio · document · sticker · voice · gif). Optional — auto-detected from the URL / content-type when omitted." }, "mediaFilename": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Filename shown on the attachment (type=media). Optional — derived from the URL / uploaded file when omitted." }, "pollQuestion": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Poll question (type=poll). Required for poll sends." }, "pollOptions": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": "Poll options (type=poll). 2–12 items." }, "pollAllowMultiple": { "type": "boolean", "description": "Allow selecting multiple poll options (type=poll). Default false." }, "secret": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Opaque correlation token you choose to tag this message with. It is stored on the message and carried into WhatsApp's `messageSecret`, so you can match it back to your own records later. NOT a deduplication key: sending the same `secret` twice creates two separate messages. To make retries safe (at-most-once send), use the `Idempotency-Key` header instead. When omitted, the API encodes the internal message id here for delivery-status matching — only set this if you have your own correlation scheme." }, "withTyping": { "type": "boolean", "description": "Briefly show the \"typing…\" indicator before sending a text message. Default true. Ignored for media/poll sends." }, "typingSeconds": { "type": "number", "minimum": 0, "maximum": 25, "description": "Extra typing duration in seconds, added on top of the built-in 0.4–0.8s random jitter. Default 0. Capped at 25s (WhatsApp clears the indicator after ~25s)." } }, "required": [ "type" ], "additionalProperties": false }, "SendMessageRequest": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text", "media", "poll" ] }, "replyTo": { "type": "string", "maxLength": 256, "description": "Wire `key` of a prior message to quote-reply (from MessageResponse.key). Empty string = no reply." }, "text": { "type": "string", "maxLength": 4096, "description": "Text body (required for type=text) or optional media caption (type=media). Up to 4096 chars. Mention a contact inline with `@[Display Name]()`, e.g. `Hi @[Jon Daw](xxxxxxxxxxxx@c.us)`." }, "mediaUrl": { "type": "string", "maxLength": 2048, "description": "Media source URL (https only). One of mediaUrl or mediaBase64 is required for media sends; mediaUrl wins when both are present." }, "mediaBase64": { "type": "string", "maxLength": 15728640, "description": "Raw media bytes, base64-encoded (or a data: URL). Used when mediaUrl is absent. For a file upload, send multipart/form-data with a `mediaFile` part instead — it is converted to this." }, "mediaKind": { "type": "string", "enum": [ "image", "video", "audio", "document", "sticker", "voice", "gif" ], "description": "Media kind (image · video · audio · document · sticker · voice · gif). Optional — auto-detected from the URL / content-type when omitted." }, "mediaFilename": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Filename shown on the attachment (type=media). Optional — derived from the URL / uploaded file when omitted." }, "pollQuestion": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Poll question (type=poll). Required for poll sends." }, "pollOptions": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": "Poll options (type=poll). 2–12 items." }, "pollAllowMultiple": { "type": "boolean", "description": "Allow selecting multiple poll options (type=poll). Default false." }, "secret": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Opaque correlation token you choose to tag this message with. It is stored on the message and carried into WhatsApp's `messageSecret`, so you can match it back to your own records later. NOT a deduplication key: sending the same `secret` twice creates two separate messages. To make retries safe (at-most-once send), use the `Idempotency-Key` header instead. When omitted, the API encodes the internal message id here for delivery-status matching — only set this if you have your own correlation scheme." }, "sendAt": { "type": "string", "format": "date-time" } }, "required": [ "type" ], "additionalProperties": false }, "AccountUsageResponse": { "type": "object", "properties": { "creditsLeft": { "type": "number", "description": "Remaining generation credits on the connected Suno account." }, "monthlyLimit": { "type": "number", "nullable": true, "description": "Monthly credit allowance, if known." }, "monthlyUsage": { "type": "number", "nullable": true, "description": "Credits used this month, if known." }, "plan": { "type": "string", "nullable": true, "description": "Suno plan name (e.g. \"Pro Plan\")." } }, "required": [ "creditsLeft", "monthlyLimit", "monthlyUsage", "plan" ] }, "CreateUploadRequest": { "type": "object", "properties": { "audioUrl": { "type": "string", "format": "uri", "description": "Public URL of the reference audio to fetch and upload. Provide this OR `audioBase64` (or send multipart file)." }, "audioBase64": { "type": "string", "description": "Base64-encoded audio bytes. Provide this OR `audioUrl` (or send multipart file)." }, "fileName": { "type": "string", "maxLength": 200, "description": "Original file name, used for the extension (defaults to \"audio.mp3\")." } } }, "CreateUploadResponse": { "type": "object", "properties": { "uploadId": { "type": "string", "description": "Pass as `uploadId` to POST /v1/suno/songs to cover/transform this audio." }, "status": { "type": "string", "description": "Upload processing status (e.g. \"complete\")." } }, "required": [ "uploadId", "status" ] }, "GenerateSongRequest": { "type": "object", "properties": { "lyrics": { "type": "string", "minLength": 1, "maxLength": 5000, "description": "The song lyrics. Maps to Suno `prompt`. Ignored when `instrumental` is true." }, "style": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Style / genre text, e.g. \"pop ballad, acoustic guitar\". Maps to Suno `tags`." }, "negativeStyle": { "type": "string", "maxLength": 1000, "description": "Styles to steer away from. Maps to Suno `negative_tags`." }, "vocalGender": { "type": "string", "enum": [ "m", "f" ], "description": "Preferred vocal gender: \"m\" (male) or \"f\" (female). Omit to let Suno decide." }, "weirdness": { "type": "number", "minimum": 0, "maximum": 1, "description": "Creative deviation 0–1 (Suno \"Weirdness\"). Maps to `control_sliders.weirdness_constraint`." }, "styleInfluence": { "type": "number", "minimum": 0, "maximum": 1, "description": "How strongly the style is applied, 0–1 (Suno \"Style Influence\"). Maps to `control_sliders.style_weight`." }, "audioInfluence": { "type": "number", "minimum": 0, "maximum": 1, "description": "How closely a cover follows the reference recording, 0–1 (Suno \"Audio Influence\"). Only meaningful when `uploadId` is set. Maps to `control_sliders.audio_weight`." }, "instrumental": { "type": "boolean", "description": "Generate without vocals. Maps to Suno `make_instrumental`." }, "model": { "type": "string", "description": "Model version, e.g. \"v5.5\" or \"v4\". Defaults to v5.5. Mapped to Suno `mv`." }, "title": { "type": "string", "maxLength": 200, "description": "Optional song title." }, "uploadId": { "type": "string", "description": "Reference-audio id from POST /v1/suno/uploads, to cover/transform your own recording." }, "captchaToken": { "type": "string", "description": "Cloudflare Turnstile token for cover generations (when `uploadId` is set) — Suno gates upload/voice-clone generations behind a captcha. Not needed for plain text→song. Optional here: if omitted and the server has a solver configured (SUNO_CAPTCHA_PROVIDER + key), the token is minted automatically. Supply your own (minted by a real browser) to skip the solver." } }, "required": [ "lyrics", "style" ] }, "GenerateSongResponse": { "type": "object", "properties": { "jobId": { "type": "string", "description": "Batch id for this generation request." }, "clips": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Clip id — poll GET /v1/suno/songs/{id} for progress." }, "status": { "type": "string", "enum": [ "submitted", "queued", "running", "streaming", "complete", "error" ], "description": "Generation status. Terminal states: \"complete\" or \"error\"." }, "audioUrl": { "type": "string", "nullable": true, "description": "MP3 URL once complete, else null." }, "imageUrl": { "type": "string", "nullable": true, "description": "Cover-art URL once available, else null." }, "title": { "type": "string", "nullable": true, "description": "Resolved song title, if any." }, "durationSec": { "type": "number", "nullable": true, "description": "Audio duration in seconds once complete, else null." }, "model": { "type": "string", "nullable": true, "description": "Model version that produced the clip (e.g. \"v5.5\")." }, "errorType": { "type": "string", "nullable": true, "description": "Failure class when status is \"error\" (e.g. \"moderation_failure\"). Omitted otherwise." }, "errorMessage": { "type": "string", "nullable": true, "description": "Human-readable reason a clip failed (e.g. \"Your lyrics contain copyrighted material\"). Only set when status is \"error\"." } }, "required": [ "id", "status", "audioUrl", "imageUrl", "title", "durationSec", "model" ] }, "description": "The generated song variants (typically two). Poll each by id." } }, "required": [ "jobId", "clips" ] }, "GetSongResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Clip id — poll GET /v1/suno/songs/{id} for progress." }, "status": { "type": "string", "enum": [ "submitted", "queued", "running", "streaming", "complete", "error" ], "description": "Generation status. Terminal states: \"complete\" or \"error\"." }, "audioUrl": { "type": "string", "nullable": true, "description": "MP3 URL once complete, else null." }, "imageUrl": { "type": "string", "nullable": true, "description": "Cover-art URL once available, else null." }, "title": { "type": "string", "nullable": true, "description": "Resolved song title, if any." }, "durationSec": { "type": "number", "nullable": true, "description": "Audio duration in seconds once complete, else null." }, "model": { "type": "string", "nullable": true, "description": "Model version that produced the clip (e.g. \"v5.5\")." }, "errorType": { "type": "string", "nullable": true, "description": "Failure class when status is \"error\" (e.g. \"moderation_failure\"). Omitted otherwise." }, "errorMessage": { "type": "string", "nullable": true, "description": "Human-readable reason a clip failed (e.g. \"Your lyrics contain copyrighted material\"). Only set when status is \"error\"." } }, "required": [ "id", "status", "audioUrl", "imageUrl", "title", "durationSec", "model" ] }, "SongClip": { "type": "object", "properties": { "id": { "type": "string", "description": "Clip id — poll GET /v1/suno/songs/{id} for progress." }, "status": { "type": "string", "enum": [ "submitted", "queued", "running", "streaming", "complete", "error" ], "description": "Generation status. Terminal states: \"complete\" or \"error\"." }, "audioUrl": { "type": "string", "nullable": true, "description": "MP3 URL once complete, else null." }, "imageUrl": { "type": "string", "nullable": true, "description": "Cover-art URL once available, else null." }, "title": { "type": "string", "nullable": true, "description": "Resolved song title, if any." }, "durationSec": { "type": "number", "nullable": true, "description": "Audio duration in seconds once complete, else null." }, "model": { "type": "string", "nullable": true, "description": "Model version that produced the clip (e.g. \"v5.5\")." }, "errorType": { "type": "string", "nullable": true, "description": "Failure class when status is \"error\" (e.g. \"moderation_failure\"). Omitted otherwise." }, "errorMessage": { "type": "string", "nullable": true, "description": "Human-readable reason a clip failed (e.g. \"Your lyrics contain copyrighted material\"). Only set when status is \"error\"." } }, "required": [ "id", "status", "audioUrl", "imageUrl", "title", "durationSec", "model" ] }, "CreateWebhookRequest": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "message.queued", "message.sending", "message.delivered", "message.failed", "message.read", "session.connected", "session.disconnected", "campaign.started", "campaign.paused", "campaign.resumed", "campaign.completed", "campaign.aborted", "new_message_received_webhook", "message_reaction_webhook", "ack_changed_webhook", "participant_joined_via_link_webhook", "participant_added_by_admin_webhook", "participant_left_group_webhook", "participant_kicked_from_group_webhook", "group_admin_changed_webhook", "group_name_changed_webhook", "group_description_changed_webhook", "group_message_pinned_webhook", "poll_vote_webhook", "reply_to_my_message_webhook", "message_deleted_revoked_webhook", "message_edited_webhook" ] }, "minItems": 1 }, "description": { "type": "string", "maxLength": 120 } }, "required": [ "url", "events" ], "additionalProperties": false }, "UpdateWebhookRequest": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "message.queued", "message.sending", "message.delivered", "message.failed", "message.read", "session.connected", "session.disconnected", "campaign.started", "campaign.paused", "campaign.resumed", "campaign.completed", "campaign.aborted", "new_message_received_webhook", "message_reaction_webhook", "ack_changed_webhook", "participant_joined_via_link_webhook", "participant_added_by_admin_webhook", "participant_left_group_webhook", "participant_kicked_from_group_webhook", "group_admin_changed_webhook", "group_name_changed_webhook", "group_description_changed_webhook", "group_message_pinned_webhook", "poll_vote_webhook", "reply_to_my_message_webhook", "message_deleted_revoked_webhook", "message_edited_webhook" ] }, "minItems": 1 }, "description": { "type": "string", "nullable": true, "maxLength": 120 }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] } }, "additionalProperties": false }, "WebhookResponse": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "url", "events", "description", "status", "createdAt" ], "additionalProperties": false } } } }