Host your own server (to process incoming messages).
Set its URL as the webhook via the [webhook](#Webhook) API call.
Phone number format:
Required: Country code (e.g. 5491155553934 for Argentina
Do not prefix with a plus sign (+), as natively whatsapp requires no plus sign prefix.
Global Dispatcher Flags & API Echo
Configure tenant-level skips for the shared dispatcher via /session/globaltransports/config and toggle Info.IsFromAPI emission through /session/echo/api. Both flows are surfaced in the dashboard and Postman collection.
π Calls β LLM build guide
Building a WhatsApp voice or video call integration? Open llm.txt β a complete, self-contained spec you can paste into any LLM (Claude, GPT, Gemini, β¦) to generate a perfect calls integration (REST control + bidirectional PCM audio over WebSocket + bidirectional H.264 video over WebSocket + passkey pairing appendix). It also surfaces as the external-docs link on the Call tag below.
π± Native mobile egress β operator and LLM guides
Provision a fail-closed, TCP-only Tailscale exit route per session with POST /session/network-route, inspect it with GET /session/network-route, and β when a route cannot converge and is holding the session offline β remove it with DELETE /session/network-route, an explicit operator action that returns the session to legacy proxy or direct egress. Read the operator guide or paste network-route-llm.txt into an LLM for the complete integration contract. Auth keys are write-only and must never be persisted, returned, or logged.
π Connector β embeddable pairing widget
Embed WhatsApp pairing (QR, phone code, or passkey) in any app with one <script> β without ever exposing the real instance token to the browser. Your backend mints a short-lived ephemeral token via POST /session/connector/token; the browser runs ZZ.connector.open({ token }) against the Connector tag's /connector/* routes. Paste-into-any-LLM guide: connector-llm.txt. Full docs hub for API users & LLMs: /docs.
"
version: "2.0.0" # x-release-please-version
termsOfService: ""
externalDocs:
description: "π Calls API β paste-into-any-LLM build guide for voice, video and passkey pairing (llm.txt)"
url: /api/llm.txt
schemes:
- http
servers:
- url: "/"
description: Current host
tags:
- name: Admin
description: Administrative operations for managing users and user accounts
- name: Admin Global
description: Global system configurations including RabbitMQ, S3, and webhook settings
- name: Admin DLQ
description: Dead Letter Queue management for failed event processing and retry operations
- name: Admin Event Archive
description: Event Archive management for viewing and managing all archived events (DLQ and Success). Monitor delivery metrics, replay failed events, and maintain archive hygiene.
- name: Admin Monitoring
description: Real-time event monitoring, SSE streaming, and telemetry insights for administrators
- name: Admin License
description: License management and information for monitoring subscription status and features
- name: System
description: System health monitoring, metrics, and application information
- name: Webhook
description: Webhook configuration and event subscription management
- name: Session
description: Session management, authentication, QR code generation, and connection handling
- name: Session Network Route
description: "Fail-closed per-session mobile TCP egress through an isolated native tsnet node. Auth keys are write-only, single-use enrollment credentials and are never persisted or returned. Full operator guide: network-route.md. Paste-into-any-LLM implementation guide: network-route-llm.txt."
externalDocs:
description: Native mobile egress implementation guide for operators and LLMs
url: /api/network-route-llm.txt
- name: Connector
description: 'Embeddable Connector widget β mint short-lived ephemeral tokens and drive pairing (QR, phone code, passkey) from a browser without ever exposing the real instance token. Full guide: connector-llm.txt (paste into any LLM) and /docs/connector.md.'
- name: Session S3
description: Per-user S3 storage configuration for media delivery and retention
- name: Session RabbitMQ
description: Per-user RabbitMQ configuration for event publishing and queue management
- name: Session Skips
description: Per-user skip media download, groups, newsletters, broadcasts, own messages, and calls configuration
- name: Session Global Transports
description: Manage per-transport skip flags that control how the global dispatcher enriches events (webhook, RabbitMQ, SQS, Redis, WebSocket, and S3)
- name: Session Echo
description: Per-user echo settings for API messages
- name: Session Presence
description: Per-user presence management β controls automatic PresenceUnavailable after connect, mirroring WhatsApp Web's behavior so the contact sees "last seen" instead of "online" while idle
- name: User
description: User profile management, contacts, and account settings
- name: User LID
description: Link ID (LID) mapping and conversion between phone numbers and LIDs
- name: Chat
description: Chat operations including message retrieval, archiving, pinning, and muting
- name: Send
description: "Send messages in all formats (text, media, documents, polls, buttons, lists, etc.).
API Echo Messages When the global flag ECHO_API_MESSAGES_ENABLED is true and the per-session echo setting is enabled, every successful API send emits a synthetic Message event through your configured transports/webhook. These events include the Info.IsFromAPI: true marker so downstream consumers can distinguish API-originated traffic. This ensures API-sent messages pass through the same filters/media pipeline as user-originated messages.
Per-Message Echo Control (EchoApi Field) All send endpoints support an optional EchoApi boolean field that provides message-level control over echo behavior. When set to true, the message will emit an API echo event regardless of global (ECHO_API_MESSAGES_ENABLED) or per-session (echo_api_messages) settings. This allows selective tracking of specific API-sent messages without enabling echo for all messages. The field is completely optional and defaults to respecting the configured echo settings when omitted. Use cases include: tracking critical business messages, monitoring specific conversation flows, or debugging individual message delivery."
- name: Label
description: Chat labeling and organization features
- name: Group
description: Group management including creation, participant management, and group settings
- name: Community
description: Community and sub-group management, announcements, and join requests
- name: Business
description: |
WhatsApp Business features of the connected session: catalog and products, collections, cart, merchant compliance, business profile and cover photo, catalog/product/shop messages, orders, billing declarations, bots and sticker packs.
**Typed catalog management routes** β `GET /business/linked-accounts`, `POST /business/eligibility`, `GET /business/catalog/{businessJID}/products/{productID}`, `POST /business/catalog/{businessJID}/products/query`, `GET /business/collections/{businessJID}/{collectionID}`, `POST /business/catalog`, `POST /business/products`, `PUT /business/products/{productID}`, `POST /business/products/delete`, `POST /business/products/image`, `PUT /business/products/{productID}/visibility`, `POST|PUT /business/collectionsβ¦`, `POST /business/collections/delete|reorder`, `PUT /business/cart`, `POST β¦/appeal`, `GET|PUT /business/merchant-compliance`, `PUT /business/profile`, `POST /business/cover`, `DELETE /business/cover/{coverID}` β share one pipeline:
- Request body (POST/PUT): exactly one JSON object, unknown fields rejected, at most 24 MiB β `400 invalid JSON body (maximum 24 MiB)`, `JSON object is required` or `exactly one JSON object is required`
- Path IDs (`productID`, `collectionID`, `coverID`) must be non-blank and at most 256 bytes β `400 ID must contain 1-256 bytes`; `businessJID` must be `@s.whatsapp.net` or `@lid` β `400 businessJID must be a user JID`, and `limit`/`cursor` are validated on those routes
- Validation runs before the session check, then `500 no session` / `client not connected`
- Any WhatsApp failure, including validation inside the WhatsApp library, returns `502 business operation failed: `
- The result is wrapped twice: `{"code":200,"data":{"data":β¦,"success":true},"success":true}`
- Successful mutations clear this user's in-memory catalog cache (300 s)
**Billing declarations** β `POST /business/order/charge/send`, `/business/order/accept`, `/business/order/status/send`, `/business/order/payment/status/send` and `/business/order/reject`:
- Require an Enterprise license (`403`, checked first)
- Body: exactly one JSON object with unknown fields rejected (256 KiB for billing, 16 KiB for refusal) β `400`
- `to` must be an individual buyer JID (`@s.whatsapp.net` or `@lid`, no device) and `id` at most 128 bytes
- Then `500 no session` / `client not connected`, `409 own device identity unavailable`, `500 buyer identity lookup failed`
- `502 β¦ delivery is not confirmed` means WhatsApp did not acknowledge the send: do not retry blindly, the buyer may have received it
- Only messages are sent: no bank or payment transaction is performed (`financial_transaction_performed: false`)
**Prices** β catalog prices are integers in thousandths of the currency (`3000000` = 3,000.00; strings on typed routes), while billing amounts use `{value, offset}` (`value/offset`).
- name: Device
description: Device management, platform detection, and linked device information
- name: Privacy
description: Privacy settings, blocklist management, and disappearing message configuration
- name: Newsletter
description: Newsletter/channel management, subscriptions, and newsletter messaging
- name: Status
description: Status/story posting in various formats (text, image, video, audio)
- name: Call
description: "Native VoIP calls engine (dial/answer/hangup/play/record + bidirectional s16le 16kHz PCM audio over /call/{call_id}/stream) plus legacy signaling control (reject/accept/preaccept/terminate/initiate).
π **[Build a perfect calls integration with any LLM β open the llm.txt guide β](/api/llm.txt)** β a complete, self-contained spec you can paste into Claude / GPT / Gemini."
externalDocs:
description: "π Calls API β complete LLM build guide (llm.txt)"
url: /api/llm.txt
- name: Sync
description: Synchronization and data consistency management
paths:
/session/echo/api:
post:
tags:
- Session Echo
summary: Turn API message echo events on or off
operationId: configureEchoApiMessages
description: |
Controls whether messages sent through this API also produce a synthetic `Message` event for this instance, so webhooks and transports see outgoing API messages like any other message.
**Rules:**
- With echo on, every successful send emits a `Message` event with `IsFromMe: true` and `Info.IsFromAPI: true`. It goes through the normal event pipeline (filters, media processing, webhook and transports).
- Echo events are only emitted when the server-wide `ECHO_API_MESSAGES_ENABLED` environment variable is `true` **and** this flag is on.
- A single send can force the echo regardless of both settings with `EchoApi`, `echoApi` or `echo_api` set to `true` in its request body.
- Because echo events are own messages, `POST /session/skipownmessages/config` with `enabled: true` drops them.
- `enabled` omitted (for example `{}`) is treated as `false` and disables echo.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/EchoAPISettingsRequest"
examples:
enable:
summary: Emit events for API sends
description: Webhook consumers receive the messages they sent through the API, flagged with `Info.IsFromAPI`.
value:
enabled: true
disable:
summary: Stop emitting events for API sends
description: Only messages received or sent from other devices generate events.
value:
enabled: false
responses:
"200":
description: Flag stored and user configuration cache reloaded.
content:
application/json:
schema:
$ref: "#/components/schemas/EchoAPISettingsUpdateResponse"
example:
code: 200
data:
Details: Echo API messages configuration updated successfully
EchoAPIMessages: true
success: true
"400":
description: "Bad Request: the body is empty or not valid JSON, or `enabled` is not a boolean."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 400
error: could not decode payload
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: the flag could not be stored or the user configuration cache could not be reloaded."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
update_failed:
summary: Database update failed
value:
code: 500
error: failed to update echo api messages configuration
success: false
cache_failed:
summary: Cache reload failed
value:
code: 500
error: failed to refresh configuration cache
success: false
get:
tags:
- Session Echo
summary: Get the API message echo setting
operationId: getEchoApiMessagesConfig
description: |
Returns whether this instance emits `Message` events for messages sent through the API.
**Rules:**
- `EchoAPIMessages` is the per-instance flag (`false` when never set).
- Echo events are only emitted when the server-wide `ECHO_API_MESSAGES_ENABLED` is also `true`; that variable is not included in this response.
security:
- ApiKeyAuth: []
responses:
"200":
description: Stored echo flag.
content:
application/json:
schema:
$ref: "#/components/schemas/EchoAPISettingsResponse"
example:
code: 200
data:
EchoAPIMessages: true
Details: Echo API messages configuration retrieved successfully
success: true
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: the flag could not be read from the database."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 500
error: failed to get echo api messages configuration
success: false
/admin/users:
get:
tags:
- Admin
summary: List all users
description: |
Returns every user (instance) stored in the gateway database, ordered by name, with its complete per-user configuration and live connection flags.
**Features:**
- `connected` and `loggedIn` come from the in-memory WhatsApp client; both are `false` when the instance has no client in this process.
- Includes webhook, event subscription, proxy, S3, RabbitMQ, WhatsApp client identity, skip filters, call rejection and global transport skip settings.
- `avatar_url` uses the cached value; missing avatars are fetched from WhatsApp in parallel for paired instances and saved back to the database.
**Rules:**
- Admin token required in the `Authorization` header (a `Bearer ` prefix is accepted).
- Credentials are returned as stored: `token`, `s3_config.access_key` and any password inside `rabbitmq_config.url` are **not masked**. The S3 secret key is never returned.
- `rabbitmq_config.queue_arguments` and `exchange_arguments` are returned as JSON-encoded strings.
- An empty database returns `data: []`.
security:
- AdminAuth: []
responses:
"200":
description: All users with their full configuration.
content:
application/json:
schema:
$ref: "#/components/schemas/AdminUserListResponse"
example:
code: 200
data:
- id: bec45bb93cbd24cbec32941ec3c93a12
name: store-support
avatar_url: https://pps.whatsapp.net/v/t61.24694-24/example.jpg
token: a1b2c3d4e5f6a7b8c9d0
webhook: https://hooks.example.com/zuckzapgo
jid: "5511999999999:12@s.whatsapp.net"
qrcode: ""
connected: true
loggedIn: true
expiration: 0
proxy_url: ""
events: Message,ReadReceipt,Connected
skip_media_download: false
skip_groups: true
skip_newsletters: true
skip_broadcasts: true
skip_own_messages: false
echo_api_messages: false
skip_calls: false
call_reject_message: Sorry, I cannot take calls at the moment.
call_reject_type: busy
globalTransportSkips:
skipGlobalWebhook: false
skipGlobalRabbitMQ: true
skipGlobalSQS: false
skipGlobalRedis: false
skipGlobalWebSocket: false
skipGlobalS3: false
isFromAPI: false
auto_presence_unavailable: false
proxy_config:
enabled: false
proxy_url: ""
s3_config:
enabled: true
endpoint: https://s3.us-east-1.amazonaws.com
region: us-east-1
bucket: zuckzapgo-media
access_key: AKIAEXAMPLEACCESSKEY
path_style: false
public_url: ""
media_delivery: both
retention_days: 30
disable_acl: true
rabbitmq_config:
enabled: false
url: ""
exchange: ""
exchange_type: ""
queue: ""
queue_type: ""
routing_key: ""
events: ""
durable: false
auto_delete: false
exclusive: false
no_wait: false
delivery_mode: 0
dead_letter_exchange: ""
dead_letter_routing_key: ""
message_ttl: 0
max_length: 0
max_length_bytes: 0
queue_arguments: ""
exchange_arguments: ""
whatsapp_config:
wa_version: ""
wa_platform: WEB
wa_release_channel: RELEASE
wa_web_sub_platform: WEB_BROWSER
wa_os_name: Mac OS 10
wa_os_version: 10.15.7
wa_device_name: Desktop
wa_manufacturer: Apple
wa_device_board: ""
wa_locale_language: en
wa_locale_country: US
wa_mcc: "000"
wa_mnc: "000"
wa_connect_type: WIFI_UNKNOWN
wa_platform_type: DESKTOP
success: true
"401":
description: Missing or invalid admin token (header `Authorization`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: the users query or row scan failed."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 500
error: problem accessing DB
success: false
"503":
description: "Service Unavailable: the gateway was started without an admin token, so admin routes are disabled."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 503
error: admin not configured
success: false
post:
tags:
- Admin
summary: Create a user (instance)
description: |
Creates a new user (WhatsApp instance) with its API token and optional webhook, event subscription, proxy, S3, RabbitMQ, WhatsApp client identity, skip filters, call rejection and global transport skip settings. The instance is created unpaired; connect it afterwards with `POST /session/connect` using the new token.
**Features:**
- `s3Config` accepts snake_case keys (preferred) and camelCase aliases; when both are sent, snake_case wins.
- `networkRoute` provisions the same native mobile egress as `POST /session/network-route` before the instance may connect.
- With `rabbitmqConfig.enabled: true` or `s3Config.enabled: true` the per-user client is initialized right away; initialization failures are only logged.
**Rules:**
- `token` must be unique: an existing token returns **409**. `name` and `token` are not validated for emptiness.
- Every comma-separated name in `events` must be a supported event type (case-sensitive, surrounding spaces ignored); otherwise **400** `invalid event type` with a `details` hint. An empty value subscribes to nothing.
- `callRejectMessage` defaults to `Sorry, I cannot take calls at the moment.` and `callRejectType` to `busy`.
- `networkRoute` cannot be combined with `proxyConfig` (**400** `network_route_conflicts_with_proxy`). Invalid route fields return **400** with the specific `network_route_*` code.
- The route manager is checked before the user is stored (**503** `network_route_manager_unavailable`). A route that fails after the user was stored returns **503** with `data.userId` and the blocked route state; the one-use `authKey` is consumed and never returned. Submit a higher `routeVersion` with a new key or delete the user.
- The response echoes the stored settings in snake_case. The S3 secret key is never echoed.
security:
- AdminAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateUser"
examples:
minimal:
summary: Minimal instance
description: Only a name and a unique token; no webhook and no event subscription yet.
value:
name: store-support
token: a1b2c3d4e5f6a7b8c9d0
webhook_and_filters:
summary: Webhook with event filters
description: Subscribes to three event types, skips group, newsletter and broadcast traffic, and rejects calls with a custom message.
value:
name: store-support
token: a1b2c3d4e5f6a7b8c9d0
webhook: https://hooks.example.com/zuckzapgo
events: Message,ReadReceipt,Connected
skipGroups: true
skipNewsletters: true
skipBroadcasts: true
skipCalls: true
callRejectMessage: We only answer by chat. Please send a message.
callRejectType: decline
s3_and_rabbitmq:
summary: S3 media storage and RabbitMQ publishing
description: Stores media in S3 (delivered as base64 and URL) and publishes all events to a per-user RabbitMQ exchange.
value:
name: store-support
token: a1b2c3d4e5f6a7b8c9d0
events: All
s3Config:
enabled: true
endpoint: https://s3.us-east-1.amazonaws.com
region: us-east-1
bucket: zuckzapgo-media
access_key: AKIAEXAMPLEACCESSKEY
secret_key: exampleSecretKey0123456789
media_delivery: both
retention_days: 30
disable_acl: true
rabbitmqConfig:
enabled: true
url: amqp://zuckzapgo:example-password@rabbitmq.internal:5672/
exchange: zuckzapgo.store-support
exchange_type: topic
queue: zuckzapgo.store-support.events
queue_type: quorum
routing_key: events.#
events: All
durable: true
delivery_mode: 2
dead_letter_exchange: dlx.zuckzapgo
message_ttl: 86400000
mobile_network_route:
summary: Instance behind a native mobile route
description: Prepares a fail-closed mobile egress before the instance may connect. The auth key is a one-use placeholder.
value:
name: pilot-mobile-01
token: f0e1d2c3b4a5968778695a4b3c2d1e0f
events: All
networkRoute:
mode: mobile
authKey: tskey-auth-REDACTED
exitNodeId: nStableMobileExit01
routeVersion: 1
idempotencyKey: provision-pilot-0001
failClosed: true
tcpOnly: true
responses:
"201":
description: User created. `data` echoes the stored configuration; `network_route` is present only when a route was requested and is ready.
content:
application/json:
schema:
$ref: "#/components/schemas/CreateUserResponse"
example:
code: 201
data:
id: bec45bb93cbd24cbec32941ec3c93a12
name: pilot-mobile-01
token: f0e1d2c3b4a5968778695a4b3c2d1e0f
webhook: ""
expiration: 0
events: All
proxy_config:
enabled: false
proxy_url: ""
s3_config:
enabled: false
endpoint: ""
region: ""
bucket: ""
access_key: ""
path_style: false
public_url: ""
media_delivery: ""
retention_days: 0
disable_acl: false
rabbitmq_config:
enabled: false
url: ""
exchange: ""
exchange_type: ""
queue: ""
queue_type: ""
routing_key: ""
events: ""
durable: false
auto_delete: false
exclusive: false
no_wait: false
delivery_mode: 0
dead_letter_exchange: ""
dead_letter_routing_key: ""
message_ttl: 0
max_length: 0
max_length_bytes: 0
queue_arguments: null
exchange_arguments: null
whatsapp_config:
wa_version: ""
wa_platform: ""
wa_release_channel: ""
wa_web_sub_platform: ""
wa_os_name: ""
wa_os_version: ""
wa_device_name: ""
wa_manufacturer: ""
wa_device_board: ""
wa_locale_language: ""
wa_locale_country: ""
wa_mcc: ""
wa_mnc: ""
wa_connect_type: ""
wa_platform_type: ""
skip_media_download: false
skip_groups: false
skip_newsletters: false
skip_broadcasts: false
skip_own_messages: false
echo_api_messages: false
skip_calls: false
call_reject_message: Sorry, I cannot take calls at the moment.
call_reject_type: busy
globalTransportSkips:
skipGlobalWebhook: false
skipGlobalRabbitMQ: false
skipGlobalSQS: false
skipGlobalRedis: false
skipGlobalWebSocket: false
skipGlobalS3: false
isFromAPI: false
auto_presence_unavailable: false
network_route:
mode: mobile
exitNodeId: nStableMobileExit01
desiredVersion: 1
appliedVersion: 1
failClosed: true
tcpOnly: true
status: ready
ready: true
success: true
"400":
description: "Bad Request: the body is not valid JSON, an event name is not supported, or `networkRoute` is invalid or combined with `proxyConfig`."
content:
application/json:
schema:
$ref: "#/components/schemas/AdminErrorWithDetails"
examples:
invalid_payload:
summary: Body is not valid JSON
value:
code: 400
error: invalid request payload
success: false
invalid_event_type:
summary: Unsupported name in events
value:
code: 400
details: "invalid event: Mesage"
error: invalid event type
success: false
network_route_conflicts_with_proxy:
summary: networkRoute sent together with proxyConfig
value:
code: 400
error: network_route_conflicts_with_proxy
success: false
network_route_auth_key_invalid:
summary: authKey is not a valid one-use key
value:
code: 400
error: network_route_auth_key_invalid
success: false
"401":
description: Missing or invalid admin token (header `Authorization`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"409":
description: "Conflict: another user already uses this token."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 409
error: user with this token already exists
success: false
"500":
description: "Internal Server Error: the token lookup or the insert failed, or a user ID could not be generated."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
database_error:
summary: Database failure
value:
code: 500
error: database error
success: false
id_generation_failed:
summary: Random ID generation failed
value:
code: 500
error: failed to generate user ID
success: false
"503":
description: "Service Unavailable: admin routes are disabled, the network route manager is not available (nothing stored), or the route could not be prepared after the user was stored (blocked user, `data.userId` returned)."
content:
application/json:
schema:
$ref: "#/components/schemas/CreateUserNetworkRouteFailureResponse"
examples:
route_prepare_failed:
summary: User stored in blocked state
value:
code: 503
data:
userId: bec45bb93cbd24cbec32941ec3c93a12
network_route:
mode: mobile
exitNodeId: nStableMobileExit01
desiredVersion: 1
appliedVersion: 0
failClosed: true
tcpOnly: true
status: blocked
ready: false
errorCode: network_route_prepare_failed
details: user persisted in blocked state; submit a higher routeVersion with a new one-use auth key or delete this user
error: network_route_prepare_failed
success: false
route_manager_unavailable:
summary: Route manager not running, nothing stored
value:
code: 503
error: network_route_manager_unavailable
success: false
admin_not_configured:
summary: Gateway started without an admin token
value:
code: 503
error: admin not configured
success: false
/admin/instances/status:
get:
tags:
- Admin
summary: List instance connection status
description: |
Returns a lightweight, paginated connection view of the instances, ordered by name and ID. Use it for dashboards and health polling instead of `GET /admin/users`, which loads every configuration column.
**Features:**
- Uses the live WhatsApp client when the instance has one in this process (`source: runtime`); otherwise falls back to the stored `connected` flag (`source: database`, `loggedIn: false`).
- `connectionHealth` summarizes the state: `connected`, `connected_not_logged`, `disconnected` or `no_client`.
- `qrcode` (base64 PNG data URL) and `qrcode_text` are filled only while the instance is not connected or not logged in.
- Pagination metadata is returned in the top-level `pagination` object; `total` only with `include_total=true`.
**Rules:**
- `limit` must be a positive integer (values above 1000 are capped to 1000); `offset` must be zero or positive; `include_total` must be a boolean. Anything else returns **400**.
- `ids` filters by a comma-separated list of user IDs (spaces and duplicates ignored). A value with no usable ID returns an empty page.
security:
- AdminAuth: []
parameters:
- name: limit
in: query
required: false
description: Page size. Positive integer; values above 1000 are capped to 1000.
schema:
type: integer
default: 200
minimum: 1
maximum: 1000
example: 50
- name: offset
in: query
required: false
description: Number of instances to skip. Use `pagination.next_offset` from the previous page.
schema:
type: integer
default: 0
minimum: 0
example: 0
- name: ids
in: query
required: false
description: Comma-separated user IDs to look up selectively.
schema:
type: string
example: bec45bb93cbd24cbec32941ec3c93a12,4fa3c1d2e5b6a7980c1d2e3f4a5b6c7d
- name: include_total
in: query
required: false
description: "`true` adds `pagination.total` (runs an extra COUNT query)."
schema:
type: boolean
default: false
example: true
responses:
"200":
description: One page of instance status entries.
content:
application/json:
schema:
$ref: "#/components/schemas/AdminInstanceStatusResponse"
examples:
first_page:
summary: First page with more results
value:
code: 200
data:
- id: bec45bb93cbd24cbec32941ec3c93a12
name: store-support
jid: "5511999999999:12@s.whatsapp.net"
qrcode: ""
qrcode_text: ""
connected: true
loggedIn: true
hasClient: true
connectionHealth: connected
lastSuccessfulConnect: 1757862000
autoReconnectErrors: 0
enableAutoReconnect: true
source: runtime
timestamp: "2026-09-15T12:00:00.123456789Z"
- id: 4fa3c1d2e5b6a7980c1d2e3f4a5b6c7d
name: store-sales
jid: ""
qrcode: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA
qrcode_text: 2@Xk3vQm9pZXhhbXBsZQ==,exampleKey=,exampleIdentity=,exampleAdv=
connected: false
loggedIn: false
hasClient: false
connectionHealth: no_client
lastSuccessfulConnect: 0
autoReconnectErrors: 0
enableAutoReconnect: false
source: database
timestamp: "2026-09-15T12:00:00.123456789Z"
pagination:
limit: 2
offset: 0
has_more: true
next_offset: 2
total: 5
success: true
empty_ids_filter:
summary: ids without any usable value
value:
code: 200
data: []
pagination:
limit: 200
offset: 0
has_more: false
next_offset: null
success: true
"400":
description: "Bad Request: `limit`, `offset` or `include_total` could not be parsed or is out of range."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
invalid_limit:
summary: limit is not a positive integer
value:
code: 400
error: invalid limit parameter
success: false
invalid_offset:
summary: offset is negative or not a number
value:
code: 400
error: invalid offset parameter
success: false
invalid_include_total:
summary: include_total is not a boolean
value:
code: 400
error: invalid include_total parameter
success: false
"401":
description: Missing or invalid admin token (header `Authorization`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: the status or count query failed."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 500
error: database error
success: false
"503":
description: "Service Unavailable: the gateway was started without an admin token."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 503
error: admin not configured
success: false
/admin/users/{id}:
get:
tags:
- Admin
summary: Get a user by ID
description: |
Returns one user with the same full configuration and live connection flags as `GET /admin/users`, filtered by the stored user ID.
**Rules:**
- `data` is always an **array**: one element when the ID exists, and an empty array (still **200**) when it does not. This route never returns 404.
- Credentials are returned as stored, exactly as in the list route (`token`, `s3_config.access_key` and any RabbitMQ URL password are not masked; the S3 secret key is never returned).
- Admin token required in the `Authorization` header.
security:
- AdminAuth: []
parameters:
- name: id
in: path
required: true
description: Stored user ID (32 hexadecimal characters), as returned by `POST /admin/users`.
schema:
type: string
example: bec45bb93cbd24cbec32941ec3c93a12
responses:
"200":
description: Array with the matching user, or an empty array when the ID does not exist.
content:
application/json:
schema:
$ref: "#/components/schemas/AdminUserListResponse"
examples:
found:
summary: User exists
value:
code: 200
data:
- id: bec45bb93cbd24cbec32941ec3c93a12
name: store-support
avatar_url: ""
token: a1b2c3d4e5f6a7b8c9d0
webhook: https://hooks.example.com/zuckzapgo
jid: "5511999999999:12@s.whatsapp.net"
qrcode: ""
connected: true
loggedIn: true
expiration: 0
proxy_url: socks5://proxy.example.com:1080
events: All
skip_media_download: true
skip_groups: false
skip_newsletters: false
skip_broadcasts: false
skip_own_messages: false
echo_api_messages: false
skip_calls: false
call_reject_message: Sorry, I cannot take calls at the moment.
call_reject_type: busy
globalTransportSkips:
skipGlobalWebhook: false
skipGlobalRabbitMQ: false
skipGlobalSQS: false
skipGlobalRedis: false
skipGlobalWebSocket: false
skipGlobalS3: false
isFromAPI: false
auto_presence_unavailable: false
proxy_config:
enabled: true
proxy_url: socks5://proxy.example.com:1080
s3_config:
enabled: false
endpoint: ""
region: ""
bucket: ""
access_key: ""
path_style: false
public_url: ""
media_delivery: base64
retention_days: 0
disable_acl: false
rabbitmq_config:
enabled: true
url: amqp://zuckzapgo:example-password@rabbitmq.internal:5672/
exchange: zuckzapgo.store-support
exchange_type: topic
queue: zuckzapgo.store-support.events
queue_type: quorum
routing_key: events.#
events: All
durable: true
auto_delete: false
exclusive: false
no_wait: false
delivery_mode: 2
dead_letter_exchange: dlx.zuckzapgo
dead_letter_routing_key: dlq.events
message_ttl: 86400000
max_length: 100000
max_length_bytes: 104857600
queue_arguments: '{"x-overflow":"reject-publish"}'
exchange_arguments: "{}"
whatsapp_config:
wa_version: ""
wa_platform: WEB
wa_release_channel: RELEASE
wa_web_sub_platform: WEB_BROWSER
wa_os_name: Mac OS 10
wa_os_version: 10.15.7
wa_device_name: Desktop
wa_manufacturer: Apple
wa_device_board: ""
wa_locale_language: en
wa_locale_country: US
wa_mcc: "000"
wa_mnc: "000"
wa_connect_type: WIFI_UNKNOWN
wa_platform_type: DESKTOP
success: true
not_found:
summary: Unknown ID (still 200)
value:
code: 200
data: []
success: true
"401":
description: Missing or invalid admin token (header `Authorization`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: the user query or row scan failed."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 500
error: problem accessing DB
success: false
"503":
description: "Service Unavailable: the gateway was started without an admin token."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 503
error: admin not configured
success: false
put:
tags:
- Admin
summary: Update a user's event delivery preferences
description: |
Partially updates the per-user event filtering flags of the user identified by `id`, without touching any other setting. The change applies to the next event without a restart or reconnect.
**Rules:**
- Every body field is an optional boolean: only the fields present are written, absent fields keep their stored value. Unknown fields are ignored.
- At least one known field is required, otherwise **400** `no updatable preference in payload`.
- Field to column mapping: `skipMedia` β `skip_media_download`, `skipGroups` β `skip_groups`, `skipNewsletters` β `skip_newsletters`, `skipBroadcasts` β `skip_broadcasts`, `skipOwnMessages` β `skip_own_messages`, `echoApiMessages` β `echo_api_messages`, `skipCalls` β `skip_calls`.
- The body is validated before the user lookup, so an unknown ID with an empty body returns 400, not 404.
**Side Effects:**
- The user's token cache entry is dropped so the next request or event reloads the preferences from the database.
- The response has no `data` key; `updated_fields` is the number of columns written.
security:
- AdminAuth: []
parameters:
- name: id
in: path
required: true
description: Stored user ID (32 hexadecimal characters).
schema:
type: string
example: bec45bb93cbd24cbec32941ec3c93a12
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/AdminUserPrefsRequest"
examples:
skip_media:
summary: Stop inlining media in events
description: For an integration that downloads media on demand through `/chat/download*`, so the base64 payload in events is not needed.
value:
skipMedia: true
several:
summary: Update several flags at once
description: Filters out group, newsletter and broadcast traffic while keeping call events.
value:
skipGroups: true
skipNewsletters: true
skipBroadcasts: true
skipCalls: false
responses:
"200":
description: Preferences written. The envelope carries `updated_fields` and no `data` key.
content:
application/json:
schema:
$ref: "#/components/schemas/AdminUserPrefsResponse"
examples:
one_field:
summary: One flag written
value:
code: 200
success: true
updated_fields: 1
four_fields:
summary: Four flags written
value:
code: 200
success: true
updated_fields: 4
"400":
description: "Bad Request: the body is not valid JSON (including non-boolean values) or carries no known preference."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
invalid_payload:
summary: Body is not valid JSON or a value is not a boolean
value:
code: 400
error: invalid request payload
success: false
no_field:
summary: No known preference in the body
value:
code: 400
error: no updatable preference in payload
success: false
"401":
description: Missing or invalid admin token (header `Authorization`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"404":
description: "Not Found: no user with this ID."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 404
error: user not found
success: false
"500":
description: "Internal Server Error: the user lookup or the update failed."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
lookup_failed:
summary: User lookup failed
value:
code: 500
error: database error
success: false
update_failed:
summary: Update statement failed
value:
code: 500
error: failed to update user preferences
success: false
"503":
description: "Service Unavailable: the gateway was started without an admin token."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 503
error: admin not configured
success: false
delete:
tags:
- Admin
summary: Delete a user (database row only)
description: |
Deletes the user row identified by `id` and tears down its runtime in this process. Use it to remove an instance quickly; use `DELETE /admin/users/{id}/full` to also log out and purge stored data.
**Behavior:**
- Takes the per-user session lock, stops the live WhatsApp client and releases its resources, even when the ID does not exist.
- Revokes the native network route of the user, if any. A revoke failure is only logged and does not abort the deletion.
- Deletes the row and immediately revokes the user's token, so it stops authenticating right away.
**Rules:**
- The WhatsApp device is **not** logged out and the whatsmeow device store, S3 objects, RabbitMQ queues and local files are **not** purged.
- **404** when no row matched the ID; the body then carries `details`.
security:
- AdminAuth: []
parameters:
- name: id
in: path
required: true
description: Stored user ID (32 hexadecimal characters).
schema:
type: string
example: bec45bb93cbd24cbec32941ec3c93a12
responses:
"200":
description: User row deleted.
content:
application/json:
schema:
$ref: "#/components/schemas/AdminUserDeleteResponse"
example:
code: 200
data:
id: bec45bb93cbd24cbec32941ec3c93a12
details: user deleted successfully
success: true
"401":
description: Missing or invalid admin token (header `Authorization`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"404":
description: "Not Found: no user with this ID."
content:
application/json:
schema:
$ref: "#/components/schemas/AdminErrorWithDetails"
example:
code: 404
details: "No user found with ID: bec45bb93cbd24cbec32941ec3c93a12"
error: user not found
success: false
"500":
description: "Internal Server Error: the delete statement failed or its affected row count could not be read."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
database_error:
summary: Delete statement failed
value:
code: 500
error: database error
success: false
verify_failed:
summary: Affected row count unavailable
value:
code: 500
error: Failed to verify deletion
success: false
"503":
description: "Service Unavailable: the gateway was started without an admin token."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 503
error: admin not configured
success: false
/admin/users/{id}/full:
delete:
tags:
- Admin
summary: Delete a user and purge all of its data
description: |
Completely removes a user: logs the WhatsApp device out, stops the runtime, and purges its database rows, device store, local files, S3 objects and RabbitMQ queues.
**Behavior (in order):**
- Checks that the user exists (**404** otherwise) and takes the per-user session lock.
- Logs out from WhatsApp when the client is connected; a logout failure falls through to a forced device-store deletion.
- Stops the client, clears the stored connection flag and QR codes, and revokes the native network route.
- Deletes the whatsmeow device, rows in `events_archive`, `monitoring_events` and `whatsmeow_privacy_tokens`, and the user row; then revokes the token and clears the S3 client and avatar caches.
- Removes the local `files/{id}` and `files/user_{id}` directories, then deletes the user's S3 objects (2 minute limit) and RabbitMQ queues (30 second limit).
**Rules:**
- Only a failure to check existence or to delete the user row aborts the request (**500** with `details`). Failures in every other step are logged and the response is still **200**.
- `data.name` and `data.jid` are empty when the stored configuration could not be read before deletion.
- This operation is irreversible and can take minutes when S3 holds many objects.
security:
- AdminAuth: []
parameters:
- name: id
in: path
required: true
description: Stored user ID (32 hexadecimal characters).
schema:
type: string
example: bec45bb93cbd24cbec32941ec3c93a12
responses:
"200":
description: User removed; all phases ran (individual phase failures are only logged).
content:
application/json:
schema:
$ref: "#/components/schemas/AdminUserFullDeleteResponse"
example:
code: 200
data:
id: bec45bb93cbd24cbec32941ec3c93a12
jid: "5511999999999:12@s.whatsapp.net"
name: store-support
details: user instance removed completely (all phases completed)
success: true
"400":
description: "Bad Request: the ID segment is empty."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 400
error: missing ID
success: false
"401":
description: Missing or invalid admin token (header `Authorization`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"404":
description: "Not Found: no user with this ID."
content:
application/json:
schema:
$ref: "#/components/schemas/AdminErrorWithDetails"
example:
code: 404
details: "No user found with ID: bec45bb93cbd24cbec32941ec3c93a12"
error: user not found
success: false
"500":
description: "Internal Server Error: the existence check or the final user row deletion failed."
content:
application/json:
schema:
$ref: "#/components/schemas/AdminErrorWithDetails"
examples:
existence_check_failed:
summary: Existence check failed
value:
code: 500
details: problem checking user existence
error: database error
success: false
row_delete_failed:
summary: User row deletion failed
value:
code: 500
details: failed to delete user from database
error: database error
success: false
"503":
description: "Service Unavailable: the gateway was started without an admin token."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 503
error: admin not configured
success: false
/admin/license/info:
get:
tags:
- Admin License
summary: Get license information
description: |
Returns the license state cached by the license validator, with live user counts from the database, for display in the admin dashboard.
**Features:**
- `users_count` and `connected_users_count` are counted live; when the query fails the cached values are used.
- `status` is `active`, `expiring_soon` (7 days or less), `grace_period` or `expired`, unless the license server supplied its own status.
- Includes the last validation outcome (`result`, `message`, `http_status`, `last_error`, `last_context`) and IP allowlist details when the license server returned them.
**Rules:**
- The body is the raw object, **not** wrapped in the `{code, data, success}` envelope. Errors use `{code, error, success}`.
- `license_key` is returned in full; the dashboard decides whether to hide it.
- `status_message` and `features` are currently produced in Portuguese by the gateway; the example shows their English meaning.
- `grace_period_end` is always present and is `0001-01-01T00:00:00Z` outside the grace period.
security:
- AdminAuth: []
responses:
"200":
description: License information (raw object, no envelope).
content:
application/json:
schema:
$ref: "#/components/schemas/AdminLicenseInfo"
example:
valid: true
installation_id: inst_1234567890abcdef
customer_id: cust_abcdef1234567890
installation_name: Production Server
plan_type: ENTERPRISE
plan_id: plan_enterprise_monthly
subscription_id: sub_0123456789abcdef
expires_at: "2026-12-31T23:59:59Z"
max_instances: 10
license_key: ZUCKZAP-ENT-2026-EXAMPLE-KEY0-0000
instance_id: zuckzapgo-prod-01
last_validation: "2026-09-15T12:00:00Z"
last_attempt: "2026-09-15T12:00:00Z"
days_until_expiry: 107
is_in_grace_period: false
grace_period_end: "0001-01-01T00:00:00Z"
status: active
status_message: License active and valid
features:
- Complete RESTful API
- Multiple instances
- Real-time events
- Priority support
- Advanced integrations
- 24/7 support
- Guaranteed SLA
- Interactive buttons
support_email: support@example.com
documentation_url: https://github.com/guilhermejansen/use-zuckzapgo
users_count: 4
connected_users_count: 3
result: active
message: License active and valid
http_status: 200
client_ip: 203.0.113.10
allowlisted_ips:
- 203.0.113.10
active_instances:
- instance_id: zuckzapgo-prod-01
ip_address: 203.0.113.10
version: 1.20.4
last_seen: "2026-09-15T12:00:00Z"
"401":
description: Missing or invalid admin token (header `Authorization`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: the license validator was not initialized at startup."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 500
error: License validator not initialized
success: false
"503":
description: "Service Unavailable: the license cache file cannot be read yet, or the gateway was started without an admin token."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
cache_unavailable:
summary: License cache not available
value:
code: 503
error: License information not available
success: false
admin_not_configured:
summary: Gateway started without an admin token
value:
code: 503
error: admin not configured
success: false
/newsletter/list:
get:
tags:
- Newsletter
summary: List followed channels with raw WhatsApp metadata
description: |
Returns every channel (newsletter) this account follows or owns, with the metadata exactly as WhatsApp returns it
(`xwa2_newsletter_subscribed`). Use it when you need fields that `GET /newsletter/subscribed` flattens away,
such as the channel state, verification badge, picture handles or reaction settings.
**Features:**
- One entry per channel in `data.Newsletter`, in the order returned by WhatsApp; the array is empty when the account follows no channel.
- `thread_metadata` carries name, description, invite code, creation time, subscriber count and picture info.
- `viewer_metadata` carries this account's `role` (`owner`, `admin`, `subscriber`, `guest`) and `mute` state; it may be `null`.
**Rules:**
- Numeric values such as `subscribers_count` and `creation_time` are JSON strings, as sent by WhatsApp.
- Failures reported by WhatsApp use a legacy envelope: `success` stays `true` and the message is the string in `data`.
- For a simplified list (`jid`, `name`, `subscribers`, `muted`...) use `GET /newsletter/subscribed`.
security:
- ApiKeyAuth: []
responses:
"200":
description: Followed channels with the raw WhatsApp metadata.
content:
application/json:
schema:
$ref: "#/components/schemas/NewsletterRawListResponse"
example:
code: 200
data:
Newsletter:
- id: 120363000000000022@newsletter
state:
type: active
thread_metadata:
creation_time: "1757900000"
invite: 0029VaExampleInviteCode01
name:
text: Product Updates
id: "1757900000123456"
update_time: "1757900000123456"
description:
text: Release notes and product news
id: "1757900000654321"
update_time: "1757900000654321"
subscribers_count: "1500"
verification: unverified
picture:
url: https://mmg.whatsapp.net/v/t61.24694-24/example-channel-picture.jpg
id: "1757900001"
type: image
direct_path: /v/t61.24694-24/example-channel-picture.jpg
hash: null
preview:
url: https://mmg.whatsapp.net/v/t61.24694-24/example-channel-preview.jpg
id: "1757900001"
type: preview
direct_path: /v/t61.24694-24/example-channel-preview.jpg
hash: null
settings:
reaction_codes:
value: all
viewer_metadata:
mute: "off"
role: owner
success: true
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error. A WhatsApp query failure uses the legacy envelope (message string in `data`, `success: true`). The `no session` case uses the standard `ErrorEnvelope` (`error`, `success: false`), shown in the `no_session` example."
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/ErrorEnvelope"
- $ref: "#/components/schemas/LegacyErrorEnvelope"
examples:
no_session:
summary: No WhatsApp session for this user
value:
code: 500
error: no session
success: false
list_failed:
summary: WhatsApp query failed (legacy envelope)
value:
code: 500
data: "failed to get newsletter list: websocket not connected"
success: true
/newsletter/create:
post:
tags:
- Newsletter
summary: Create a channel
description: |
Creates a WhatsApp channel (newsletter) owned by this account, optionally with a description and a picture.
The new channel JID is returned in `data.jid` and can be used right away with `POST /newsletter/send`.
**Rules:**
- The body must be exactly one JSON object of at most 24 MiB; unknown keys are ignored.
- `name` is required and cannot be blank. It is cut to its first 25 **bytes**, which may split a multi-byte character; `data.name` shows the value actually used.
- `picture` accepts a base64 data URL or an HTTP(S) URL of a JPEG, PNG, GIF or WebP image. It is converted to a JPEG of at most 640x640 pixels before upload.
- The account must have accepted the channel terms first (`POST /newsletter/accept-tos`); otherwise WhatsApp refuses the creation.
**Error envelopes:**
- Body and `name` validation errors and `no session` use the standard error envelope.
- Picture errors (**400**) and a creation refused by WhatsApp (**500**) use a legacy envelope: `success` stays `true` and the failure is in `data.success: false` with `data.message`.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/NewsletterCreateRequest"
examples:
name_only:
summary: Name only
description: Creates a channel without description or picture.
value:
name: Product Updates
with_picture_url:
summary: Name, description and picture URL
description: The picture is downloaded, converted to a JPEG of at most 640x640 and uploaded with the channel.
value:
name: Product Updates
description: Release notes and product news
picture: https://example.com/images/channel-cover.png
with_picture_data_url:
summary: Picture as a base64 data URL
description: Same as the URL variant, with the image embedded in the request (1x1 PNG shown).
value:
name: Product Updates
description: Release notes and product news
picture: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==
responses:
"200":
description: Channel created; `data.jid` is the new channel JID.
content:
application/json:
schema:
$ref: "#/components/schemas/NewsletterCreateResponse"
example:
code: 200
data:
success: true
jid: 120363000000000022@newsletter
name: Product Updates
message: Newsletter created successfully
success: true
"400":
description: "Bad Request: invalid body or missing `name` (error envelope), or an unusable `picture` (legacy envelope with `success: true`)."
content:
application/json:
schema:
$ref: "#/components/schemas/NewsletterLegacyErrorEnvelope"
examples:
invalid_json:
summary: Body is not valid JSON or exceeds 24 MiB
value:
code: 400
error: invalid newsletter JSON (maximum 24 MiB)
success: false
several_objects:
summary: More than one JSON value in the body
value:
code: 400
error: exactly one JSON object is required
success: false
name_required:
summary: name missing or blank
value:
code: 400
error: name is required
success: false
unsupported_picture_format:
summary: Picture is not JPEG, PNG, GIF or WebP (legacy envelope)
value:
code: 400
data:
success: false
message: "Invalid image format. Supported: JPEG, PNG, GIF, WebP"
success: true
invalid_picture_input:
summary: Picture is neither a data URL nor an HTTP(S) URL (legacy envelope)
value:
code: 400
data:
success: false
message: "Error processing image: invalid media input: must be either base64 data URL or HTTP(S) URL"
success: true
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: no WhatsApp session for this user (error envelope), or WhatsApp refused the creation (legacy envelope with `success: true`)."
content:
application/json:
schema:
$ref: "#/components/schemas/NewsletterLegacyErrorEnvelope"
examples:
no_session:
summary: No WhatsApp session for this user
value:
code: 500
error: no session
success: false
creation_refused:
summary: WhatsApp refused the creation (legacy envelope)
value:
code: 500
data:
success: false
message: "Error creating newsletter: info query timed out"
success: true
/newsletter/subscribed:
get:
tags:
- Newsletter
summary: List followed channels (simplified)
description: |
Returns the channels this account follows or owns as a flat list with the most useful fields: JID, name,
description, subscriber count, mute state and invite code.
**Rules:**
- `data.newsletters` is **omitted** (not an empty array) when the account follows no channel.
- `muted` is `true` when this account muted the channel notifications.
- `description` and `invite_code` are empty strings when WhatsApp does not return them.
- A failure reported by WhatsApp uses a legacy envelope: `success` stays `true` and the failure is in `data.success: false` with `data.message`.
- For the raw WhatsApp metadata (state, verification, pictures, role) use `GET /newsletter/list`.
security:
- ApiKeyAuth: []
responses:
"200":
description: Followed channels in simplified form.
content:
application/json:
schema:
$ref: "#/components/schemas/NewsletterSubscribedResponse"
examples:
with_channels:
summary: Account follows two channels
value:
code: 200
data:
success: true
newsletters:
- jid: 120363000000000022@newsletter
name: Product Updates
description: Release notes and product news
subscribers: 1500
muted: false
invite_code: 0029VaExampleInviteCode01
- jid: 120363000000000033@newsletter
name: Weekly Digest
description: ""
subscribers: 320
muted: true
invite_code: 0029VaExampleInviteCode02
success: true
no_channels:
summary: Account follows no channel
value:
code: 200
data:
success: true
success: true
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: no WhatsApp session for this user (error envelope), or WhatsApp failed to return the list (legacy envelope with `success: true`)."
content:
application/json:
schema:
$ref: "#/components/schemas/NewsletterLegacyErrorEnvelope"
examples:
no_session:
summary: No WhatsApp session for this user
value:
code: 500
error: no session
success: false
list_failed:
summary: WhatsApp query failed (legacy envelope)
value:
code: 500
data:
success: false
message: "Error listing newsletters: websocket not connected"
success: true
/newsletter/info:
post:
tags:
- Newsletter
summary: Get channel information by JID
description: |
Fetches the metadata of one channel by its JID: name, description, subscriber count, invite code and, when
WhatsApp returns viewer data, this account's mute state and role. The account does not need to follow the channel.
**Rules:**
- The channel JID is required and must be `@newsletter` without device. Send it as `NewsletterJID`, `newsletter_jid`, `jid`, `NewsletterID` or `newsletterID`, in the JSON body or in the query string.
- When the JID is sent under several keys the values must be identical, otherwise the request fails with `conflicting newsletter parameters`.
- The body must be a single JSON object of at most 1 MiB; keys other than the JID aliases are ignored.
- `description`, `invite_code` and `role` are omitted when empty; `role` is `owner`, `admin`, `subscriber` or `guest`.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/main.NewsletterTargetRequest"
examples:
dashboard_field:
summary: Channel JID in the dashboard SDK field
description: "`NewsletterJID` is the field sent by the bundled dashboard SDK."
value:
NewsletterJID: 120363000000000022@newsletter
short_alias:
summary: Channel JID with the short alias
description: "`jid` and `newsletter_jid` are accepted as aliases of `NewsletterJID`."
value:
jid: 120363000000000022@newsletter
responses:
"200":
description: Channel metadata.
content:
application/json:
schema:
$ref: "#/components/schemas/NewsletterInfoResponse"
example:
code: 200
data:
jid: 120363000000000022@newsletter
name: Product Updates
description: Release notes and product news
subscribers: 1500
invite_code: 0029VaExampleInviteCode01
muted: false
role: owner
success: true
"400":
description: "Bad Request: the body is not a single JSON object, or the channel JID is missing, invalid or conflicting."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
invalid_jid:
summary: JID missing or not a newsletter JID
value:
code: 400
error: invalid newsletter JID
success: false
conflicting_jid:
summary: Different JIDs under two aliases
value:
code: 400
error: conflicting newsletter parameters
success: false
invalid_json:
summary: Body is not valid JSON
value:
code: 400
error: invalid newsletter JSON payload
success: false
non_string_jid:
summary: JID sent as a number
value:
code: 400
error: newsletter target must be a string
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"404":
description: "Not Found: WhatsApp returned no channel for this JID."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
not_found:
summary: No channel returned
value:
code: 404
error: newsletter not found
success: false
"500":
description: "Internal Server Error: no WhatsApp session for this user, or WhatsApp failed to return the channel metadata."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: No WhatsApp session for this user
value:
code: 500
error: no session
success: false
info_failed:
summary: WhatsApp query failed
value:
code: 500
error: "error getting info: info query timed out"
success: false
/newsletter/send:
post:
tags:
- Newsletter
summary: Publish a post to a channel
description: |
Publishes a text, media or poll post to a channel this account owns or administers. Channel media is uploaded
unencrypted and sent with the media handle, as the official client does.
**Features:**
- **Text:** `message`.
- **Media:** `image`, `video`, `document`, `audio` or `sticker`, each as a base64 data URL or an HTTP(S) URL. `caption` applies to image, video and document.
- **Poll:** `question` with at least 2 `options`; `max_answer` sets how many options a follower may pick.
**Rules:**
- `jid` is required and must be an `@newsletter` JID.
- Send one content type. When several are present, the first non-empty one wins in this order: `message`, `image`, `video`, `document`, `audio`, `sticker`, poll.
- Audio is always sent as a voice note (PTT) with a generated waveform; stickers are uploaded as images; `filename` (document name and title) defaults to `document`.
- `max_answer` defaults to 1, values below 1 become 1, and a value above the number of options returns **400**. A `question` with fewer than 2 options counts as no content.
- The whole request (download, upload and send) times out after 120 seconds.
- `data.id` is the message ID. Reactions and view receipts need the numeric `server_id` from `POST /newsletter/messages`.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/NewsletterSendRequest"
examples:
text:
summary: Text post
description: Publishes a plain text post.
value:
jid: 120363000000000022@newsletter
message: Version 2.4 is live. Check the release notes on our website.
image_url:
summary: Image with caption (URL)
description: The image is downloaded from the URL, uploaded to the channel media server and sent with a 72x72 thumbnail.
value:
jid: 120363000000000022@newsletter
image: https://example.com/images/release-2-4.jpg
caption: Version 2.4 highlights
document_url:
summary: Document with file name
description: "`filename` is used as the document name and title shown to followers."
value:
jid: 120363000000000022@newsletter
document: https://example.com/files/release-notes-2-4.pdf
filename: release-notes-2-4.pdf
caption: Full changelog
voice_note:
summary: Voice note
description: Audio is always delivered as a voice note (PTT).
value:
jid: 120363000000000022@newsletter
audio: https://example.com/audio/weekly-briefing.ogg
poll:
summary: Single-choice poll
description: A poll needs `question` and at least 2 `options`; `max_answer` 1 makes it single choice.
value:
jid: 120363000000000022@newsletter
question: Which feature should ship next?
options:
- Dark mode
- Offline sync
- Shared folders
max_answer: 1
responses:
"200":
description: Post published.
content:
application/json:
schema:
$ref: "#/components/schemas/NewsletterSendResponse"
example:
code: 200
data:
success: true
id: 3EB0C767D26A1D6B8A9F
timestamp: 1757901234
success: true
"400":
description: "Bad Request: invalid JSON or JID, no content, unusable media input, or `max_answer` above the number of options."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
invalid_json:
summary: Body is not valid JSON
value:
code: 400
error: invalid JSON
success: false
invalid_jid:
summary: jid is missing or not an @newsletter JID
value:
code: 400
error: invalid JID
success: false
no_content:
summary: No text, media or valid poll in the body
value:
code: 400
error: no message content provided
success: false
invalid_media:
summary: Media is neither a data URL nor an HTTP(S) URL
value:
code: 400
error: "error processing image: invalid media input: must be either base64 data URL or HTTP(S) URL"
success: false
max_answer_too_high:
summary: max_answer greater than the number of options
value:
code: 400
error: max_answer cannot be greater than options length (2)
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: no WhatsApp session, media upload failure, or WhatsApp rejected the post."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: No WhatsApp session for this user
value:
code: 500
error: no session
success: false
upload_failed:
summary: Media upload failed
value:
code: 500
error: "error uploading video: websocket not connected"
success: false
send_failed:
summary: WhatsApp rejected the post
value:
code: 500
error: "error sending message: websocket not connected"
success: false
/newsletter/follow:
post:
tags:
- Newsletter
summary: Follow a channel by JID
description: |
Follows (subscribes to) a WhatsApp channel identified by its JID, so its posts appear in this account's Updates tab.
Use `POST /newsletter/follow-invite` when you only have an invite code or link.
**Rules:**
- The channel JID is required (`@newsletter`, no device) under `NewsletterJID`, `newsletter_jid`, `jid`, `NewsletterID` or `newsletterID`, in the body or the query string; repeated values must match.
- The body must be a single JSON object of at most 1 MiB. Other keys are ignored.
- Following a channel that is already followed is passed to WhatsApp as is; the gateway does not check the current state.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/main.NewsletterTargetRequest"
examples:
dashboard_field:
summary: Follow with the dashboard SDK field
description: "`NewsletterJID` is the field sent by the bundled dashboard SDK."
value:
NewsletterJID: 120363000000000022@newsletter
snake_case_alias:
summary: Follow with the snake_case alias
description: "`newsletter_jid` is equivalent to `NewsletterJID`; sending both with different values returns 400."
value:
newsletter_jid: 120363000000000022@newsletter
responses:
"200":
description: WhatsApp accepted the follow request.
content:
application/json:
schema:
$ref: "#/components/schemas/NewsletterActionResponse"
example:
code: 200
data:
success: true
message: Subscribed successfully
success: true
"400":
description: "Bad Request: the body is not a single JSON object, or the channel JID is missing, invalid or conflicting."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
invalid_jid:
summary: JID missing or not a newsletter JID
value:
code: 400
error: invalid newsletter JID
success: false
conflicting_jid:
summary: Different JIDs under two aliases
value:
code: 400
error: conflicting newsletter parameters
success: false
invalid_json:
summary: Body is not valid JSON
value:
code: 400
error: invalid newsletter JSON payload
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: no WhatsApp session for this user, or WhatsApp rejected the follow request."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: No WhatsApp session for this user
value:
code: 500
error: no session
success: false
follow_failed:
summary: WhatsApp rejected the request
value:
code: 500
error: "error subscribing: info query timed out"
success: false
/newsletter/follow-invite:
post:
tags:
- Newsletter
summary: Follow a channel by invite code or link
description: |
Follows a WhatsApp channel from its invite code or `https://whatsapp.com/channel/...` link. The gateway first
resolves the code to the channel metadata, then follows the resolved JID, which is returned in `data.jid`.
**Rules:**
- The invite is required under `Code`, `code`, `invite_code`, `NewsletterInviteCode` or `newsletterInviteCode`, in the body or the query string; repeated values must match.
- Send either the bare code or the full channel link (the `https://whatsapp.com/channel/` prefix is stripped); maximum 2048 bytes.
- The body must be a single JSON object of at most 1 MiB. Other keys are ignored.
- An unknown or revoked code fails while resolving it (`error getting info: ...`), before any follow request is sent.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/main.NewsletterTargetRequest"
examples:
invite_code:
summary: Follow with the bare invite code
description: "`Code` is the field sent by the bundled dashboard SDK."
value:
Code: 0029VaExampleInviteCode01
channel_link:
summary: Follow with the full channel link
description: The link prefix is removed before the code is resolved; the lowercase `code` alias is accepted.
value:
code: https://whatsapp.com/channel/0029VaExampleInviteCode01
responses:
"200":
description: Invite resolved and follow request accepted; `data.jid` is the followed channel.
content:
application/json:
schema:
$ref: "#/components/schemas/NewsletterFollowInviteResponse"
example:
code: 200
data:
success: true
message: Subscribed successfully
jid: 120363000000000022@newsletter
success: true
"400":
description: "Bad Request: the body is not a single JSON object, or the invite code is missing, too long or conflicting."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
missing_code:
summary: Invite code missing, blank or over 2048 bytes
value:
code: 400
error: newsletter invite code is required (maximum 2048 bytes)
success: false
conflicting_code:
summary: Different codes under two aliases
value:
code: 400
error: conflicting newsletter parameters
success: false
invalid_json:
summary: Body is not valid JSON
value:
code: 400
error: invalid newsletter JSON payload
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"404":
description: "Not Found: WhatsApp returned no channel for this invite code."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
not_found:
summary: No channel returned
value:
code: 404
error: newsletter not found for invite
success: false
"500":
description: "Internal Server Error: no WhatsApp session, the invite could not be resolved, or WhatsApp rejected the follow request."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: No WhatsApp session for this user
value:
code: 500
error: no session
success: false
resolve_failed:
summary: Invite code could not be resolved
value:
code: 500
error: "error getting info: info query timed out"
success: false
follow_failed:
summary: WhatsApp rejected the follow request
value:
code: 500
error: "error subscribing: websocket not connected"
success: false
/newsletter/unfollow:
post:
tags:
- Newsletter
summary: Unfollow a channel by JID
description: |
Unfollows (unsubscribes from) a WhatsApp channel identified by its JID, removing it from this account's followed channels.
To remove a channel you own for everyone, use `DELETE /newsletter/{newsletterID}` instead.
**Rules:**
- Send the channel JID (`@newsletter`, no device) as `NewsletterJID`, `newsletter_jid`, `jid`, `NewsletterID` or `newsletterID`, in the body or the query string. Values under several keys must be identical.
- Only the JID is read; the body must be one JSON object (max 1 MiB).
- Use `POST /newsletter/unfollow-invite` when you only have the invite link.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/main.NewsletterTargetRequest"
examples:
dashboard_field:
summary: Unfollow with the dashboard SDK field
description: "`NewsletterJID` is the field sent by the bundled dashboard SDK."
value:
NewsletterJID: 120363000000000022@newsletter
short_alias:
summary: Unfollow with the short alias
description: "`jid` is accepted as an alias of `NewsletterJID`."
value:
jid: 120363000000000022@newsletter
responses:
"200":
description: WhatsApp accepted the unfollow request.
content:
application/json:
schema:
$ref: "#/components/schemas/NewsletterActionResponse"
example:
code: 200
data:
success: true
message: Unsubscribed successfully
success: true
"400":
description: "Bad Request: the body is not a single JSON object, or the channel JID is missing, invalid or conflicting."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
invalid_jid:
summary: JID missing or not a newsletter JID
value:
code: 400
error: invalid newsletter JID
success: false
conflicting_jid:
summary: Different JIDs under two aliases
value:
code: 400
error: conflicting newsletter parameters
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: no WhatsApp session for this user, or WhatsApp rejected the unfollow request."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: No WhatsApp session for this user
value:
code: 500
error: no session
success: false
unfollow_failed:
summary: WhatsApp rejected the request
value:
code: 500
error: "error unsubscribing: info query timed out"
success: false
/newsletter/unfollow-invite:
post:
tags:
- Newsletter
summary: Unfollow a channel by invite code or link
description: |
Unfollows a WhatsApp channel from its invite code or channel link. The gateway resolves the code to the channel
JID first and then sends the unfollow request for that JID.
**Rules:**
- Send the invite as `Code`, `code`, `invite_code`, `NewsletterInviteCode` or `newsletterInviteCode` (body or query string); identical values are required when repeated.
- The bare code and the `https://whatsapp.com/channel/` link are both accepted, up to 2048 bytes.
- Unlike `POST /newsletter/follow-invite`, the response does not include the resolved JID.
- An unknown or revoked code fails while resolving it (`error getting info: ...`) and nothing is unfollowed.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/main.NewsletterTargetRequest"
examples:
invite_code:
summary: Unfollow with the bare invite code
description: "`Code` is the field sent by the bundled dashboard SDK."
value:
Code: 0029VaExampleInviteCode01
channel_link:
summary: Unfollow with the full channel link
description: "`invite_code` is accepted as an alias; the link prefix is removed before resolving."
value:
invite_code: https://whatsapp.com/channel/0029VaExampleInviteCode01
responses:
"200":
description: Invite resolved and unfollow request accepted.
content:
application/json:
schema:
$ref: "#/components/schemas/NewsletterActionResponse"
example:
code: 200
data:
success: true
message: Unsubscribed successfully
success: true
"400":
description: "Bad Request: the body is not a single JSON object, or the invite code is missing, too long or conflicting."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
missing_code:
summary: Invite code missing, blank or over 2048 bytes
value:
code: 400
error: newsletter invite code is required (maximum 2048 bytes)
success: false
non_string_code:
summary: Invite code sent as a number
value:
code: 400
error: newsletter target must be a string
success: false
invalid_json:
summary: Body is not valid JSON
value:
code: 400
error: invalid newsletter JSON payload
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"404":
description: "Not Found: WhatsApp returned no channel for this invite code."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
not_found:
summary: No channel returned
value:
code: 404
error: newsletter not found for invite
success: false
"500":
description: "Internal Server Error: no WhatsApp session, the invite could not be resolved, or WhatsApp rejected the unfollow request."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: No WhatsApp session for this user
value:
code: 500
error: no session
success: false
resolve_failed:
summary: Invite code could not be resolved
value:
code: 500
error: "error getting info: info query timed out"
success: false
unfollow_failed:
summary: WhatsApp rejected the unfollow request
value:
code: 500
error: "error unsubscribing: websocket not connected"
success: false
/newsletter/mute:
post:
tags:
- Newsletter
summary: Mute or unmute channel notifications
description: |
Mutes or unmutes the notifications of a channel this account follows. Muting does not unfollow the channel; posts
keep arriving silently.
**Rules:**
- Channel JID required (`@newsletter`, no device) under `jid`, `NewsletterJID`, `newsletter_jid`, `NewsletterID` or `newsletterID`; the query string is accepted too.
- `mute` (alias `Mute`) must be a JSON boolean: `true` mutes, `false` unmutes. Strings such as `"true"` are rejected. Omitted or `null` means `false` (unmute), as in the original contract.
- When both `mute` and `Mute` are sent, `mute` wins.
- The body must be a JSON object of at most 1 MiB; `null` values count as absent and data after the object is ignored.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/NewsletterMuteRequest"
examples:
mute:
summary: Mute a channel
description: Stops notifications for new posts of the channel.
value:
jid: 120363000000000022@newsletter
mute: true
unmute:
summary: Unmute a channel
description: Turns the channel notifications back on.
value:
jid: 120363000000000022@newsletter
mute: false
responses:
"200":
description: WhatsApp applied the mute setting. `data.message` says `muted` or `enabled`.
content:
application/json:
schema:
$ref: "#/components/schemas/NewsletterActionResponse"
examples:
muted:
summary: Channel muted
value:
code: 200
data:
success: true
message: Notifications muted successfully
success: true
unmuted:
summary: Channel unmuted
value:
code: 200
data:
success: true
message: Notifications enabled successfully
success: true
"400":
description: "Bad Request: invalid body, invalid or conflicting channel JID, or `mute` not a boolean."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
mute_not_boolean:
summary: mute is not a JSON boolean
value:
code: 400
error: mute must be a boolean
success: false
invalid_jid:
summary: JID missing or not a newsletter JID
value:
code: 400
error: invalid newsletter JID
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: no WhatsApp session for this user, or WhatsApp rejected the mute change."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: No WhatsApp session for this user
value:
code: 500
error: no session
success: false
mute_failed:
summary: WhatsApp rejected the change
value:
code: 500
error: "error changing mute: info query timed out"
success: false
/newsletter/messages:
post:
tags:
- Newsletter
summary: List recent posts of a channel
description: |
Returns recent posts of a channel with their view and reaction counts, text or caption and media details. Each
item's `server_id` is the ID required by `POST /newsletter/reaction` and `POST /newsletter/mark-viewed`.
**Pagination:**
- `limit` (aliases `count`, `Count`): 1-1000 posts, default 25.
- `before_id` (aliases `before`, `Before`): only posts older than this server ID. Use the smallest `server_id` of the previous page.
- Both accept a JSON number or a numeric string.
**Rules:**
- The channel JID is required under `NewsletterJID`, `newsletter_jid`, `jid`, `NewsletterID` or `newsletterID`, in the body or the query string; values repeated under several keys must be identical.
- The body must be a single JSON object of at most 1 MiB.
- `media` holds `type`, `mimetype`, `url`, `sha256` (base64) and `size`, plus `title` for documents and `duration` (seconds) for audio.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/main.NewsletterTargetRequest"
examples:
latest_page:
summary: Latest 25 posts
description: Without pagination fields the newest 25 posts are returned.
value:
NewsletterJID: 120363000000000022@newsletter
older_page:
summary: Next page with the dashboard fields
description: Returns 10 posts older than server ID 120.
value:
newsletter_jid: 120363000000000022@newsletter
limit: 10
before_id: "120"
legacy_aliases:
summary: Pagination with count and before aliases
description: "`count` and `before` are accepted as aliases of `limit` and `before_id`."
value:
jid: 120363000000000022@newsletter
count: 50
before: 120
responses:
"200":
description: Channel posts.
content:
application/json:
schema:
$ref: "#/components/schemas/NewsletterMessagesResponse"
example:
code: 200
data:
success: true
messages:
- id: 3EB0C767D26A1D6B8A9F
server_id: 121
type: text
timestamp: 1757901234
text: Version 2.4 is live
views_count: 42
reaction_counts:
"π": 3
- id: 3EB0C767D26A1D6B8A9E
server_id: 120
type: media
timestamp: 1757897634
caption: Version 2.4 highlights
views_count: 57
media:
type: image
mimetype: image/jpeg
url: https://mmg.whatsapp.net/v/t62.7118-24/example-post-image.jpg
sha256: n4bQgYhMfWWaL+qgxVrQFaO/TxsrC4Is0V1sFbDwCgg=
size: 48213
success: true
"400":
description: "Bad Request: invalid body, missing or conflicting channel JID, or invalid pagination."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
invalid_jid:
summary: JID missing or not a newsletter JID
value:
code: 400
error: invalid newsletter JID
success: false
count_out_of_range:
summary: limit outside 1-1000
value:
code: 400
error: newsletter count must be between 1 and 1000
success: false
invalid_before:
summary: before_id is negative or not numeric
value:
code: 400
error: before must be a nonnegative server message ID
success: false
wrong_type:
summary: limit sent as a boolean
value:
code: 400
error: newsletter parameter must be string or integer
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: no WhatsApp session for this user, or WhatsApp failed to return the posts."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: No WhatsApp session for this user
value:
code: 500
error: no session
success: false
fetch_failed:
summary: WhatsApp query failed
value:
code: 500
error: "error getting messages: info query timed out"
success: false
/newsletter/reaction:
post:
tags:
- Newsletter
summary: React to a channel post
description: |
Sends a reaction from this account to a channel post, or removes the current reaction with an empty `reaction`.
**Rules:**
- `jid` (aliases `NewsletterJID`, `newsletter_jid`) must be an `@newsletter` JID.
- `server_id` (alias `message_id`) is required: a positive numeric server ID as a number or string. Take it from `server_id` in `POST /newsletter/messages`; the `id` returned by `POST /newsletter/send` is not a server ID.
- The session is checked first (**500** `no session`). As in the original contract, a missing or non-positive numeric `server_id` or a parseable JID that is not an `@newsletter` JID (for example `{}`) returns **500** `error sending reaction: ...`; nothing is sent to WhatsApp. A body that is not a JSON object, a field with the wrong type or a non-numeric string ID returns **400**.
- `reaction` (alias `emoji`): the emoji to set; `""`, `null` or omitted removes the reaction (original contract).
- The body must be a JSON object of at most 1 MiB. Unknown keys are ignored, `null` values count as absent, key names are case-insensitive, and the canonical key wins over a differing alias.
- Reacting is a follower action: when the channel owner reacts to its own post the call returns 200 but no reaction becomes visible.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/NewsletterReactionRequest"
examples:
add_reaction:
summary: React with an emoji
description: Adds or replaces this account's reaction on post 121.
value:
jid: 120363000000000022@newsletter
server_id: 121
reaction: "π"
remove_reaction:
summary: Remove the reaction
description: An empty `reaction` removes this account's reaction.
value:
jid: 120363000000000022@newsletter
server_id: 121
reaction: ""
aliases:
summary: Dashboard aliases
description: "`NewsletterJID`, `message_id` (numeric string) and `emoji` are normalized to `jid`, `server_id` and `reaction`."
value:
NewsletterJID: 120363000000000022@newsletter
message_id: "121"
emoji: "β€οΈ"
responses:
"200":
description: WhatsApp accepted the reaction change.
content:
application/json:
schema:
$ref: "#/components/schemas/NewsletterActionResponse"
example:
code: 200
data:
success: true
message: Reaction sent successfully
success: true
"400":
description: "Bad Request: the body is not a JSON object, a field has the wrong type (including a non-numeric string `server_id`), or the JID cannot be parsed."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
invalid_json:
summary: Body is not a JSON object
value:
code: 400
error: invalid newsletter JSON object
success: false
invalid_type:
summary: A known field has the wrong JSON type
value:
code: 400
error: invalid newsletter parameter type
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: no WhatsApp session for this user, `server_id` missing or not positive, `jid` missing or not a newsletter JID (original contract), or WhatsApp rejected the reaction."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: No WhatsApp session for this user
value:
code: 500
error: no session
success: false
invalid_server_id:
summary: server_id missing, zero or negative
value:
code: 500
error: "error sending reaction: message ID must be a positive numeric server ID"
success: false
invalid_jid:
summary: jid missing or not a newsletter JID
value:
code: 500
error: "error sending reaction: invalid newsletter JID"
success: false
reaction_failed:
summary: WhatsApp rejected the reaction
value:
code: 500
error: "error sending reaction: websocket not connected"
success: false
/newsletter/mark-viewed:
post:
tags:
- Newsletter
summary: Mark channel posts as viewed
description: |
Sends a view receipt for one or more channel posts, incrementing their `views_count`. This is not the same as
marking the chat as read on other devices.
**Rules:**
- `jid` (aliases `NewsletterJID`, `newsletter_jid`) must be an `@newsletter` JID.
- `server_ids` (alias `message_ids`) is required: at least one positive server ID (numbers or numeric strings) from `POST /newsletter/messages`.
- The session is checked first (**500** `no session`). As in the original contract, missing or empty `server_ids`, a non-positive numeric ID or a parseable JID that is not an `@newsletter` JID (for example `{}`) returns **500** `error marking as viewed: ...`; nothing is sent to WhatsApp. A body that is not a JSON object, a field with the wrong type or a non-numeric string ID returns **400**.
- The body must be a JSON object of at most 1 MiB. Unknown keys are ignored and `null` values count as absent.
- A view is counted only for posts this account has not viewed yet; repeating the call returns 200 without changing `views_count`.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/NewsletterMarkViewedRequest"
examples:
server_ids:
summary: Mark two posts as viewed
description: Sends one view receipt covering posts 120 and 121.
value:
jid: 120363000000000022@newsletter
server_ids:
- 120
- 121
aliases:
summary: Dashboard aliases with string IDs
description: "`newsletter_jid` and `message_ids` are normalized; numeric strings are converted to numbers."
value:
newsletter_jid: 120363000000000022@newsletter
message_ids:
- "120"
- "121"
responses:
"200":
description: WhatsApp accepted the view receipt.
content:
application/json:
schema:
$ref: "#/components/schemas/NewsletterActionResponse"
example:
code: 200
data:
success: true
message: Messages marked as viewed
success: true
"400":
description: "Bad Request: the body is not a JSON object, a field has the wrong type (including non-numeric string IDs), or the JID cannot be parsed."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
invalid_json:
summary: Body is not a JSON object
value:
code: 400
error: invalid newsletter JSON object
success: false
invalid_type:
summary: A known field has the wrong JSON type
value:
code: 400
error: invalid newsletter parameter type
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: no WhatsApp session for this user, `server_ids` missing, empty or not positive, `jid` missing or not a newsletter JID (original contract), or WhatsApp rejected the view receipt."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: No WhatsApp session for this user
value:
code: 500
error: no session
success: false
ids_required:
summary: server_ids missing or empty
value:
code: 500
error: "error marking as viewed: provide at least one server message ID"
success: false
invalid_id:
summary: An ID is zero or negative
value:
code: 500
error: "error marking as viewed: message ID must be a positive numeric server ID"
success: false
receipt_failed:
summary: WhatsApp rejected the receipt
value:
code: 500
error: "error marking as viewed: websocket not connected"
success: false
/newsletter/subscribe-live-updates:
post:
tags:
- Newsletter
summary: Subscribe to live reaction and view updates of a channel
description: |
Asks WhatsApp to push live reaction and view-count updates of a channel to this session for a limited time.
WhatsApp answers with the subscription length in seconds (`data.duration`); renew the subscription before it expires.
**Rules:**
- Target channel: `NewsletterJID`, `newsletter_jid`, `jid`, `NewsletterID` or `newsletterID` (body or query string), formatted `@newsletter` without device; conflicting values under several keys return 400.
- The body must be a single JSON object of at most 1 MiB; keys other than the channel aliases are ignored.
- The WhatsApp request has its own 30-second timeout.
- `duration` is `0` when WhatsApp does not state a length.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/NewsletterLiveUpdatesRequest"
examples:
subscribe:
summary: Subscribe to live updates
description: Starts (or renews) the live updates subscription of the channel.
value:
jid: 120363000000000022@newsletter
dashboard_field:
summary: Subscribe with the dashboard SDK field
description: "`NewsletterJID` is accepted as an alias of `jid`."
value:
NewsletterJID: 120363000000000022@newsletter
responses:
"200":
description: Subscription accepted; `data.duration` is its length in seconds.
content:
application/json:
schema:
$ref: "#/components/schemas/NewsletterLiveUpdatesResponse"
example:
code: 200
data:
success: true
duration: 300
message: Subscribed to live updates
success: true
"400":
description: "Bad Request: the body is not a single JSON object, or the channel JID is missing, invalid or conflicting."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
invalid_jid:
summary: JID missing or not a newsletter JID
value:
code: 400
error: invalid newsletter JID
success: false
json_object_required:
summary: Body is JSON null
value:
code: 400
error: JSON object is required
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: no WhatsApp session for this user, or WhatsApp did not accept the subscription within 30 seconds."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: No WhatsApp session for this user
value:
code: 500
error: no session
success: false
subscribe_failed:
summary: WhatsApp query failed
value:
code: 500
error: "error subscribing to live updates: info query timed out"
success: false
/newsletter/message-updates:
post:
tags:
- Newsletter
summary: Get reaction and view-count updates of channel posts
description: |
Returns the latest reaction and view counts of channel posts, like the official client's message-updates query.
The request always carries a cursor: `after`, `before`, or (when neither is sent) a cursor anchored on the newest post.
**Cursor:**
- `after`: updates for posts newer than this server ID.
- `before`: updates for posts older than this server ID (exclusive). When `after` is also sent, `after` wins.
- Neither: the gateway reads the newest post first and asks for the latest `count` posts; a channel without posts returns an empty list.
- `count`: `0`, negative or omitted means 25; other values are passed to WhatsApp unchanged (original contract). `since` (Unix seconds) limits the result to changes after that time; negative cursors and `since` are ignored.
**Rules:**
- `jid` (aliases `NewsletterJID`, `newsletter_jid`) must be an `@newsletter` JID.
- The body must be a JSON object of at most 1 MiB. Unknown keys (including the unsupported `message_ids`) are ignored and `null` values count as absent.
- `media` in each update only carries `type`, `mimetype`, `url` (plus `title` for documents), and only for image, video and document posts.
- WhatsApp may not answer this query; the call then fails with **500** `error getting updates: info query timed out`.
- The session is checked first (**500** `no session`). As in the original contract, a missing `jid` or a parseable JID that is not an `@newsletter` JID (for example `{}`) returns **500** `error getting updates: invalid newsletter JID`; nothing is sent to WhatsApp. A body that is not a JSON object, a field with the wrong type or an unparseable JID returns **400**.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/NewsletterMessageUpdatesRequest"
examples:
latest:
summary: Updates of the latest 25 posts
description: No cursor; the gateway anchors on the newest post.
value:
jid: 120363000000000022@newsletter
after_cursor:
summary: Updates for posts newer than a server ID
description: Returns up to 50 updates for posts newer than server ID 120.
value:
jid: 120363000000000022@newsletter
count: 50
after: 120
before_since:
summary: Older posts changed since a time
description: Posts older than server ID 121 whose counters changed after the given Unix time.
value:
jid: 120363000000000022@newsletter
before: 121
since: 1757890000
responses:
"200":
description: Updates of the selected posts; `data.updates` is empty when nothing matches.
content:
application/json:
schema:
$ref: "#/components/schemas/NewsletterMessageUpdatesResponse"
example:
code: 200
data:
success: true
updates:
- id: 3EB0C767D26A1D6B8A9F
server_id: 121
type: text
timestamp: 1757901234
views_count: 58
reaction_counts:
"π": 5
"β€οΈ": 2
text: Version 2.4 is live
success: true
"400":
description: "Bad Request: the body is not a JSON object, a field has the wrong type, or the JID cannot be parsed."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
invalid_type:
summary: A known field has the wrong JSON type
value:
code: 400
error: invalid newsletter parameter type
success: false
invalid_json:
summary: Body is not a JSON object
value:
code: 400
error: invalid newsletter JSON object
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: no WhatsApp session, `jid` missing or not a newsletter JID (original contract), the newest post could not be read, or WhatsApp did not answer the updates query."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: No WhatsApp session for this user
value:
code: 500
error: no session
success: false
invalid_jid:
summary: jid missing or not a newsletter JID
value:
code: 500
error: "error getting updates: invalid newsletter JID"
success: false
query_timeout:
summary: WhatsApp did not answer
value:
code: 500
error: "error getting updates: info query timed out"
success: false
anchor_failed:
summary: Newest post could not be read
value:
code: 500
error: "error getting updates: could not read the newest post to anchor the updates cursor: websocket not connected"
success: false
"501":
description: "Not Implemented: the bundled WhatsApp library lacks the before-cursor updates query. The library shipped with this build implements it, so this is a defensive answer."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 501
error: "error getting updates: the bundled WhatsApp library does not support this official newsletter operation yet"
success: false
/newsletter/accept-tos:
post:
tags:
- Newsletter
summary: Accept a WhatsApp terms of service notice
description: |
Accepts a WhatsApp terms of service notice for this account. Accepting the channel notice is required once before
`POST /newsletter/create`; the defaults target that notice.
**Rules:**
- A JSON object is required: send `{}` to accept the channel notice with the defaults. An empty body returns **400** `invalid JSON`.
- `notice_id` defaults to `20601218` and `stage` to `5` when omitted or empty. Both must be JSON strings; numbers are rejected as `invalid JSON`.
- Unknown keys are ignored.
- The session is checked before the body, so a missing session returns **500** even for an invalid body.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/NewsletterAcceptTOSRequest"
examples:
channel_defaults:
summary: Accept the channel creation notice
description: An empty object uses notice `20601218`, stage `5`.
value: {}
explicit_notice:
summary: Explicit notice and stage
description: Same notice as the defaults, sent explicitly.
value:
notice_id: "20601218"
stage: "5"
responses:
"200":
description: WhatsApp accepted the notice.
content:
application/json:
schema:
$ref: "#/components/schemas/NewsletterActionResponse"
example:
code: 200
data:
success: true
message: Terms of service accepted
success: true
"400":
description: "Bad Request: the body is empty, not valid JSON, or has non-string fields."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 400
error: invalid JSON
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: no WhatsApp session for this user, or WhatsApp rejected the acceptance."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: No WhatsApp session for this user
value:
code: 500
error: no session
success: false
accept_failed:
summary: WhatsApp rejected the request
value:
code: 500
error: "error accepting terms: websocket not connected"
success: false
/newsletter/admin-invite:
post:
tags:
- Newsletter
summary: Invite a contact to become a channel admin
description: |
Invites a person to become admin of a channel this account owns, following the official client flow: the gateway
first creates the invite on the WhatsApp server for the invitee's LID (the server returns the expiration) and only
then sends the `NewsletterAdminInviteMessage` carrying that expiration to the invitee.
**Rules:**
- `phone`, `newsletter_jid`, `image`, `caption` and `name` are all required and non-empty.
- `phone` accepts a phone number, an `@s.whatsapp.net` JID or an `@lid` JID. Groups and other JID types are refused.
- Phone numbers are resolved to a LID from the local store or a WhatsApp lookup; when no LID is found the call fails with **400** (message the contact first or pass the `@lid` JID).
- `image` (base64 data URL or HTTP(S) URL) becomes a 96px JPEG thumbnail; an undecodable image is sent without thumbnail. It is fetched before `newsletter_jid` is validated.
- `name` is the channel name shown in the invite card; the gateway does not read it from the channel.
- A message sent without a server-side invite shows as "invite cancelled", which is why a refused invite (**502**) sends nothing.
**Response:** `expires_at` is the server expiration (Unix seconds), `invitee_lid` the resolved LID and `invite_created` is always `true`.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/NewsletterAdminInviteRequest"
examples:
by_phone:
summary: Invite by phone number
description: The number is resolved to the invitee's LID before the invite is created.
value:
phone: "5511999999999"
newsletter_jid: 120363000000000022@newsletter
image: https://example.com/images/channel-cover.png
caption: Join me as admin of Product Updates
name: Product Updates
by_lid:
summary: Invite by LID with a data URL image
description: A `@lid` JID skips the LID lookup (1x1 PNG shown as image).
value:
phone: 123456789012345@lid
newsletter_jid: 120363000000000022@newsletter
image: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==
caption: Join me as admin of Product Updates
name: Product Updates
responses:
"200":
description: Invite created on the server and invite message sent.
content:
application/json:
schema:
$ref: "#/components/schemas/NewsletterAdminInviteResponse"
example:
code: 200
data:
success: true
id: 3EB0A1B2C3D4E5F60718
timestamp: 1757901234
recipient: "5511999999999"
newsletter_jid: 120363000000000022@newsletter
invite_name: Product Updates
expires_at: 1758506034
invitee_lid: 123456789012345@lid
invite_created: true
message: Newsletter admin invite sent successfully
success: true
"400":
description: "Bad Request: invalid JSON, missing fields, unparseable phone, unusable image, invalid channel JID, non-person invitee or unresolvable LID."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
invalid_json:
summary: Body is not valid JSON
value:
code: 400
error: invalid JSON
success: false
missing_fields:
summary: A required field is empty
value:
code: 400
error: phone, newsletter_jid, image, caption and name are required
success: false
invalid_phone:
summary: phone cannot be parsed
value:
code: 400
error: could not parse phone number
success: false
invalid_newsletter_jid:
summary: newsletter_jid is not an @newsletter JID
value:
code: 400
error: invalid newsletter JID
success: false
not_a_person:
summary: phone is a group or another non-user JID
value:
code: 400
error: admin invites can only be sent to a person
success: false
lid_not_found:
summary: Invitee LID could not be resolved
value:
code: 400
error: could not resolve the invitee LID; send a message to this contact first or pass the @lid JID
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: no WhatsApp session, or the invite message could not be sent after the server-side invite was created."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: No WhatsApp session for this user
value:
code: 500
error: no session
success: false
send_failed:
summary: Invite message not sent
value:
code: 500
error: "error sending admin invite: websocket not connected"
success: false
"501":
description: "Not Implemented: the bundled WhatsApp library cannot create admin invites. The library shipped with this build implements it, so this is a defensive answer."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 501
error: the bundled WhatsApp library does not support this official newsletter operation yet
success: false
"502":
description: "Bad Gateway: WhatsApp refused to create the invite (for example, this account is not the channel owner). No message is sent."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 502
error: "whatsapp did not create the admin invite: info query timed out"
success: false
/health:
get:
tags:
- System
summary: Check server health
description: |
Public liveness and readiness probe. Returns the aggregated health status, runtime metrics and the result of a database ping.
**Rules:**
- No authentication.
- The only dependency checked is the database: a ping with a 250 ms timeout.
- Ping succeeds within 750 ms: service `up`, overall `healthy`, HTTP **200**.
- Ping succeeds but takes longer than 750 ms: service `degraded`, overall `degraded`, still HTTP **200**. In practice the 250 ms timeout usually turns a slow database into `down` first.
- Ping fails, times out, or no database is configured: service `down`, overall `unhealthy`, HTTP **503**.
- The snapshot is cached for 3 seconds, so faster probes return the same body.
**Payload:**
- Health fields sit at the top level next to `code`, `data` and `success`. `data` is `OK` for 200 and `ERROR` for 503; `success` is `false` on 503. There is no `error` field.
- `build.commit` appears only when `GIT_COMMIT` is set; `environment.app_env` comes from `APP_ENV` or `ENVIRONMENT`, `environment.app_region` from `APP_REGION`.
security: []
responses:
"200":
description: Server healthy or degraded.
content:
application/json:
schema:
$ref: "#/components/schemas/HealthStatusResponse"
example:
code: 200
data: OK
success: true
status: healthy
version: v1.20.4
uptime: 86400
timestamp: "2026-09-15T12:00:00Z"
metrics:
goroutines: 42
go_version: go1.25.1
cpu_count: 8
go_max_procs: 8
environment:
containerized: true
hostname: zuckzapgo-01
app_env: production
build:
commit: a1b2c3d4
services:
database:
status: up
latency_ms: 1.42
open_connections: 10
in_use: 2
idle: 8
driver: postgres
"503":
description: "Service Unavailable: the database ping failed or no database is configured. The body keeps the health payload shape (no `error` field)."
content:
application/json:
schema:
$ref: "#/components/schemas/HealthStatusEnvelope"
example:
code: 503
data: ERROR
success: false
status: unhealthy
version: v1.20.4
uptime: 3600
timestamp: "2026-09-15T12:00:00Z"
metrics:
goroutines: 38
go_version: go1.25.1
cpu_count: 8
go_max_procs: 8
environment:
containerized: true
hostname: zuckzapgo-01
services:
database:
status: down
error: context deadline exceeded
latency_ms: 250.31
open_connections: 0
in_use: 0
idle: 0
driver: postgres
/webhook:
get:
tags:
- Webhook
summary: Get the instance webhook and subscribed events
description: |
Returns the individual webhook URL of this instance and the event types it is subscribed to.
**Rules:**
- `webhook` is empty when no individual webhook is configured.
- `subscribe` is the stored comma-separated list split into an array. When nothing is stored the array contains one empty string (`[""]`).
- The server-wide global webhook is configured by environment variables and is not part of this response.
**Event types:**
- **Messages:** `Message`, `UndecryptableMessage`, `FBMessage`, `Receipt`, `MediaRetry`, `ReadReceipt`
- **Chat management:** `Star`, `Pin`, `Archive`, `Mute`, `MarkChatAsRead`, `ClearChat`, `DeleteChat`, `DeleteForMe`, `LabelAssociationChat`, `LabelAssociationMessage`, `LabelEdit`
- **Groups and contacts:** `GroupInfo`, `JoinedGroup`, `Contact`, `Picture`, `PushName`, `BusinessName`, `UserAbout`
- **Privacy:** `PrivacySettings`, `IdentityChange`, `Blocklist`, `BlocklistChange`, `UserStatusMute`
- **Connection:** `Connected`, `Disconnected`, `QR`, `PairSuccess`, `PairError`, `QRScannedWithoutMultidevice`, `LoggedOut`, `StreamReplaced`, `StreamError`, `ConnectFailure`, `KeepAliveTimeout`, `KeepAliveRestored`, `ManualLoginReconnect`, `TemporaryBan`, `ClientOutdated`, `CATRefreshError`, `PasskeyRequest`, `PasskeyConfirmation`
- **Calls:** `CallOffer`, `CallAccept`, `CallAcceptEngine`, `CallPreAccept`, `CallTransport`, `CallTerminate`, `CallTerminateEngine`, `CallRecordingReady`, `CallReject`, `CallOfferNotice`, `CallRelayLatency`, `CallReminder`, `UnknownCallEvent`
- **Presence:** `Presence`, `ChatPresence`
- **Newsletters:** `NewsletterJoin`, `NewsletterLeave`, `NewsletterMuteChange`, `NewsletterLiveUpdate`
- **Sync:** `AppState`, `AppStateSyncComplete`, `AppStateSyncError`, `HistorySync`, `OfflineSyncPreview`, `OfflineSyncCompleted`, `PushNameSetting`, `UnarchiveChatsSetting`
- **Special:** `All` subscribes to every event type
security:
- ApiKeyAuth: []
responses:
"200":
description: Stored webhook URL and subscription.
content:
application/json:
schema:
$ref: "#/components/schemas/WebhookGetResponse"
examples:
configured:
summary: Webhook with selected events
value:
code: 200
data:
webhook: https://example.com/webhooks/whatsapp
subscribe:
- Message
- ReadReceipt
- Connected
success: true
not_configured:
summary: No webhook stored
value:
code: 200
data:
webhook: ""
subscribe:
- ""
success: true
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: the webhook could not be read from the database."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 500
error: "could not get webhook: sql: database is closed"
success: false
post:
tags:
- Webhook
summary: Set the instance webhook URL and events
description: |
Sets the individual webhook URL of this instance and, optionally, replaces its event subscription.
**Rules:**
- `webhookurl` is stored as sent, without URL validation. An empty or omitted value clears the webhook and unregisters the individual webhook transport.
- `events` omitted or empty: only the URL changes and the stored subscription is kept.
- `events` non-empty: names are matched exactly (case-sensitive, no trimming), unknown names are silently discarded and the valid ones **replace** the stored subscription. If every name is unknown, the subscription becomes empty.
- Event names are the ones listed in `GET /webhook`; `All` subscribes to every event type.
**Side effects:**
- The user cache is updated, live client subscriptions are refreshed and the individual webhook transport is registered in the event dispatcher.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/WebhookSet"
examples:
with_events:
summary: URL and selected events
description: Stores the URL and subscribes only to messages, read receipts and connection events.
value:
webhookurl: https://example.com/webhooks/whatsapp
events:
- Message
- ReadReceipt
- Connected
all_events:
summary: URL and every event type
description: "`All` subscribes the webhook to every supported event type."
value:
webhookurl: https://example.com/webhooks/whatsapp
events:
- All
url_only:
summary: Change only the URL
description: Without `events`, the stored subscription is kept.
value:
webhookurl: https://example.com/webhooks/whatsapp-v2
clear:
summary: Remove the webhook URL
description: An empty URL unregisters the individual webhook transport; the stored subscription is kept.
value:
webhookurl: ""
responses:
"200":
description: Webhook stored. `data.webhook` echoes the stored URL.
content:
application/json:
schema:
$ref: "#/components/schemas/WebhookSetResponse"
example:
code: 200
data:
webhook: https://example.com/webhooks/whatsapp
success: true
"400":
description: "Bad Request: the body is not valid JSON or `events` is not an array of strings."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 400
error: could not decode payload
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: the webhook could not be stored."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 500
error: "could not set webhook: sql: database is closed"
success: false
put:
tags:
- Webhook
summary: Update the webhook URL, events and activation
description: |
Updates the individual webhook of this instance, with an explicit activation switch.
**Rules:**
- `active` defaults to `false` when omitted. With `active: false` the stored URL is cleared and the transport unregistered, whatever `webhookurl` says; send `active: true` to keep a webhook.
- `events` non-empty: names are trimmed, unknown names silently discarded, and the valid list replaces the stored subscription. With `active: false` the subscription is cleared instead.
- `events` omitted or empty: only the URL column is written and the stored subscription is kept.
- `webhookurl` is stored without URL validation.
**Response:**
- `data.webhook` is the stored URL (empty when inactive), `data.events` the accepted event names (`null` when none was sent or accepted) and `data.active` echoes the request.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/WebhookUpdate"
examples:
activate:
summary: Activate with URL and events
description: Stores the URL, replaces the subscription and registers the webhook transport.
value:
webhookurl: https://example.com/webhooks/whatsapp
events:
- Message
- ReadReceipt
active: true
url_only:
summary: Change the URL and keep the events
description: Without `events`, only the URL changes. `active` must be `true` or the URL is cleared.
value:
webhookurl: https://example.com/webhooks/whatsapp-v2
active: true
deactivate:
summary: Deactivate and clear the subscription
description: "`active: false` with a non-empty `events` clears both the URL and the stored subscription."
value:
webhookurl: ""
events:
- Message
active: false
responses:
"200":
description: Webhook updated.
content:
application/json:
schema:
$ref: "#/components/schemas/WebhookUpdateResponse"
examples:
active:
summary: Active webhook
value:
code: 200
data:
active: true
events:
- Message
- ReadReceipt
webhook: https://example.com/webhooks/whatsapp
success: true
inactive:
summary: Deactivated webhook
value:
code: 200
data:
active: false
events:
- Message
webhook: ""
success: true
"400":
description: "Bad Request: the body is not valid JSON or a field has the wrong type."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 400
error: could not decode payload
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: the webhook could not be stored."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 500
error: "could not update webhook: sql: database is closed"
success: false
delete:
tags:
- Webhook
summary: Delete the instance webhook and its events
description: |
Removes the individual webhook of this instance: the URL and the event subscription are both cleared.
**Rules:**
- No request body.
- The individual webhook transport is unregistered from the event dispatcher and the user cache is updated.
- The server-wide global webhook and other transports (RabbitMQ, SQS, Redis, WebSocket) are not affected.
- Deleting when no webhook is configured still returns **200**.
security:
- ApiKeyAuth: []
responses:
"200":
description: Webhook URL and events cleared.
content:
application/json:
schema:
$ref: "#/components/schemas/WebhookDeleteResponse"
example:
code: 200
data:
Details: Webhook and events deleted successfully
success: true
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: the webhook could not be removed from the database."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 500
error: "could not delete webhook: sql: database is closed"
success: false
/session/connect:
post:
tags:
- Session
summary: Connect the instance to WhatsApp
description: |
Starts the WhatsApp client of this instance in the background and stores the event subscription used by its individual webhook.
Without a stored session the client starts in pairing mode: read the code with `GET /session/qr` or request a phone code with `POST /session/pairphone`. A stored, valid session reconnects without scanning. Use this endpoint again after `POST /session/disconnect`.
**Rules:**
- The body is required; an empty body returns `400 could not decode Payload`. Send at least `{}`. Field names are matched case-insensitively.
- `Subscribe` **replaces** the stored subscription (`users.events`) on every call. Unknown names are discarded and duplicates removed; omitting it, sending `[]` or only unknown names stores an empty subscription, which stops individual webhook deliveries (global transports are not affected). Send `["All"]` to receive every event.
- `Immediate: false` (default) blocks for about 10 seconds and returns `500 failed to connect` when the socket is not up by then. `Immediate: true` returns at once; check `GET /session/status` afterwards.
- A connected client returns `500 already connected`; a stale, disconnected client is cleaned up and replaced.
- `data.jid` and `data.webhook` are the values stored before this call (`jid` is empty before the first pairing); `data.events` is the new comma-separated subscription.
**Event names:** `Message`, `ReadReceipt`, `Receipt`, `Presence`, `ChatPresence`, `GroupInfo`, `Connected`, `Disconnected`, `LoggedOut`, `QR`, `PairSuccess`, `CallOffer`, `CallTerminate`, `NewsletterJoin`, `HistorySync`, `All` and the rest of `supportedEventTypes` in `constants.go`.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/Connect"
examples:
selected_events:
summary: Subscribe to selected events and return immediately
description: Stores `Message,ReadReceipt,Connected` as the individual webhook subscription and answers without waiting for the socket.
value:
Subscribe:
- Message
- ReadReceipt
- Connected
Immediate: true
all_events_wait:
summary: All events, wait up to 10 seconds
description: Blocks for about 10 seconds and fails with 500 when the client is not connected by then.
value:
Subscribe:
- All
Immediate: false
no_subscription:
summary: Connect without individual webhook events
description: Omitting `Subscribe` clears the stored subscription; global transports still receive events.
value:
Immediate: true
responses:
"200":
description: Client started. With `Immediate:false` the socket was connected within the wait.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionConnectResponse"
examples:
paired_session:
summary: Stored session reconnected
value:
code: 200
data:
details: Connected!
events: Message,ReadReceipt,Connected
jid: 5511999999999:12@s.whatsapp.net
skip_media_download: false
webhook: https://example.com/webhook
success: true
first_pairing:
summary: New instance, waiting for QR scan
value:
code: 200
data:
details: Connected!
events: All
jid: ""
skip_media_download: false
webhook: ""
success: true
"400":
description: "Bad Request: the body is empty or not valid JSON."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 400
error: could not decode Payload
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: the client is already connected, or the socket did not connect within the 10-second wait."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
already_connected:
summary: A connected client already exists
value:
code: 500
error: already connected
success: false
failed_to_connect:
summary: Socket not connected after the wait
value:
code: 500
error: failed to connect
success: false
/session/disconnect:
post:
tags:
- Session
summary: Disconnect from WhatsApp and keep the session
description: |
Closes the WhatsApp socket of this instance while keeping the paired device credentials, so `POST /session/connect` can resume later without scanning a QR code again.
**Rules:**
- No request body is read.
- Requires a client in memory; otherwise returns `500 no session`.
- When the client was connected or logged in, a synthetic `Disconnected` event (`source: session/disconnect`, `synthetic: true`) is dispatched to the configured webhooks before cleanup.
- The client resources are released, the `connected` flag is cleared in the database and any stored QR code is discarded.
- `wasConnected` / `wasLoggedIn` report the client state immediately before the call.
**Use Cases:**
- Pause event delivery during maintenance
- Apply a new proxy (`POST /session/proxy` requires a disconnected client)
- Use `POST /session/logout` instead to unlink the device for good
security:
- ApiKeyAuth: []
responses:
"200":
description: Client disconnected; the paired session is kept.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionDisconnectResponse"
example:
code: 200
data:
Details: Disconnected successfully
wasConnected: true
wasLoggedIn: true
success: true
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: there is no client in memory for this instance (never connected, or already disconnected)."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 500
error: no session
success: false
/session/logout:
post:
tags:
- Session
summary: Log out and unlink the device
description: |
Logs the linked device out of WhatsApp and removes the local session, so the next `POST /session/connect` starts a fresh pairing (QR code or phone code).
**Rules:**
- No request body is read.
- Requires a client in memory; otherwise returns `500 no session`.
- When the client is logged in, the gateway asks WhatsApp to remove the device (30-second timeout). The local cleanup always runs, even when that request fails; `logoutSuccess: false` tells that WhatsApp did not confirm the removal.
- A client that was not logged in is only cleaned up and reports `logoutSuccess: true`.
- The stored QR code is cleared and the `connected` flag is reset.
**Use Cases:**
- Revoke API access to a WhatsApp account
- Switch the instance to another phone number
- Use `POST /session/disconnect` to pause without unlinking
security:
- ApiKeyAuth: []
responses:
"200":
description: Local session removed. Check `logoutSuccess` to know whether WhatsApp confirmed the device removal.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionLogoutResponse"
examples:
logged_out:
summary: Device removed from WhatsApp
value:
code: 200
data:
Details: Logout completed
logoutSuccess: true
wasConnected: true
wasLoggedIn: true
success: true
cleanup_only:
summary: WhatsApp did not confirm; local session removed anyway
value:
code: 200
data:
Details: Logout completed
logoutSuccess: false
wasConnected: false
wasLoggedIn: true
success: true
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: there is no client in memory for this instance."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 500
error: no session
success: false
/session/refresh:
post:
tags:
- Session
summary: Reconnect and resynchronize the session
description: |
Restarts the WhatsApp client of an already paired instance and, once the socket is back, optionally resynchronizes app state, pre-keys and privacy settings.
**Features:**
- **Reconnect:** releases the current client, starts a new one with the stored subscription and waits 3 seconds.
- **App state:** fetches the five collections `critical_block`, `critical_unblock_low`, `regular_low`, `regular_high` and `regular` from scratch.
- **Auto recovery:** when a collection fails, asks the primary phone for an app-state recovery snapshot.
- **Pre-keys:** reads the server pre-key count and uploads new keys when fewer than 5 remain.
- **Privacy:** fetches the privacy settings bypassing the cache.
**Rules:**
- The body is optional; every flag defaults to `true`. An unreadable body is ignored and the defaults are used.
- The instance must have a stored JID; before the first pairing the call returns `400`.
- The sync steps only run when the new client is connected after the 3-second wait. `sync` and `sync_options` are omitted otherwise, or when all flags are `false`.
- When the new client is not connected, the response is **500** but keeps the legacy envelope: `success: true` at the top level and the details in `data` with `refreshSuccess: false`.
- Typical duration: 4 to 10 seconds. Do not call it in a tight loop.
security:
- ApiKeyAuth: []
requestBody:
required: false
content:
application/json:
schema:
$ref: "#/components/schemas/SessionRefreshRequest"
examples:
full_refresh:
summary: Full refresh (same as an empty body)
description: Reconnects and runs every sync step with automatic recovery.
value:
sync_app_state: true
refresh_prekeys: true
refresh_privacy: true
auto_recovery: true
reconnect_only:
summary: Reconnect without sync steps
description: Only restarts the client; `sync` and `sync_options` are omitted from the response.
value:
sync_app_state: false
refresh_prekeys: false
refresh_privacy: false
app_state_without_recovery:
summary: Resync app state without asking the phone for recovery
description: Runs the app-state fetch only and never sends recovery requests to the primary device.
value:
sync_app_state: true
refresh_prekeys: false
refresh_privacy: false
auto_recovery: false
responses:
"200":
description: Client reconnected; `data.sync` holds the result of each requested step.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionRefreshResponse"
example:
code: 200
data:
Details: Connection refresh completed
refreshSuccess: true
wasConnected: true
wasLoggedIn: true
newConnected: true
newLoggedIn: true
jid: 5511999999999:12@s.whatsapp.net
sync_options:
sync_app_state: true
refresh_prekeys: true
refresh_privacy: true
auto_recovery: true
sync:
app_state:
- name: critical_block
success: true
duration: 1.234s
- name: critical_unblock_low
success: true
duration: 856.1ms
- name: regular_low
success: true
duration: 523.4ms
- name: regular_high
success: false
error: "failed to verify patch v42: mismatching LTHash"
duration: 412.9ms
recovery_requested: true
- name: regular
success: true
duration: 678.2ms
prekeys:
checked: true
server_count: 47
privacy_settings:
fetched: true
total_duration: 4.521s
success: true
"400":
description: "Bad Request: the instance has never been paired, so there is no JID to reconnect."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 400
error: no JID found, QR scan required for initial pairing
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error. When the new client is not connected after the wait, the body keeps the legacy envelope (`success: true`, details in `data`, `data.error` set). A response that cannot be encoded uses the error envelope."
content:
application/json:
schema:
$ref: "#/components/schemas/SessionRefreshFailureResponse"
examples:
not_reconnected:
summary: Client did not reconnect (legacy envelope)
value:
code: 500
data:
Details: Connection refresh completed
error: Failed to refresh connection
refreshSuccess: false
wasConnected: true
wasLoggedIn: true
newConnected: false
newLoggedIn: false
jid: 5511999999999:12@s.whatsapp.net
success: true
encoding_failed:
summary: Response could not be encoded
value:
code: 500
error: "json: unsupported value: NaN"
success: false
/session/status:
get:
tags:
- Session
summary: Get connection, pairing and configuration status
description: |
Returns a snapshot of the instance: socket and login state, connection health, stored configuration (webhook, events, skip flags, proxy, S3, RabbitMQ) and the pending passkey pairing state.
**Rules:**
- Always answers 200 for a valid token, even without a client (`hasClient: false`, `connectionHealth: no_client`).
- `connectionHealth` is derived in this order: `no_client`, `disconnected`, `connected_not_logged`, `connected`.
- `expiration` is the remaining lifetime in seconds computed from the stored expiration timestamp; without a stored expiration it is the negative current Unix time.
- `avatar_url` comes from a 24-hour cache; when it is empty and the session is logged in, the avatar is fetched in the background for the next call.
- The configuration blocks are read from the database. When that read fails, `s3_config` and `rabbitmq_config` fall back to `{"enabled": false}`.
- The response includes secrets stored for the instance (the instance `token`, the S3 access key and the RabbitMQ URL). Call it only from trusted backends; the browser-facing `GET /connector/status` removes them.
- `isFromAPI` mirrors `echo_api_messages`.
security:
- ApiKeyAuth: []
responses:
"200":
description: Status snapshot of the instance.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionStatusResponse"
examples:
connected:
summary: Paired and connected instance
value:
code: 200
data:
id: bec45bb93cbd24cbec32941ec3c93a12
name: Support Line
avatar_url: https://pps.whatsapp.net/v/t61.24694-24/example_avatar.jpg
connected: true
loggedIn: true
hasClient: true
connectionHealth: connected
lastSuccessfulConnect: 1757862000
autoReconnectErrors: 0
enableAutoReconnect: true
expiration: 86400
token: a1b2c3d4e5f6a7b8c9d0
jid: 5511999999999:12@s.whatsapp.net
webhook: https://example.com/webhook
events: Message,ReadReceipt
proxy_url: ""
qrcode: ""
skip_media_download: false
skip_groups: false
skip_newsletters: false
skip_broadcasts: true
skip_own_messages: false
echo_api_messages: false
skip_calls: false
call_reject_message: Sorry, I cannot take calls at the moment.
call_reject_type: busy
globalTransportSkips:
skipGlobalWebhook: false
skipGlobalRabbitMQ: false
skipGlobalSQS: false
skipGlobalRedis: false
skipGlobalWebSocket: false
skipGlobalS3: false
isFromAPI: false
auto_presence_unavailable: false
proxy_config:
enabled: false
proxy_url: ""
s3_config:
enabled: true
endpoint: https://s3.us-east-1.amazonaws.com
region: us-east-1
bucket: example-whatsapp-media
access_key: AKIAIOSFODNN7EXAMPLE
path_style: false
public_url: https://cdn.example.com
media_delivery: both
retention_days: 30
disable_acl: true
rabbitmq_config:
enabled: false
url: ""
exchange: ""
exchange_type: ""
queue: ""
queue_type: ""
routing_key: ""
events: ""
durable: false
auto_delete: false
exclusive: false
no_wait: false
delivery_mode: 0
dead_letter_exchange: ""
dead_letter_routing_key: ""
message_ttl: 0
max_length: 0
max_length_bytes: 0
queue_arguments: ""
exchange_arguments: ""
passkeyRequired: false
passkeyResponseSubmitted: false
passkeyConfirmed: false
passkeyConfirmationCode: ""
passkeySkipHandoffUX: false
passkeyError: ""
timestamp: 1757865600
success: true
no_client:
summary: Instance created but never connected
value:
code: 200
data:
id: 5663e0c52063ec35d0ba45f7c2011c06
name: New Instance
avatar_url: ""
connected: false
loggedIn: false
hasClient: false
connectionHealth: no_client
lastSuccessfulConnect: 0
autoReconnectErrors: 0
enableAutoReconnect: false
expiration: -1757865600
token: f0e1d2c3b4a5968778695a4b
jid: ""
webhook: ""
events: ""
proxy_url: ""
qrcode: ""
skip_media_download: false
skip_groups: false
skip_newsletters: false
skip_broadcasts: false
skip_own_messages: false
echo_api_messages: false
skip_calls: false
call_reject_message: ""
call_reject_type: ""
globalTransportSkips:
skipGlobalWebhook: false
skipGlobalRabbitMQ: false
skipGlobalSQS: false
skipGlobalRedis: false
skipGlobalWebSocket: false
skipGlobalS3: false
isFromAPI: false
auto_presence_unavailable: false
proxy_config:
enabled: false
proxy_url: ""
s3_config:
enabled: false
rabbitmq_config:
enabled: false
passkeyRequired: false
passkeyResponseSubmitted: false
passkeyConfirmed: false
passkeyConfirmationCode: ""
passkeySkipHandoffUX: false
passkeyError: ""
timestamp: 1757865600
success: true
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: the token lookup in the database failed, or the status could not be encoded."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 500
error: "sql: database is closed"
success: false
/session/pairphone:
post:
tags:
- Session
summary: Get a phone pairing code
description: |
Requests an 8-character linking code for pairing by phone number instead of scanning a QR code. The user types the code on the phone under **Linked devices > Link with phone number**.
**Rules:**
- The instance must be connected first (`POST /session/connect`) and not paired yet; a paired instance returns `400 already paired`, a missing client `500 no session`.
- `Phone` is required: the full number with country code, digits only.
- `client_type` (optional, case-insensitive) chooses the device label shown on the phone; omitted or empty keeps `chrome` ("Chrome (Linux)"). Any other value returns `400`.
- A rejection from WhatsApp (for example an invalid number or too many attempts) is returned as `400` with the upstream error text.
**Use Cases:**
- Pair headless servers without a camera
- Show a "macOS" or "Android" label instead of the default browser label
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/Pairphone"
examples:
default_chrome:
summary: Default device label
description: Without `client_type` the phone shows "Chrome (Linux)".
value:
Phone: "5511999999999"
macos_label:
summary: Show the code as a macOS device
description: The phone lists the new linked device as "macOS".
value:
Phone: "5511999999999"
client_type: macos
android_label:
summary: Show the code as an Android device
description: "`client_type` is case-insensitive, so `Android` is accepted."
value:
Phone: "5511999999999"
client_type: Android
responses:
"200":
description: Linking code generated. It must be typed on the phone before it expires.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionPairPhoneResponse"
example:
code: 200
data:
LinkingCode: 9H3J-H3J8
success: true
"400":
description: "Bad Request: invalid body, missing `Phone`, unsupported `client_type`, instance already paired, or WhatsApp rejected the pairing request."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
could_not_decode_payload:
summary: Body is not valid JSON
value:
code: 400
error: could not decode Payload
success: false
missing_phone:
summary: Phone missing
value:
code: 400
error: missing Phone in Payload
success: false
invalid_client_type:
summary: Unsupported client_type
value:
code: 400
error: "invalid client_type: accepted values are unknown, chrome, edge, firefox, ie, opera, safari, electron, uwp, otherwebclient, macos, android"
success: false
already_paired:
summary: Instance is already paired
value:
code: 400
error: already paired
success: false
upstream_rejected:
summary: WhatsApp rejected the request
value:
code: 400
error: "server returned error 429: rate-overlimit"
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: there is no client in memory; call `POST /session/connect` first."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 500
error: no session
success: false
/session/passkey/status:
get:
tags:
- Session
summary: Get the passkey pairing state
description: |
Returns the in-memory passkey pairing state of the instance: the WebAuthn challenge to sign, whether a response was submitted, and the confirmation code once WhatsApp sends it.
**Flow:**
- `POST /session/connect`, then poll this endpoint (or call `POST /session/passkey/challenge` to obtain the challenge on demand).
- Pass `challenge` verbatim to `navigator.credentials.get({publicKey})` at the origin `https://web.whatsapp.com`, then send the assertion to `POST /session/passkey/response`.
- When `confirmationCode` appears and `skipHandoffUX` is false, the user compares the code on the phone and you call `POST /session/passkey/confirm`. With `skipHandoffUX: true` the gateway confirms automatically.
**Rules:**
- Always 200 for a valid token; without any passkey activity every field has its idle value and `challenge` is `null`.
- `required` is `true` while a challenge is stored and not confirmed.
- Binary WebAuthn fields (`challenge.challenge`, `allowCredentials[].id`) are base64url without padding.
- A successful confirm clears the state, so the next call returns the idle snapshot.
security:
- ApiKeyAuth: []
responses:
"200":
description: Passkey state snapshot.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionPasskeyStatusResponse"
examples:
idle:
summary: No passkey challenge pending
value:
code: 200
data:
required: false
challenge: null
responseSubmitted: false
confirmed: false
confirmationCode: ""
skipHandoffUX: false
error: ""
success: true
challenge_pending:
summary: Challenge waiting for the WebAuthn assertion
value:
code: 200
data:
required: true
challenge:
challenge: ZmljdGl0aW91cy13ZWJhdXRobi1jaGFsbGVuZ2U
timeout: 60000
rpId: whatsapp.com
allowCredentials:
- id: Y3JlZGVudGlhbC1pZC0wMDAx
type: public-key
transports:
- internal
- hybrid
userVerification: preferred
extensions: null
responseSubmitted: false
confirmed: false
confirmationCode: ""
skipHandoffUX: false
error: ""
success: true
awaiting_confirmation:
summary: Response submitted, confirmation code received
value:
code: 200
data:
required: true
challenge:
challenge: ZmljdGl0aW91cy13ZWJhdXRobi1jaGFsbGVuZ2U
timeout: 60000
rpId: whatsapp.com
allowCredentials:
- id: Y3JlZGVudGlhbC1pZC0wMDAx
type: public-key
transports:
- internal
- hybrid
userVerification: preferred
extensions: null
responseSubmitted: true
confirmed: false
confirmationCode: "482913"
skipHandoffUX: false
error: ""
success: true
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
/session/passkey/response:
post:
tags:
- Session
summary: Submit the WebAuthn passkey assertion
description: |
Forwards the WebAuthn assertion produced by the user's authenticator to WhatsApp to continue passkey pairing.
The client must not build the `rpId` itself: it passes the `challenge` object from `GET /session/passkey/status` (which carries `rpId: whatsapp.com`) verbatim to `navigator.credentials.get()` and runs the ceremony only at the origin `https://web.whatsapp.com`.
**Rules:**
- Requires a client in memory (`500 no session`).
- Rate limit: one submission per instance every 5 seconds (`429`). The limit is consumed before the body is validated, so a rejected body also starts the window.
- Body capped at 256 KiB and decoded strictly: unknown fields or an oversized body return `400 invalid payload`.
- Required: `id`, `rawId`, `type`, `response.clientDataJSON`, `response.authenticatorData`, `response.signature`; `response.userHandle` is optional.
- `rawId` and every `response.*` value must be base64url without padding; `id` is forwarded as-is.
- A rejection from WhatsApp returns `400` with the upstream error text (30-second timeout).
- On success the state is marked `responseSubmitted`; poll the status for the confirmation code.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/main.PasskeyResponsePayload"
examples:
assertion:
summary: WebAuthn assertion without userHandle
description: Values copied from `PublicKeyCredential` and re-encoded as base64url without padding.
value:
id: Y3JlZGVudGlhbC1pZC0wMDAx
rawId: Y3JlZGVudGlhbC1pZC0wMDAx
type: public-key
response:
clientDataJSON: eyJ0eXBlIjoid2ViYXV0aG4uZ2V0Iiwib3JpZ2luIjoiaHR0cHM6Ly93ZWIud2hhdHNhcHAuY29tIn0
authenticatorData: ZmljdGl0aW91cy1hdXRoZW50aWNhdG9yLWRhdGE
signature: ZmljdGl0aW91cy1zaWduYXR1cmUtYnl0ZXM
with_user_handle:
summary: Assertion including userHandle
description: Discoverable credentials return a user handle; send it base64url-encoded when present.
value:
id: Y3JlZGVudGlhbC1pZC0wMDAx
rawId: Y3JlZGVudGlhbC1pZC0wMDAx
type: public-key
response:
clientDataJSON: eyJ0eXBlIjoid2ViYXV0aG4uZ2V0Iiwib3JpZ2luIjoiaHR0cHM6Ly93ZWIud2hhdHNhcHAuY29tIn0
authenticatorData: ZmljdGl0aW91cy1hdXRoZW50aWNhdG9yLWRhdGE
signature: ZmljdGl0aW91cy1zaWduYXR1cmUtYnl0ZXM
userHandle: dXNlci1oYW5kbGUtMDAwMQ
responses:
"200":
description: Assertion accepted by WhatsApp; wait for the confirmation code.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionPasskeySubmitResponse"
example:
code: 200
data:
status: submitted
details: Passkey response sent to WhatsApp. Await confirmation.
success: true
"400":
description: "Bad Request: invalid or oversized body, missing field, value not base64url, or WhatsApp rejected the assertion."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
invalid_payload:
summary: Unknown field, invalid JSON or body over 256 KiB
value:
code: 400
error: invalid payload
success: false
missing_id:
summary: id missing
value:
code: 400
error: id is required
success: false
missing_signature:
summary: response.signature missing
value:
code: 400
error: response.signature is required
success: false
bad_raw_id:
summary: rawId is not base64url
value:
code: 400
error: "invalid rawId: must be base64url"
success: false
bad_user_handle:
summary: userHandle is not base64url
value:
code: 400
error: "invalid userHandle: must be base64url"
success: false
upstream_rejected:
summary: WhatsApp did not accept the assertion
value:
code: 400
error: "info query returned status 401: not-authorized"
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"429":
description: "Too Many Requests: a submission was already made for this instance in the last 5 seconds."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 429
error: "rate limit exceeded: try again in 5 seconds"
success: false
"500":
description: "Internal Server Error: there is no client in memory; call `POST /session/connect` first."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 500
error: no session
success: false
/session/passkey/confirm:
post:
tags:
- Session
summary: Confirm passkey pairing
description: |
Tells WhatsApp that the user verified the passkey confirmation code on the phone, completing passkey pairing.
**Rules:**
- No request body is read.
- Needed only when `GET /session/passkey/status` reports `skipHandoffUX: false`; with `skipHandoffUX: true` the gateway sends the confirmation automatically when the code arrives.
- Requires a client in memory (`500 no session`).
- A rejection from WhatsApp, or calling it before a response was submitted, returns `400` with the upstream error text (30-second timeout).
- On success the passkey state is cleared; follow the `PairSuccess` event or `GET /session/status` until `loggedIn` is true.
security:
- ApiKeyAuth: []
responses:
"200":
description: Confirmation sent; pairing completes shortly.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionPasskeyConfirmResponse"
example:
code: 200
data:
status: confirmed
details: Passkey confirmation sent. Pairing should complete shortly.
success: true
"400":
description: "Bad Request: WhatsApp rejected the confirmation, or no passkey response was submitted before."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_response_submitted:
summary: Confirm called before submitting the assertion
value:
code: 400
error: no passkey linking cache available
success: false
upstream_rejected:
summary: WhatsApp did not accept the confirmation
value:
code: 400
error: info query timed out
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: there is no client in memory for this instance."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 500
error: no session
success: false
/session/passkey/challenge:
post:
tags:
- Session
summary: Fetch the passkey challenge on demand
description: |
Asks WhatsApp for the WebAuthn request options right away and stores them, so `GET /session/passkey/status` returns the challenge immediately instead of waiting for the `PasskeyRequest` event.
**Rules:**
- No request body is read. The instance must be connected (`POST /session/connect` first).
- Without a client the call returns `500 no session`.
- A disconnected client returns **503** `not_connected`; an account outside the passkey cohort (normal QR or phone-code accounts), or a refused request, returns **503** `passkey_unavailable` with the upstream reason. Fall back to `GET /session/qr` or `POST /session/pairphone` in that case.
- Both 503 bodies keep the legacy envelope: `success: true` at the top level and `error`/`reason` inside `data`.
- 30-second timeout for the WhatsApp request.
security:
- ApiKeyAuth: []
responses:
"200":
description: Challenge fetched and stored for this instance.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionPasskeyChallengeResponse"
example:
code: 200
data:
required: true
challenge:
challenge: ZmljdGl0aW91cy13ZWJhdXRobi1jaGFsbGVuZ2U
timeout: 60000
rpId: whatsapp.com
allowCredentials:
- id: Y3JlZGVudGlhbC1pZC0wMDAx
type: public-key
transports:
- internal
- hybrid
userVerification: preferred
extensions: null
success: true
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: there is no client in memory for this instance."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 500
error: no session
success: false
"503":
description: "Service Unavailable (legacy envelope, `success: true`): the client is not connected, or passkey pairing is not available for this account."
content:
application/json:
schema:
$ref: "#/components/schemas/SessionPasskeyUnavailableResponse"
examples:
not_connected:
summary: Client is not connected
value:
code: 503
data:
error: not_connected
reason: connect the instance before probing the passkey challenge
success: true
passkey_unavailable:
summary: Account outside the passkey cohort
value:
code: 503
data:
error: passkey_unavailable
reason: "info query returned status 404: item-not-found"
success: true
/session/connector/token:
post:
tags:
- Connector
summary: Mint an ephemeral Connector token
description: |
Issues a short-lived token bound to this instance for the embeddable Connector widget, so the browser never receives the real instance token.
**Rules:**
- Call it from your backend with the real instance token; hand only `data.token` to the browser (for example `ZZ.connector.open({ token })`).
- The token starts with `ct_`, lives for `CONNECTOR_TOKEN_TTL` seconds (default 600) and is accepted only on `/connector/*` routes, in the `token` header or the `token` query parameter.
- Tokens are kept in memory: a gateway restart invalidates them.
- Rate limit per real token: `CONNECTOR_TOKEN_RATE_PER_MIN` mints per minute (default 60); above it the call returns `429`.
- No request body is read.
security:
- ApiKeyAuth: []
responses:
"200":
description: Ephemeral token issued.
content:
application/json:
schema:
$ref: "#/components/schemas/ConnectorTokenResponse"
example:
code: 200
data:
token: ct_Qm9ndXNFeGFtcGxlVG9rZW5WYWx1ZTAwMDAwMDAwMDAwMA
expiresIn: 600
tokenType: connector
success: true
"401":
description: Missing or invalid real instance token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"429":
description: "Too Many Requests: the per-token mint limit for the current minute was reached."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 429
error: "mint rate limit exceeded: try again shortly"
success: false
"500":
description: "Internal Server Error: random bytes for the token could not be generated."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 500
error: "read /dev/urandom: resource temporarily unavailable"
success: false
/connector/connect:
post:
tags:
- Connector
summary: "[Connector] Connect the instance"
description: |
Browser-facing version of `POST /session/connect`: the embeddable widget starts the WhatsApp client with an ephemeral Connector token instead of the real instance token.
**Rules:**
- Authenticate with the `ct_...` token from `POST /session/connector/token` (header `token` or `?token=`); an unknown or expired token returns `401`.
- Same body, side effects and errors as `POST /session/connect`: the body is required (send at least `{}`), `Subscribe` replaces the stored subscription and an omitted list clears it, and `Immediate: false` blocks for about 10 seconds.
- Nothing is redacted: `data.webhook` and `data.jid` are returned to the browser. Prefer `Immediate: true` and poll `GET /connector/status`.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/Connect"
examples:
widget_immediate:
summary: Start pairing and return immediately
description: The widget keeps the stored subscription it sends and polls the status afterwards.
value:
Subscribe:
- Message
Immediate: true
widget_wait:
summary: Wait up to 10 seconds for the socket
description: Answers 500 `failed to connect` when the socket is not connected after the wait.
value:
Subscribe:
- All
Immediate: false
responses:
"200":
description: Client started for the instance bound to the Connector token.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionConnectResponse"
example:
code: 200
data:
details: Connected!
events: Message
jid: ""
skip_media_download: false
webhook: https://example.com/webhook
success: true
"400":
description: "Bad Request: the body is empty or not valid JSON."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 400
error: could not decode Payload
success: false
"401":
description: Connector token missing, unknown or expired (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: the client is already connected, or the socket did not connect within the wait."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
already_connected:
summary: A connected client already exists
value:
code: 500
error: already connected
success: false
failed_to_connect:
summary: Socket not connected after the wait
value:
code: 500
error: failed to connect
success: false
/connector/disconnect:
post:
tags:
- Connector
summary: "[Connector] Disconnect the instance"
description: |
Lets the Connector widget close the WhatsApp socket (for example when the user cancels pairing) without holding the real instance token.
**Rules:**
- Accepts only a valid, unexpired ephemeral token minted by `POST /session/connector/token`; otherwise `401`.
- Runs the `POST /session/disconnect` handler: no body, `500 no session` without a client, a synthetic `Disconnected` webhook event when the client was connected or logged in.
- The paired session is kept; the stored QR code is cleared.
security:
- ApiKeyAuth: []
responses:
"200":
description: Client disconnected; the paired session is kept.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionDisconnectResponse"
example:
code: 200
data:
Details: Disconnected successfully
wasConnected: true
wasLoggedIn: false
success: true
"401":
description: Connector token missing, unknown or expired (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: there is no client in memory for the instance."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 500
error: no session
success: false
/connector/status:
get:
tags:
- Connector
summary: "[Connector] Get the redacted connection status"
description: |
Returns the connection and pairing snapshot the widget needs to drive its UI, with every credential of the instance removed.
**Rules:**
- Requires the ephemeral `ct_...` token (header `token` or query `token`); the real instance token is rejected here with `401`.
- Same snapshot as `GET /session/status` except that `token`, `webhook`, `events`, `proxy_url`, `proxy_config`, `s3_config` and `rabbitmq_config` are removed.
- Use `connected`, `loggedIn`, `connectionHealth`, `qrcode` and the `passkey*` fields to decide which pairing step to show.
security:
- ApiKeyAuth: []
responses:
"200":
description: Redacted status snapshot.
content:
application/json:
schema:
$ref: "#/components/schemas/ConnectorStatusResponse"
example:
code: 200
data:
id: bec45bb93cbd24cbec32941ec3c93a12
name: Support Line
avatar_url: ""
connected: true
loggedIn: false
hasClient: true
connectionHealth: connected_not_logged
lastSuccessfulConnect: 1757862000
autoReconnectErrors: 0
enableAutoReconnect: true
expiration: 86400
jid: ""
qrcode: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAQAAAAEAAQMAAABmvDolAAAABlBMVEX///8AAABVwtN+AAAA
skip_media_download: false
skip_groups: false
skip_newsletters: false
skip_broadcasts: false
skip_own_messages: false
echo_api_messages: false
skip_calls: false
call_reject_message: ""
call_reject_type: ""
globalTransportSkips:
skipGlobalWebhook: false
skipGlobalRabbitMQ: false
skipGlobalSQS: false
skipGlobalRedis: false
skipGlobalWebSocket: false
skipGlobalS3: false
isFromAPI: false
auto_presence_unavailable: false
passkeyRequired: false
passkeyResponseSubmitted: false
passkeyConfirmed: false
passkeyConfirmationCode: ""
passkeySkipHandoffUX: false
passkeyError: ""
timestamp: 1757865600
success: true
"401":
description: Connector token missing, unknown or expired (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: the token lookup in the database failed, or the status could not be encoded."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 500
error: "sql: database is closed"
success: false
/connector/qr:
get:
tags:
- Connector
summary: "[Connector] Get the pairing QR code"
description: |
Returns the current pairing QR code so the widget can render it in the browser while the user scans it on the phone.
**Rules:**
- Authenticated by the short-lived Connector token only (header or query `token`); `401` once it expires.
- Runs the `GET /session/qr` handler: the client must be connected and not logged in (`500 no session`, `500 not connected`, `500 already logged in`).
- The code rotates every few seconds; poll it or follow `GET /connector/status` (`qrcode`).
security:
- ApiKeyAuth: []
responses:
"200":
description: Current QR code (empty strings until the first code is generated).
content:
application/json:
schema:
$ref: "#/components/schemas/SessionQRResponse"
examples:
qr_available:
summary: QR code ready to scan
value:
code: 200
data:
QRCode: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAQAAAAEAAQMAAABmvDolAAAABlBMVEX///8AAABVwtN+AAAA
code: 2@Xq3example0000QrTextValue,Zq9exampleNoiseKey=,Kp2exampleIdentityKey=,Tt5exampleAdvSecret=,1
success: true
not_generated_yet:
summary: Connected, first code not generated yet
value:
code: 200
data:
QRCode: ""
code: ""
success: true
"401":
description: Connector token missing, unknown or expired (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: no client, client not connected, instance already logged in, or the stored QR code could not be read."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: No client in memory
value:
code: 500
error: no session
success: false
not_connected:
summary: Client exists but is not connected
value:
code: 500
error: not connected
success: false
already_logged_in:
summary: Instance is already paired
value:
code: 500
error: already logged in
success: false
/connector/pairphone:
post:
tags:
- Connector
summary: "[Connector] Get a phone pairing code"
description: |
Requests a phone linking code from the widget, for users who pair by typing a code instead of scanning the QR.
**Rules:**
- Send the ephemeral token (not the real instance token) in the `token` header or query; expired tokens get `401`.
- Same body, rules and errors as `POST /session/pairphone`: `Phone` required, optional case-insensitive `client_type` (default `chrome`), `400 already paired` for a paired instance and `500 no session` without a client.
- WhatsApp rejections come back as `400` with the upstream text.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/Pairphone"
examples:
default_chrome:
summary: Default device label
description: Without `client_type` the phone shows "Chrome (Linux)".
value:
Phone: "5511999999999"
macos_label:
summary: Show the code as a macOS device
description: The phone lists the new linked device as "macOS".
value:
Phone: "5511999999999"
client_type: macos
responses:
"200":
description: Linking code generated.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionPairPhoneResponse"
example:
code: 200
data:
LinkingCode: 9H3J-H3J8
success: true
"400":
description: "Bad Request: invalid body, missing `Phone`, unsupported `client_type`, instance already paired, or WhatsApp rejected the request."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
could_not_decode_payload:
summary: Body is not valid JSON
value:
code: 400
error: could not decode Payload
success: false
missing_phone:
summary: Phone missing
value:
code: 400
error: missing Phone in Payload
success: false
invalid_client_type:
summary: Unsupported client_type
value:
code: 400
error: "invalid client_type: accepted values are unknown, chrome, edge, firefox, ie, opera, safari, electron, uwp, otherwebclient, macos, android"
success: false
already_paired:
summary: Instance is already paired
value:
code: 400
error: already paired
success: false
"401":
description: Connector token missing, unknown or expired (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: there is no client in memory; connect first."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 500
error: no session
success: false
/connector/passkey/status:
get:
tags:
- Connector
summary: "[Connector] Get the passkey pairing state"
description: |
Returns the passkey pairing state to the widget, which runs the WebAuthn ceremony in the browser with the challenge it contains.
**Rules:**
- Auth: a `ct_...` Connector token that has not expired, in the `token` header or query; else `401`.
- Same snapshot as `GET /session/passkey/status`; it holds no credentials, so nothing is redacted.
- Pass `challenge` verbatim to `navigator.credentials.get({publicKey})` at the origin `https://web.whatsapp.com`.
security:
- ApiKeyAuth: []
responses:
"200":
description: Passkey state snapshot.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionPasskeyStatusResponse"
examples:
idle:
summary: No passkey challenge pending
value:
code: 200
data:
required: false
challenge: null
responseSubmitted: false
confirmed: false
confirmationCode: ""
skipHandoffUX: false
error: ""
success: true
challenge_pending:
summary: Challenge waiting for the WebAuthn assertion
value:
code: 200
data:
required: true
challenge:
challenge: ZmljdGl0aW91cy13ZWJhdXRobi1jaGFsbGVuZ2U
timeout: 60000
rpId: whatsapp.com
allowCredentials:
- id: Y3JlZGVudGlhbC1pZC0wMDAx
type: public-key
transports:
- internal
- hybrid
userVerification: preferred
extensions: null
responseSubmitted: false
confirmed: false
confirmationCode: ""
skipHandoffUX: false
error: ""
success: true
"401":
description: Connector token missing, unknown or expired (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
/connector/passkey/challenge:
post:
tags:
- Connector
summary: "[Connector] Fetch the passkey challenge on demand"
description: |
Lets the widget force WhatsApp to issue the WebAuthn challenge immediately, so the passkey tab does not wait for the reactive `PasskeyRequest` event.
**Rules:**
- The ephemeral token minted for this instance is the only accepted credential (header or query `token`); `401` otherwise.
- Runs the `POST /session/passkey/challenge` handler: no body, the instance must be connected.
- **503** bodies (`not_connected`, `passkey_unavailable`) keep the legacy envelope with `success: true`; on `passkey_unavailable` the widget should switch to the QR or phone-code tab.
security:
- ApiKeyAuth: []
responses:
"200":
description: Challenge fetched and stored.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionPasskeyChallengeResponse"
example:
code: 200
data:
required: true
challenge:
challenge: ZmljdGl0aW91cy13ZWJhdXRobi1jaGFsbGVuZ2U
timeout: 60000
rpId: whatsapp.com
allowCredentials:
- id: Y3JlZGVudGlhbC1pZC0wMDAx
type: public-key
transports:
- internal
- hybrid
userVerification: preferred
extensions: null
success: true
"401":
description: Connector token missing, unknown or expired (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: there is no client in memory for the instance."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 500
error: no session
success: false
"503":
description: "Service Unavailable (legacy envelope, `success: true`): client not connected, or passkey pairing not available for the account."
content:
application/json:
schema:
$ref: "#/components/schemas/SessionPasskeyUnavailableResponse"
examples:
not_connected:
summary: Client is not connected
value:
code: 503
data:
error: not_connected
reason: connect the instance before probing the passkey challenge
success: true
passkey_unavailable:
summary: Account outside the passkey cohort
value:
code: 503
data:
error: passkey_unavailable
reason: "info query returned status 404: item-not-found"
success: true
/connector/passkey/response:
post:
tags:
- Connector
summary: "[Connector] Submit the WebAuthn passkey assertion"
description: |
Receives the assertion that the browser obtained from `navigator.credentials.get()` and forwards it to WhatsApp on behalf of the widget.
**Rules:**
- Use the Connector token issued by your backend (header or query `token`); a missing or expired one is answered with `401`.
- Same strict body and errors as `POST /session/passkey/response`: 256 KiB cap, unknown fields rejected, base64url without padding for `rawId` and `response.*`, one submission every 5 seconds (`429`).
- After `200`, poll `GET /connector/passkey/status` for the confirmation code.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/main.PasskeyResponsePayload"
examples:
assertion:
summary: WebAuthn assertion without userHandle
description: Binary values from `PublicKeyCredential` re-encoded as base64url without padding.
value:
id: Y3JlZGVudGlhbC1pZC0wMDAx
rawId: Y3JlZGVudGlhbC1pZC0wMDAx
type: public-key
response:
clientDataJSON: eyJ0eXBlIjoid2ViYXV0aG4uZ2V0Iiwib3JpZ2luIjoiaHR0cHM6Ly93ZWIud2hhdHNhcHAuY29tIn0
authenticatorData: ZmljdGl0aW91cy1hdXRoZW50aWNhdG9yLWRhdGE
signature: ZmljdGl0aW91cy1zaWduYXR1cmUtYnl0ZXM
with_user_handle:
summary: Assertion including userHandle
description: Send `userHandle` when the authenticator returns one.
value:
id: Y3JlZGVudGlhbC1pZC0wMDAx
rawId: Y3JlZGVudGlhbC1pZC0wMDAx
type: public-key
response:
clientDataJSON: eyJ0eXBlIjoid2ViYXV0aG4uZ2V0Iiwib3JpZ2luIjoiaHR0cHM6Ly93ZWIud2hhdHNhcHAuY29tIn0
authenticatorData: ZmljdGl0aW91cy1hdXRoZW50aWNhdG9yLWRhdGE
signature: ZmljdGl0aW91cy1zaWduYXR1cmUtYnl0ZXM
userHandle: dXNlci1oYW5kbGUtMDAwMQ
responses:
"200":
description: Assertion accepted by WhatsApp.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionPasskeySubmitResponse"
example:
code: 200
data:
status: submitted
details: Passkey response sent to WhatsApp. Await confirmation.
success: true
"400":
description: "Bad Request: invalid or oversized body, missing field, value not base64url, or WhatsApp rejected the assertion."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
invalid_payload:
summary: Unknown field, invalid JSON or body over 256 KiB
value:
code: 400
error: invalid payload
success: false
missing_type:
summary: type missing
value:
code: 400
error: type is required
success: false
bad_signature:
summary: signature is not base64url
value:
code: 400
error: "invalid signature: must be base64url"
success: false
upstream_rejected:
summary: WhatsApp did not accept the assertion
value:
code: 400
error: "info query returned status 401: not-authorized"
success: false
"401":
description: Connector token missing, unknown or expired (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"429":
description: "Too Many Requests: a submission was already made for this instance in the last 5 seconds."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 429
error: "rate limit exceeded: try again in 5 seconds"
success: false
"500":
description: "Internal Server Error: there is no client in memory for the instance."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 500
error: no session
success: false
/connector/passkey/confirm:
post:
tags:
- Connector
summary: "[Connector] Confirm passkey pairing"
description: |
Sends the final passkey confirmation from the widget after the user compared the confirmation code on the phone.
**Rules:**
- Authorized by the ephemeral Connector token (header or query `token`), never by the real instance token; `401` when it is not valid.
- Needed only when the status reports `skipHandoffUX: false`; otherwise the gateway already confirmed.
- Runs the `POST /session/passkey/confirm` handler: no body, `400` with the upstream text when WhatsApp refuses, `500 no session` without a client.
security:
- ApiKeyAuth: []
responses:
"200":
description: Confirmation sent; pairing completes shortly.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionPasskeyConfirmResponse"
example:
code: 200
data:
status: confirmed
details: Passkey confirmation sent. Pairing should complete shortly.
success: true
"400":
description: "Bad Request: WhatsApp rejected the confirmation, or no passkey response was submitted before."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_response_submitted:
summary: Confirm called before submitting the assertion
value:
code: 400
error: no passkey linking cache available
success: false
key_not_ready:
summary: Confirmation code not received yet
value:
code: 400
error: passkey linking cache does not have an encryption key yet
success: false
"401":
description: Connector token missing, unknown or expired (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: there is no client in memory for the instance."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 500
error: no session
success: false
/session/import:
post:
tags:
- Session
summary: Import an existing web.whatsapp.com session (BETA)
description: |
Converts a web.whatsapp.com device identity into a native device of this instance and boots it, as an alternative to QR, phone-code or passkey pairing. The payload is impersonation-grade key material: guard this endpoint and never log the body.
**Rules:**
- Body up to 16 MiB. A body with `meJid` is parsed as a structured `WebDeviceSnapshot`; a body with `source: wa-web` or an `indexeddb` object is treated as a generic companion dump; anything else returns `400`.
- Structured snapshot, required: `meJid`, non-zero `registrationId`, `noiseKey.priv`, `identityKey.priv`, `signedPreKey.priv` (32 bytes), `signedPreKey.signature` (64 bytes) and the four `account` fields. Key material is base64 (standard or URL alphabet, padded or not); `pub` values are ignored because they are derived from `priv`.
- Optional: `lid`, `advSecretKey` (a random key is kept when omitted), `platform`, `pushName`, `businessName`.
- Invalid key material returns `422 snapshot conversion failed: ...`.
- **Generic dump:** automatic extraction is not implemented yet, so a dump is always answered with `422` listing the missing fields (legacy envelope, `success: true`). Nothing is fabricated.
- On success the device is stored, `users.jid` is updated and the client starts in the background with the `Message` subscription only. Poll `GET /session/status` until `loggedIn` is true and call `POST /session/connect` to set the subscription you need.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/main.WebDeviceSnapshot"
examples:
structured_snapshot:
summary: Structured snapshot with every field
description: All key material in base64. The values are synthetic and do not open a real session.
value:
meJid: 5511999999999:12@s.whatsapp.net
lid: 123456789012345:12@lid
registrationId: 12345
noiseKey:
priv: AQIDBAUGBwgJCgsMDQ4PEBESExQVFhcYGRobHB0eHyA=
identityKey:
priv: ISIjJCUmJygpKissLS4vMDEyMzQ1Njc4OTo7PD0+P0A=
signedPreKey:
keyId: 1
priv: QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVpbXF1eX2A=
signature: YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXp7fH1+f4CBgoOEhYaHiImKi4yNjo+QkZKTlJWWl5iZmpucnZ6foA==
account:
details: CwwNDg8QERITFBUWFxgZGhscHR4fICEiIyQlJicoKSorLC0uLzAxMjM0NTY3ODk6
accountSignature: FRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vMDEyMzQ1Njc4OTo7PD0+P0BBQkNERUZHSElKS0xNTk9QUVJTVA==
accountSignatureKey: HyAhIiMkJSYnKCkqKywtLi8wMTIzNDU2Nzg5Ojs8PT4=
deviceSignature: KSorLC0uLzAxMjM0NTY3ODk6Ozw9Pj9AQUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVpbXF1eX2BhYmNkZWZnaA==
advSecretKey: MzQ1Njc4OTo7PD0+P0BBQkNERUZHSElKS0xNTk9QUVI=
platform: chrome
pushName: Support Line
businessName: ""
minimal_snapshot:
summary: Only the required fields
description: Without `advSecretKey` a fresh random ADV secret is kept; `lid`, `platform` and names stay empty.
value:
meJid: 5511999999999:12@s.whatsapp.net
registrationId: 12345
noiseKey:
priv: AQIDBAUGBwgJCgsMDQ4PEBESExQVFhcYGRobHB0eHyA=
identityKey:
priv: ISIjJCUmJygpKissLS4vMDEyMzQ1Njc4OTo7PD0+P0A=
signedPreKey:
keyId: 1
priv: QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVpbXF1eX2A=
signature: YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXp7fH1+f4CBgoOEhYaHiImKi4yNjo+QkZKTlJWWl5iZmpucnZ6foA==
account:
details: CwwNDg8QERITFBUWFxgZGhscHR4fICEiIyQlJicoKSorLC0uLzAxMjM0NTY3ODk6
accountSignature: FRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vMDEyMzQ1Njc4OTo7PD0+P0BBQkNERUZHSElKS0xNTk9QUVJTVA==
accountSignatureKey: HyAhIiMkJSYnKCkqKywtLi8wMTIzNDU2Nzg5Ojs8PT4=
deviceSignature: KSorLC0uLzAxMjM0NTY3ODk6Ozw9Pj9AQUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVpbXF1eX2BhYmNkZWZnaA==
wa_web_dump:
summary: Generic companion dump (always answered with 422)
description: Recognized by `source` or `indexeddb`; the extractor reports the identity fields it cannot resolve.
value:
source: wa-web
indexeddb:
wawc: {}
responses:
"200":
description: Device stored; the client is booting in the background.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionImportResponse"
example:
code: 200
data:
status: imported
jid: 5511999999999:12@s.whatsapp.net
note: device booting (BETA); poll /session/status for loggedIn
success: true
"400":
description: "Bad Request: the body could not be read (or exceeds 16 MiB), is not JSON, or matches neither accepted shape."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
could_not_read_body:
summary: Body unreadable or over 16 MiB
value:
code: 400
error: could not read body
success: false
invalid_json:
summary: Body is not valid JSON
value:
code: 400
error: invalid JSON
success: false
invalid_snapshot:
summary: meJid present but a field has the wrong type
value:
code: 400
error: invalid snapshot
success: false
unrecognized_payload:
summary: Neither a snapshot nor a wa-web dump
value:
code: 400
error: "unrecognized import payload: expected a WebDeviceSnapshot or a wa-web dump"
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"422":
description: "Unprocessable Entity: the snapshot key material is invalid (error envelope), or a generic dump could not be converted (legacy envelope with `success: true` and details in `data`)."
content:
application/json:
schema:
$ref: "#/components/schemas/SessionImportUnprocessableResponse"
examples:
conversion_failed:
summary: Invalid key material in the snapshot
value:
code: 422
error: "snapshot conversion failed: noiseKey: priv: expected 32 bytes, got 16"
success: false
missing_registration_id:
summary: registrationId missing or zero
value:
code: 422
error: "snapshot conversion failed: registrationId is required and must be non-zero"
success: false
incomplete_dump:
summary: Generic dump without resolvable identity fields
value:
code: 422
data:
error: "incomplete wa-web dump: auto-extraction could not resolve required fields"
missing:
- meJid
- registrationId
- noiseKey
- identityKey
- signedPreKey
- account
hint: supply a structured WebDeviceSnapshot (meJid, registrationId, noiseKey, identityKey, signedPreKey, account) β see docs/session-import.md
success: true
"500":
description: "Internal Server Error: the device store is not initialized, or the device could not be persisted."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
container_not_initialized:
summary: Device store not initialized
value:
code: 500
error: whatsmeow container not initialized
success: false
persist_failed:
summary: Device could not be stored
value:
code: 500
error: "persist device: sql: database is closed"
success: false
/session/qr:
get:
tags:
- Session
summary: Get the pairing QR code
description: |
Returns the current pairing QR code of a connected instance that is not logged in yet, as a PNG data URL and as the raw code text.
**Rules:**
- Call `POST /session/connect` first. Without a client the call returns `500 no session`; with a disconnected client `500 not connected`.
- A logged-in instance returns `500 already logged in`.
- WhatsApp rotates the code every few seconds; poll this endpoint or subscribe to the `QR` event instead of caching it.
- Right after connecting, before the first code is generated, both fields can be empty strings.
- `code` is the raw text encoded in the QR image, useful for rendering the QR yourself.
security:
- ApiKeyAuth: []
responses:
"200":
description: Current QR code (empty strings until the first code is generated).
content:
application/json:
schema:
$ref: "#/components/schemas/SessionQRResponse"
examples:
qr_available:
summary: QR code ready to scan
value:
code: 200
data:
QRCode: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAQAAAAEAAQMAAABmvDolAAAABlBMVEX///8AAABVwtN+AAAA
code: 2@Xq3example0000QrTextValue,Zq9exampleNoiseKey=,Kp2exampleIdentityKey=,Tt5exampleAdvSecret=,1
success: true
not_generated_yet:
summary: Connected, first code not generated yet
value:
code: 200
data:
QRCode: ""
code: ""
success: true
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: no client, client not connected, instance already logged in, or the stored QR code could not be read."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: No client in memory
value:
code: 500
error: no session
success: false
not_connected:
summary: Client exists but is not connected
value:
code: 500
error: not connected
success: false
already_logged_in:
summary: Instance is already paired
value:
code: 500
error: already logged in
success: false
database_error:
summary: Stored QR code could not be read
value:
code: 500
error: "sql: database is closed"
success: false
/session/network-route:
post:
tags:
- Session Network Route
summary: Provision or update the mobile network route
operationId: applySessionNetworkRoute
description: |
Provisions an isolated `tsnet` node for this session that egresses through a stable Tailscale exit node (typically a phone on mobile data), then reconnects the WhatsApp client through it.
**Features:**
- The current client is disconnected before the route is prepared; the node starts, selects the exit node, opens an authenticated SOCKS5 listener on `127.0.0.1` and runs a SOCKS/TLS preflight.
- When the client was connected before and the route becomes ready, a reconnect is scheduled (`reconnectScheduled: true`).
- `authKey` is write-only: used once during node start, never persisted, returned or logged.
**Rules:**
- Strict body: unknown fields or invalid JSON return `400 network_route_payload_invalid`.
- `mode` must be `mobile` and `tcpOnly` must be `true`; native Calls/UDP stay disabled while the route exists.
- `failClosed` is a plain boolean and **omitting it means `false`**: while the route is not ready the session may leave through the default egress (legacy proxy or direct). Send `true` to hold traffic instead.
- `exitNodeId`: 3-128 characters `[A-Za-z0-9_-]`. `idempotencyKey`: 8-160 characters `[A-Za-z0-9._:-]`. `authKey`: 12-512 printable characters starting with `tskey-auth-`.
- `routeVersion` is a fencing token (>= 1). A lower version returns `409 network_route_stale_version`; the same version with a different configuration or key returns `409 network_route_version_conflict`; an exact retry returns the current state (200 when ready, 503 with the stored error code when not).
- A failed start leaves the route `blocked` (`503 network_route_prepare_failed`, redacted cause in `details`). Retry with a higher `routeVersion` and a new one-use auth key, or remove the route.
- Error bodies raised by the route manager also carry `data` with the route state; for validation errors that state is empty.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/main.NetworkRouteRequest"
examples:
first_apply_fail_closed:
summary: First route, hold traffic while not ready
description: Version 1 with `failClosed` true, so nothing leaves through another IP while the exit node is unavailable.
value:
mode: mobile
authKey: tskey-auth-kExample0000CNTRL-ExampleSecretValue0000
exitNodeId: nStableMobileExit01
routeVersion: 1
idempotencyKey: route-2026-09-15-0001
failClosed: true
tcpOnly: true
new_version_fail_open:
summary: New version that falls back to the default egress
description: A higher `routeVersion` with a new auth key; omitting `failClosed` would have the same fail-open effect as `false`.
value:
mode: mobile
authKey: tskey-auth-kExample0001CNTRL-ExampleSecretValue0001
exitNodeId: nStableMobileExit02
routeVersion: 2
idempotencyKey: route-2026-09-15-0002
failClosed: false
tcpOnly: true
responses:
"200":
description: Route ready, or an exact retry of the current version that is already ready.
content:
application/json:
schema:
$ref: "#/components/schemas/NetworkRouteApplyResponse"
examples:
ready_reconnect:
summary: Route ready, client reconnect scheduled
value:
code: 200
data:
mode: mobile
exitNodeId: nStableMobileExit01
desiredVersion: 1
appliedVersion: 1
failClosed: true
tcpOnly: true
status: ready
ready: true
details: network route ready
reconnectScheduled: true
success: true
idempotent_retry:
summary: Exact retry of the ready version
value:
code: 200
data:
mode: mobile
exitNodeId: nStableMobileExit01
desiredVersion: 1
appliedVersion: 1
failClosed: true
tcpOnly: true
status: ready
ready: true
details: network route ready
reconnectScheduled: false
success: true
"400":
description: "Bad Request: invalid JSON or unknown field, or a field failed validation. Validation errors carry an empty `data` route state."
content:
application/json:
schema:
$ref: "#/components/schemas/NetworkRouteErrorResponse"
examples:
payload_invalid:
summary: Invalid JSON or unknown field
value:
code: 400
error: network_route_payload_invalid
success: false
tcp_only_required:
summary: tcpOnly is not true
value:
code: 400
data:
mode: ""
exitNodeId: ""
desiredVersion: 0
appliedVersion: 0
failClosed: false
tcpOnly: false
status: ""
ready: false
error: network_route_mobile_requires_tcp_only
success: false
auth_key_invalid:
summary: authKey missing or malformed
value:
code: 400
data:
mode: ""
exitNodeId: ""
desiredVersion: 0
appliedVersion: 0
failClosed: false
tcpOnly: false
status: ""
ready: false
error: network_route_auth_key_invalid
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"409":
description: "Conflict: fencing or idempotency violation; the stored route is not changed. `data` holds the stored route."
content:
application/json:
schema:
$ref: "#/components/schemas/NetworkRouteErrorResponse"
examples:
stale_version:
summary: routeVersion lower than the stored version
value:
code: 409
data:
mode: mobile
exitNodeId: nStableMobileExit01
desiredVersion: 3
appliedVersion: 3
failClosed: true
tcpOnly: true
status: ready
ready: true
error: network_route_stale_version
success: false
version_conflict:
summary: Same version, different configuration or idempotency key
value:
code: 409
data:
mode: mobile
exitNodeId: nStableMobileExit01
desiredVersion: 3
appliedVersion: 3
failClosed: true
tcpOnly: true
status: ready
ready: true
error: network_route_version_conflict
success: false
"503":
description: "Service Unavailable: route manager or store unavailable, the client could not be stopped, the node failed to start (route left `blocked`), or an exact retry of a version that is not ready."
content:
application/json:
schema:
$ref: "#/components/schemas/NetworkRouteErrorResponse"
examples:
prepare_failed:
summary: Node start or preflight failed; route blocked
value:
code: 503
data:
mode: mobile
exitNodeId: nStableMobileExit01
desiredVersion: 2
appliedVersion: 1
failClosed: true
tcpOnly: true
status: blocked
ready: false
errorCode: network_route_prepare_failed
details: "exit node nStableMobileExit01 is offline"
error: network_route_prepare_failed
success: false
manager_unavailable:
summary: Route manager not initialized in this process
value:
code: 503
error: network_route_manager_unavailable
success: false
not_ready_retry:
summary: Exact retry of a blocked version
value:
code: 503
data:
mode: mobile
exitNodeId: nStableMobileExit01
desiredVersion: 2
appliedVersion: 1
failClosed: true
tcpOnly: true
status: blocked
ready: false
errorCode: network_route_prepare_failed
error: network_route_prepare_failed
success: false
get:
tags:
- Session Network Route
summary: Get the mobile network route state
operationId: getSessionNetworkRoute
description: |
Returns the non-secret state of this session's mobile route: desired and applied versions, fail mode, status and live readiness. With `probe=egress` it also proves the public IP the route really exits from.
**Rules:**
- Never returns the auth key, SOCKS credentials, proxy URL or state paths.
- `ready: true` requires `status: ready`, `desiredVersion == appliedVersion` and a live node for that version in this process; after a gateway restart it stays false until the node is restored.
- `probe=egress` makes a real external request through the route (10-second timeout) and adds `egressIP` at the top level. When the probe fails the call still answers 200 with `egressProbeError` instead. Any other `probe` value is ignored.
- `404 network_route_not_configured` when the session has no route.
security:
- ApiKeyAuth: []
parameters:
- in: query
name: probe
required: false
description: Send `egress` to measure the route's real public exit IP (external request). Other values only return the stored state.
schema:
type: string
enum:
- egress
example: egress
responses:
"200":
description: Route state, plus `egressIP` or `egressProbeError` when `probe=egress`.
content:
application/json:
schema:
$ref: "#/components/schemas/NetworkRouteGetResponse"
examples:
state:
summary: Route state without probe
value:
code: 200
data:
mode: mobile
exitNodeId: nStableMobileExit01
desiredVersion: 3
appliedVersion: 3
failClosed: true
tcpOnly: true
status: ready
ready: true
success: true
egress_probe:
summary: probe=egress succeeded
value:
code: 200
data:
mode: mobile
exitNodeId: nStableMobileExit01
desiredVersion: 3
appliedVersion: 3
failClosed: true
tcpOnly: true
status: ready
ready: true
egressIP: 203.0.113.45
success: true
egress_probe_failed:
summary: probe=egress failed (route not active)
value:
code: 200
data:
mode: mobile
exitNodeId: nStableMobileExit01
desiredVersion: 2
appliedVersion: 1
failClosed: true
tcpOnly: true
status: blocked
ready: false
errorCode: network_route_prepare_failed
egressProbeError: network_route_egress_probe_failed
success: true
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"404":
description: "Not Found: no mobile route is configured for this session."
content:
application/json:
schema:
$ref: "#/components/schemas/NetworkRouteErrorResponse"
example:
code: 404
error: network_route_not_configured
success: false
"503":
description: "Service Unavailable: the route manager is not initialized, or the route metadata could not be read."
content:
application/json:
schema:
$ref: "#/components/schemas/NetworkRouteErrorResponse"
examples:
manager_unavailable:
summary: Route manager not initialized
value:
code: 503
error: network_route_manager_unavailable
success: false
store_unavailable:
summary: Route metadata unreadable
value:
code: 503
error: network_route_store_unavailable
success: false
delete:
tags:
- Session Network Route
summary: Remove the mobile network route
operationId: removeSessionNetworkRoute
description: |
Removes this session's mobile route on explicit operator request: the live node is logged out and closed, the stored row is deleted and the state directory is wiped. Afterwards the session egresses through its legacy `proxy_url`, or directly when none is set, so the peer sees a different IP.
**Rules:**
- No body. The client is disconnected first and any stored QR code is cleared.
- `data` is the route as read right before removal.
- A reconnect is scheduled (`reconnectScheduled: true`) when the client was connected, or when a fail-closed route that was not ready had been holding the session offline, so a fresh QR code is produced. A session stopped on purpose over a healthy route stays stopped.
- Idempotent by absence: a second call returns `404 network_route_not_configured`.
- `503 network_route_revoke_failed` may leave a partial removal; repeat the call, and a `404` then confirms the route is gone.
- The next apply accepts any valid `routeVersion` and needs a new one-use auth key.
**Use Cases:**
- Unblock a session held offline by a route that will not converge (`status: blocked`)
- Recover after the route runtime did not come back from a gateway restart
security:
- ApiKeyAuth: []
responses:
"200":
description: Route removed; `data` is its last state.
content:
application/json:
schema:
$ref: "#/components/schemas/NetworkRouteApplyResponse"
example:
code: 200
data:
mode: mobile
exitNodeId: nStableMobileExit01
desiredVersion: 4
appliedVersion: 3
failClosed: true
tcpOnly: true
status: blocked
ready: false
errorCode: network_route_prepare_failed
details: "network route removed; this session egresses through its legacy proxy_url on the next connect, or directly when none is set"
reconnectScheduled: true
success: true
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"404":
description: "Not Found: no route is configured (also the answer to a repeated removal)."
content:
application/json:
schema:
$ref: "#/components/schemas/NetworkRouteErrorResponse"
example:
code: 404
error: network_route_not_configured
success: false
"503":
description: "Service Unavailable: route manager not initialized, metadata unreadable, or the removal failed."
content:
application/json:
schema:
$ref: "#/components/schemas/NetworkRouteErrorResponse"
examples:
manager_unavailable:
summary: Route manager not initialized
value:
code: 503
error: network_route_manager_unavailable
success: false
store_unavailable:
summary: Route metadata unreadable
value:
code: 503
error: network_route_store_unavailable
success: false
revoke_failed:
summary: Node close, row delete or cleanup failed
value:
code: 503
error: network_route_revoke_failed
success: false
/session/proxy:
post:
tags:
- Session
summary: Set or remove the connection proxy
description: |
Stores or removes the legacy proxy used by the WhatsApp connection of this instance (`users.proxy_url`). The proxy is applied on the next connect.
**Rules:**
- The instance must be **disconnected**: a connected client returns `400 cannot set proxy while connected. Please disconnect first` before the body is read.
- `enable: false` (or omitted) removes the proxy and ignores `proxy_url`.
- `enable: true` requires `proxy_url` with scheme `http`, `https` or `socks5`, for example `socks5://user:pass@host:1080`.
- The URL is stored as given (credentials included) and echoed in `data.ProxyURL`.
- `RequiresReconnection` and `Message` exist for a connected client, but connected clients are rejected up front, so `RequiresReconnection` is `false` in practice.
- A session with a mobile network route (`/session/network-route`) egresses through that route instead of this proxy.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/SessionProxyRequest"
examples:
socks5:
summary: Enable a SOCKS5 proxy with credentials
description: Stores the SOCKS5 URL; it is used on the next `POST /session/connect`.
value:
enable: true
proxy_url: socks5://proxyuser:proxypass@proxy.example.com:1080
http:
summary: Enable an HTTP proxy
description: HTTP and HTTPS proxies are accepted as well.
value:
enable: true
proxy_url: http://proxy.example.com:3128
disable:
summary: Remove the proxy
description: Clears the stored proxy; the next connect goes out directly.
value:
enable: false
responses:
"200":
description: Proxy stored or removed.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionProxyResponse"
examples:
enabled:
summary: Proxy stored
value:
code: 200
data:
Details: Proxy configured successfully
ProxyURL: socks5://proxyuser:proxypass@proxy.example.com:1080
RequiresReconnection: false
success: true
disabled:
summary: Proxy removed
value:
code: 200
data:
Details: Proxy disabled successfully
RequiresReconnection: false
success: true
"400":
description: "Bad Request: client connected, invalid body, missing or malformed `proxy_url`, or unsupported scheme."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
connected:
summary: Client is connected
value:
code: 400
error: cannot set proxy while connected. Please disconnect first
success: false
could_not_decode_payload:
summary: Body is not valid JSON
value:
code: 400
error: could not decode payload
success: false
missing_proxy_url:
summary: enable is true but proxy_url is empty
value:
code: 400
error: missing proxy_url in payload
success: false
invalid_format:
summary: proxy_url cannot be parsed
value:
code: 400
error: invalid proxy URL format
success: false
unsupported_scheme:
summary: Scheme other than http, https or socks5
value:
code: 400
error: only HTTP, HTTPS and SOCKS5 proxies are supported
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: the proxy could not be written to the database."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
save_failed:
summary: Proxy could not be stored
value:
code: 500
error: failed to save proxy configuration
success: false
remove_failed:
summary: Proxy could not be removed
value:
code: 500
error: failed to remove proxy configuration
success: false
/session/s3/config:
post:
tags:
- Session S3
summary: Configure S3 storage for this instance
description: |
Stores the per-instance S3-compatible storage (AWS S3, MinIO, Backblaze B2, Cloudflare R2, etc.) used to upload
media from incoming and outgoing messages, and chooses how that media is delivered inside events.
**Rules:**
- **Full replace:** every call overwrites all S3 columns. Omitted fields are stored empty, `false` or `0`, so always send the complete configuration.
- `media_delivery` accepts `base64`, `s3`, `url` (alias, stored as `s3`) or `both`. Empty or omitted is stored as `base64`; any other value returns **400**.
- `retention_days: 0` disables object expiration.
- No connectivity or credential check happens here. Use `POST /session/s3/test` after saving.
- `enabled: false` keeps the other values as sent but stops uploads for this instance.
**Side effects:**
- The user configuration cache is reloaded and the S3 client of the instance is rebuilt from the saved values.
**Use Cases:**
- Deliver media as short URLs instead of large base64 blobs in webhooks
- Keep a copy of every media file in your own bucket with an expiration policy
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/SessionS3ConfigRequest"
examples:
aws_s3:
summary: AWS S3 with bucket owner enforced ownership
description: Standard AWS endpoint (leave `endpoint` empty), ACLs disabled, media delivered as both URL and base64, objects kept for 30 days.
value:
enabled: true
endpoint: ""
region: us-east-1
bucket: zuckzapgo-media-example
access_key: AKIAIOSFODNN7EXAMPLE
secret_key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
path_style: false
public_url: ""
media_delivery: both
retention_days: 30
disable_acl: true
minio_cdn:
summary: MinIO with path-style addressing and a CDN URL
description: Self-hosted MinIO requires `path_style`. Links in events use `public_url` as the base and objects never expire.
value:
enabled: true
endpoint: https://minio.example.com
region: us-east-1
bucket: whatsapp-media
access_key: minio-access-example
secret_key: minio-secret-example
path_style: true
public_url: https://cdn.example.com
media_delivery: url
retention_days: 0
disable_acl: false
disable:
summary: Disable S3 uploads
description: Because the call is a full replace, every other S3 field is stored empty and media delivery falls back to `base64`.
value:
enabled: false
responses:
"200":
description: S3 configuration saved and the S3 client rebuilt.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionS3ConfigSaveResponse"
example:
code: 200
data:
Details: S3 configuration saved successfully
Enabled: true
success: true
"400":
description: "Bad Request: the body is not valid JSON or `media_delivery` is not an accepted value."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
could_not_decode_payload:
summary: Body is not valid JSON
value:
code: 400
error: could not decode payload
success: false
invalid_media_delivery:
summary: media_delivery is not base64, s3, url or both
value:
code: 400
error: media_delivery must be 'base64', 's3', 'url', or 'both'
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: the database update failed, or the cache/S3 client could not be rebuilt from the saved values."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
save_failed:
summary: Database update failed
value:
code: 500
error: failed to save S3 configuration
success: false
cache_failed:
summary: Cache reload or S3 client rebuild failed
value:
code: 500
error: failed to update S3 cache
success: false
get:
tags:
- Session S3
summary: Get the S3 storage configuration
description: |
Returns the S3 storage configuration stored for this instance, as used for media uploads and media delivery in events.
**Rules:**
- `secret_key` is never returned.
- `access_key` is always returned as `***`, even when no key is stored.
- Values are read from the database, so this reflects the last `POST /session/s3/config` or `DELETE /session/s3/config`, not a connectivity check.
security:
- ApiKeyAuth: []
responses:
"200":
description: Stored S3 configuration with the access key masked.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionS3ConfigGetResponse"
examples:
configured:
summary: S3 configured
value:
code: 200
data:
enabled: true
endpoint: https://minio.example.com
region: us-east-1
bucket: whatsapp-media
access_key: "***"
path_style: true
public_url: https://cdn.example.com
media_delivery: s3
retention_days: 30
disable_acl: false
success: true
not_configured:
summary: S3 never configured or deleted
value:
code: 200
data:
enabled: false
endpoint: ""
region: ""
bucket: ""
access_key: "***"
path_style: true
public_url: ""
media_delivery: base64
retention_days: 30
disable_acl: false
success: true
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: the configuration could not be read from the database."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 500
error: failed to get S3 configuration
success: false
delete:
tags:
- Session S3
summary: Delete the S3 storage configuration
description: |
Removes the S3 storage configuration of this instance and returns media delivery to inline `base64`.
**Rules:**
- Stores `enabled=false`, empty endpoint, region, bucket, keys and public URL, `path_style=true`, `media_delivery=base64` and `retention_days=30`.
- `disable_acl` is not reset and keeps its previous value.
- Objects already uploaded to the bucket are not deleted.
- The user configuration cache is reloaded and the instance S3 client is removed.
security:
- ApiKeyAuth: []
responses:
"200":
description: S3 configuration removed.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionS3ConfigDeleteResponse"
example:
code: 200
data:
Details: S3 configuration deleted successfully
success: true
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: the database update failed, or the cache could not be reloaded."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
delete_failed:
summary: Database update failed
value:
code: 500
error: failed to delete S3 configuration
success: false
cache_failed:
summary: Cache reload failed
value:
code: 500
error: failed to update S3 cache
success: false
/session/s3/test:
post:
tags:
- Session S3
summary: Test the stored S3 connection
description: |
Verifies that the stored S3 configuration can reach the bucket, by rebuilding the S3 client and listing at most one object.
**Rules:**
- No request body: the test always uses the configuration saved with `POST /session/s3/config`.
- Fails with **400** when S3 is disabled for this instance.
- The bucket listing has a 10 second timeout; nothing is uploaded or deleted.
- A successful test also leaves the rebuilt S3 client active for uploads.
**Use Cases:**
- Validate credentials, endpoint and bucket permissions right after saving them
security:
- ApiKeyAuth: []
responses:
"200":
description: Bucket reachable with the stored credentials.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionS3TestResponse"
example:
code: 200
data:
Details: S3 connection test successful
Bucket: whatsapp-media
Region: us-east-1
success: true
"400":
description: "Bad Request: S3 is not enabled for this instance."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 400
error: S3 is not enabled for this user
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: the configuration could not be read, the S3 client could not be built, or the bucket listing failed (credentials, permissions, endpoint or network)."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
read_failed:
summary: Configuration could not be read
value:
code: 500
error: failed to get S3 configuration
success: false
client_failed:
summary: S3 client could not be built
value:
code: 500
error: "failed to initialize S3 client: failed to load AWS configuration"
success: false
access_denied:
summary: Bucket listing rejected
value:
code: 500
error: "S3 connection test failed: operation error S3: ListObjectsV2, https response error StatusCode: 403, api error AccessDenied: Access Denied"
success: false
/session/rabbitmq/config:
post:
tags:
- Session RabbitMQ
summary: Configure the RabbitMQ publisher for this instance
description: |
Stores the per-instance RabbitMQ publisher that receives WhatsApp events, including exchange and queue topology,
dead-lettering, queue limits and publisher tuning.
**Rules:**
- **Full replace:** every call overwrites all RabbitMQ columns. Omitted fields are stored as `false`, empty or NULL (server defaults), so always send the complete configuration.
- `events` is a comma-separated list of canonical, case-sensitive event names or `All`. Spaces around names are trimmed and empty items skipped; an unknown name returns **400**. Empty means no events.
- When `enabled` is `true`: `exchange_type` defaults to `topic`, `queue_type` to `classic`, `exchange` to `zuckzapgo.user.`, `queue` to `zuckzapgouser..events` and `routing_key` to `events.#`. `exchange_type` and `queue_type` are only validated in this case.
- `delivery_mode` `0` or omitted is stored as `2` (persistent).
- `connection_pool_size`, `worker_count`, `queue_buffer_size`, `batch_size` and `publish_timeout_ms` must be greater than 0; `batch_timeout_ms`, `max_retries` and `retry_delay_ms` must be non-negative.
- `queue_arguments` and `exchange_arguments` are **JSON-encoded strings**. Sending a JSON object in these fields fails with `400 could not decode payload`.
- The broker is not contacted here: a wrong URL does not fail this request. Use `POST /session/rabbitmq/test`.
**Features:**
- **Dynamic queues:** `{user_id}` and `{event_type}` placeholders in `queue` and `routing_key` are expanded per event; a `queue` containing `{event_type}` creates one queue per event type.
- **Dead-lettering and limits:** `dead_letter_exchange`, `dead_letter_routing_key`, `message_ttl`, `max_length` and `max_length_bytes` become `x-*` queue arguments.
- **Transport registration:** enabling registers the individual RabbitMQ transport in the event dispatcher; disabling unregisters it.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/SessionRabbitMQConfigRequest"
examples:
minimal:
summary: Enable with server defaults
description: Only the URL and events are sent; exchange, queue, routing key, exchange type and queue type get their defaults.
value:
enabled: true
url: amqp://zzg_user:zzg_pass@rabbitmq.example.com:5672/
events: All
dynamic_quorum_dlx:
summary: Per-event quorum queues with dead-lettering and tuning
description: One quorum queue per event type, a dead-letter exchange, a 24 hour message TTL, overflow rejection and custom publisher tuning.
value:
enabled: true
url: amqps://zzg_user:zzg_pass@rabbitmq.example.com:5671/whatsapp
exchange: whatsapp.events
exchange_type: topic
queue: user_{user_id}_event_{event_type}
queue_type: quorum
routing_key: whatsapp.{user_id}.{event_type}
events: Message,ReadReceipt,Connected
durable: true
auto_delete: false
exclusive: false
no_wait: false
delivery_mode: 2
dead_letter_exchange: dlx.zuckzapgo
dead_letter_routing_key: dlq.events
message_ttl: 86400000
max_length: 100000
max_length_bytes: 104857600
queue_arguments: '{"x-overflow":"reject-publish"}'
exchange_arguments: "{}"
worker_count: 50
batch_size: 500
batch_timeout_ms: 100
publish_timeout_ms: 5000
max_retries: 3
retry_delay_ms: 1000
disable:
summary: Disable publishing
description: Because the call is a full replace, the stored URL, exchange, queue and events are cleared and the transport is unregistered.
value:
enabled: false
responses:
"200":
description: RabbitMQ configuration saved and the publisher cache rebuilt.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionRabbitMQConfigSaveResponse"
example:
code: 200
data:
Details: RabbitMQ configuration saved successfully
Enabled: true
success: true
"400":
description: "Bad Request: invalid JSON (including JSON objects in `queue_arguments`/`exchange_arguments`), an unknown event name, an invalid exchange/queue type, or a tuning value out of range."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
could_not_decode_payload:
summary: Body is not valid JSON or a field has the wrong type
value:
code: 400
error: could not decode payload
success: false
unsupported_event_type:
summary: Unknown event name in events
value:
code: 400
error: "unsupported event type: MessageReceived"
success: false
invalid_exchange_type:
summary: exchange_type is not topic, direct, fanout or headers
value:
code: 400
error: "invalid exchange_type: fan-out. Must be one of: topic, direct, fanout, headers"
success: false
invalid_queue_type:
summary: queue_type is not classic, quorum or stream
value:
code: 400
error: "invalid queue_type: lazy. Must be one of: classic, quorum, stream"
success: false
positive_value_required:
summary: A tuning value that must be positive is 0 or negative
value:
code: 400
error: worker_count must be greater than 0
success: false
non_negative_value_required:
summary: A tuning value that must be non-negative is negative
value:
code: 400
error: max_retries must be non-negative
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: the database update failed, or the cache/publisher could not be rebuilt."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
save_failed:
summary: Database update failed
value:
code: 500
error: failed to save RabbitMQ configuration
success: false
cache_failed:
summary: Cache reload or publisher rebuild failed
value:
code: 500
error: failed to update RabbitMQ cache
success: false
get:
tags:
- Session RabbitMQ
summary: Get the RabbitMQ configuration and queue statistics
description: |
Returns the stored RabbitMQ publisher configuration of this instance together with the dynamic queues this process has declared.
**Rules:**
- The password inside `config.url` is replaced by `***`.
- Tuning fields (`connection_pool_size`, `worker_count`, ...) are only present when a value is stored.
- `dead_letter_*`, `queue_arguments` and `exchange_arguments` are only present when non-empty; `message_ttl`, `max_length` and `max_length_bytes` only when greater than 0.
- `stats` is in-memory state of this process (reset on restart) and is `null` when the RabbitMQ manager is not running.
security:
- ApiKeyAuth: []
responses:
"200":
description: Stored configuration (URL password masked) and in-memory queue statistics.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionRabbitMQConfigGetResponse"
example:
code: 200
data:
config:
enabled: true
url: "amqps://zzg_user:***@rabbitmq.example.com:5671/whatsapp"
exchange: whatsapp.events
exchange_type: topic
queue: user_{user_id}_event_{event_type}
queue_type: quorum
routing_key: whatsapp.{user_id}.{event_type}
events: Message,ReadReceipt,Connected
durable: true
auto_delete: false
exclusive: false
no_wait: false
delivery_mode: 2
worker_count: 50
batch_size: 500
dead_letter_exchange: dlx.zuckzapgo
dead_letter_routing_key: dlq.events
message_ttl: 86400000
queue_arguments: '{"x-overflow":"reject-publish"}'
stats:
userID: 4e4942c7dee1deef99ab8fd9f7350de5
dynamicQueues: true
createdQueues: 2
queueNames:
- user_4e4942c7dee1deef99ab8fd9f7350de5_event_Message
- user_4e4942c7dee1deef99ab8fd9f7350de5_event_ReadReceipt
success: true
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: the configuration could not be read from the database."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 500
error: failed to get RabbitMQ configuration
success: false
delete:
tags:
- Session RabbitMQ
summary: Delete the RabbitMQ configuration
description: |
Disables RabbitMQ publishing for this instance, clears the stored broker settings and unregisters the individual RabbitMQ transport.
**Rules:**
- Stores `enabled=false`, empty URL, exchange, exchange type, queue, queue type, routing key and events, `durable=true`, `auto_delete`/`exclusive`/`no_wait=false`, `delivery_mode=2`, and NULL dead-letter, TTL, length and argument fields.
- Publisher tuning fields (`connection_pool_size`, `worker_count`, `queue_buffer_size`, `batch_size`, timeouts and retries) are not reset.
- Exchanges and queues already declared on the broker are not deleted.
security:
- ApiKeyAuth: []
responses:
"200":
description: RabbitMQ configuration removed.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionRabbitMQConfigDeleteResponse"
example:
code: 200
data:
Details: RabbitMQ configuration deleted successfully
success: true
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: the database update failed, or the cache could not be reloaded."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
delete_failed:
summary: Database update failed
value:
code: 500
error: failed to delete RabbitMQ configuration
success: false
cache_failed:
summary: Cache reload failed
value:
code: 500
error: failed to update RabbitMQ cache
success: false
/session/rabbitmq/test:
post:
tags:
- Session RabbitMQ
summary: Test the RabbitMQ connection and publish a test message
description: |
Verifies the stored RabbitMQ configuration end to end: it reloads the configuration, connects to the broker,
declares the configured topology, starts the publisher and publishes one test event.
**Rules:**
- No request body: the test uses the configuration saved with `POST /session/rabbitmq/config`.
- Fails with **400** when RabbitMQ is disabled for this instance.
- The published test event has type `test` and a payload with `test: true`, a message, a Unix timestamp and the user ID; consumers bound to the routing key receive it.
- A successful test leaves the publisher initialized for normal event delivery.
- The broker URL is never echoed: `data.URL` is always `***`.
security:
- ApiKeyAuth: []
responses:
"200":
description: Broker reachable, topology declared and test message published.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionRabbitMQTestResponse"
example:
code: 200
data:
Details: RabbitMQ connection test successful
Exchange: whatsapp.events
ExchangeType: topic
Queue: user_{user_id}_event_{event_type}
QueueType: quorum
RoutingKey: whatsapp.{user_id}.{event_type}
TestMessage: Test message published successfully
URL: "***"
success: true
"400":
description: "Bad Request: RabbitMQ is not enabled for this instance."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 400
error: RabbitMQ is not enabled for this user
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: the configuration could not be read or reloaded, the broker connection or topology declaration failed, the publisher could not start, or the test message could not be published."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
read_failed:
summary: Configuration could not be read
value:
code: 500
error: failed to get RabbitMQ configuration
success: false
refresh_failed:
summary: Cache reload failed
value:
code: 500
error: "failed to refresh RabbitMQ configuration: user config not found in cache for RabbitMQ refresh"
success: false
not_cached:
summary: Reloaded configuration missing from the manager
value:
code: 500
error: failed to retrieve RabbitMQ configuration from cache
success: false
connection_failed:
summary: Broker unreachable or credentials rejected
value:
code: 500
error: "RabbitMQ connection test failed: failed to connect to RabbitMQ: dial tcp 203.0.113.10:5672: connect: connection refused"
success: false
init_failed:
summary: Publisher could not start after the test
value:
code: 500
error: "failed to initialize RabbitMQ client after test: failed to open channel: channel/connection is not open"
success: false
publish_failed:
summary: Test message not published
value:
code: 500
error: "failed to publish test message: publish timeout"
success: false
/session/skipmedia/config:
post:
tags:
- Session Skips
summary: Turn media download for events on or off
description: |
Controls whether this instance downloads the media (images, videos, audio, documents, stickers) of message events.
With the flag on, events are still delivered with the WhatsApp message metadata, but without base64 content and without S3 uploads.
**Rules:**
- `enabled: true` skips media download; `false` restores it. An omitted `enabled` is treated as `false`.
- Media is skipped when **any** of these is on: the `-skipmedia` command-line flag, the `GLOBAL_SKIP_MEDIA_DOWNLOAD` environment variable, or this per-instance flag. This endpoint cannot override the first two.
- Takes effect for the next events: the user configuration cache is reloaded immediately.
**Use Cases:**
- High-volume instances that only need text and message metadata
- Reducing bandwidth and S3 storage when media is fetched on demand with `/chat/download*`
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/SkipMediaConfig"
examples:
skip_media:
summary: Skip media download
description: Events keep message metadata but carry no base64 media and nothing is uploaded to S3.
value:
enabled: true
download_media:
summary: Download media again
description: Media is downloaded (and uploaded to S3 when configured) unless the flag or environment variable forces the skip.
value:
enabled: false
responses:
"200":
description: Flag stored and cache reloaded.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionSkipMediaUpdateResponse"
example:
code: 200
data:
Details: Skip media download configuration updated successfully
SkipMediaDownload: true
success: true
"400":
description: "Bad Request: the body is empty or not valid JSON, or `enabled` is not a boolean."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 400
error: could not decode payload
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: the flag could not be stored or the media cache could not be reloaded."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
update_failed:
summary: Database update failed
value:
code: 500
error: failed to update skip media download configuration
success: false
cache_failed:
summary: Cache reload failed
value:
code: 500
error: failed to update skip media cache
success: false
get:
tags:
- Session Skips
summary: Get the media download skip setting
description: |
Returns the per-instance media download flag together with the server-wide environment setting, so clients can tell why media is missing from events.
**Rules:**
- `UserSkipMediaDownload` is the value stored with `POST /session/skipmedia/config` (`false` when never set).
- `GlobalSkipMediaDownload` mirrors `GLOBAL_SKIP_MEDIA_DOWNLOAD` and is read-only.
- The `-skipmedia` command-line flag is not reported, but it also forces the skip when set.
security:
- ApiKeyAuth: []
responses:
"200":
description: Per-instance and server-wide media skip settings.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionSkipMediaGetResponse"
example:
code: 200
data:
UserSkipMediaDownload: true
GlobalSkipMediaDownload: false
Details: Skip media download configuration retrieved successfully
success: true
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: the flag could not be read from the database."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 500
error: failed to get skip media download configuration
success: false
/session/skipgroups/config:
post:
tags:
- Session Skips
summary: Ignore or process group chat events
description: |
Controls whether this instance drops every event that comes from WhatsApp groups (`@g.us`), so only direct chats, newsletters and broadcasts reach webhooks and transports.
**Rules:**
- `enabled: true` drops group events; `false` processes them again. An omitted `enabled` is treated as `false`.
- Dropped event types: `Message` and `Receipt` in group chats, `ChatPresence` in groups, `GroupInfo` and `JoinedGroup`.
- Dropped events are discarded before any processing: no media download, no webhook, no RabbitMQ/SQS/Redis/WebSocket delivery.
- The server-wide `GLOBAL_SKIP_GROUPS` environment variable drops group events for every instance, regardless of this flag.
- Sending to groups through the API is not affected.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/SkipGroupsConfig"
examples:
ignore_groups:
summary: Ignore group events
description: A support bot that only answers direct chats stops receiving group traffic.
value:
enabled: true
process_groups:
summary: Process group events again
description: Group messages, receipts and group updates are delivered again.
value:
enabled: false
responses:
"200":
description: Flag stored and cache reloaded.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionSkipGroupsUpdateResponse"
example:
code: 200
data:
Details: Skip groups configuration updated successfully
SkipGroups: true
success: true
"400":
description: "Bad Request: the body is empty or not valid JSON, or `enabled` is not a boolean."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 400
error: could not decode payload
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: the flag could not be stored or the groups cache could not be reloaded."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
update_failed:
summary: Database update failed
value:
code: 500
error: failed to update skip groups configuration
success: false
cache_failed:
summary: Cache reload failed
value:
code: 500
error: failed to update skip groups cache
success: false
get:
tags:
- Session Skips
summary: Get the group events skip setting
description: |
Returns whether this instance currently drops events from WhatsApp groups.
**Rules:**
- `SkipGroups` is the per-instance value (`false` when never set).
- The server-wide `GLOBAL_SKIP_GROUPS` environment variable is not included in this response.
security:
- ApiKeyAuth: []
responses:
"200":
description: Per-instance group skip flag.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionSkipGroupsGetResponse"
example:
code: 200
data:
SkipGroups: true
Details: Skip groups configuration retrieved successfully
success: true
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: the flag could not be read from the database."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 500
error: failed to get skip groups configuration
success: false
/session/skipnewsletters/config:
post:
tags:
- Session Skips
summary: Ignore or process newsletter (channel) events
description: |
Controls whether this instance drops events that come from WhatsApp newsletters (Channels, `@newsletter`).
**Rules:**
- `enabled: true` drops newsletter events; `false` processes them again. An omitted `enabled` is treated as `false`.
- Dropped event types: `Message` and `Receipt` in newsletter chats, `ChatPresence` in newsletters, `NewsletterJoin`, `NewsletterLeave`, `NewsletterMuteChange` and `NewsletterLiveUpdate`.
- Dropped events never reach media download, webhooks or any transport.
- The server-wide `GLOBAL_SKIP_NEWSLETTERS` environment variable drops newsletter events for every instance, regardless of this flag.
- `/newsletter/*` endpoints keep working.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/SkipNewslettersConfig"
examples:
ignore_newsletters:
summary: Ignore channel events
description: Followed channels can post many updates; this keeps them out of the webhook.
value:
enabled: true
process_newsletters:
summary: Process channel events again
description: Newsletter messages and follow/mute updates are delivered again.
value:
enabled: false
responses:
"200":
description: Flag stored and cache reloaded.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionSkipNewslettersUpdateResponse"
example:
code: 200
data:
Details: Skip newsletters configuration updated successfully
SkipNewsletters: true
success: true
"400":
description: "Bad Request: the body is empty or not valid JSON, or `enabled` is not a boolean."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 400
error: could not decode payload
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: the flag could not be stored or the newsletters cache could not be reloaded."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
update_failed:
summary: Database update failed
value:
code: 500
error: failed to update skip newsletters configuration
success: false
cache_failed:
summary: Cache reload failed
value:
code: 500
error: failed to update skip newsletters cache
success: false
get:
tags:
- Session Skips
summary: Get the newsletter events skip setting
description: |
Returns whether this instance currently drops events from WhatsApp newsletters (Channels).
**Rules:**
- `SkipNewsletters` is the per-instance value (`false` when never set).
- The server-wide `GLOBAL_SKIP_NEWSLETTERS` environment variable is not included in this response.
security:
- ApiKeyAuth: []
responses:
"200":
description: Per-instance newsletter skip flag.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionSkipNewslettersGetResponse"
example:
code: 200
data:
SkipNewsletters: false
Details: Skip newsletters configuration retrieved successfully
success: true
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: the flag could not be read from the database."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 500
error: failed to get skip newsletters configuration
success: false
/session/skipbroadcasts/config:
post:
tags:
- Session Skips
summary: Ignore or process broadcast and status events
description: |
Controls whether this instance drops events from broadcast chats, which include contacts' Status updates (`status@broadcast`) and broadcast lists (`@broadcast`).
**Rules:**
- `enabled: true` drops broadcast events; `false` processes them again. An omitted `enabled` is treated as `false`.
- Dropped event types: `Message` and `Receipt` whose chat JID contains `@broadcast`, and `ChatPresence` in those chats.
- Dropped events never reach media download, webhooks or any transport. Skipping Status traffic also avoids downloading status media.
- The server-wide `GLOBAL_SKIP_BROADCASTS` environment variable drops broadcast events for every instance, regardless of this flag.
- Publishing your own status with `/status/send/*` is not affected.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/SkipBroadcastsConfig"
examples:
ignore_status:
summary: Ignore Status and broadcast events
description: Contacts' Status posts and their receipts stop reaching the webhook.
value:
enabled: true
process_status:
summary: Process Status and broadcast events again
description: Status posts and broadcast list messages are delivered again.
value:
enabled: false
responses:
"200":
description: Flag stored and cache reloaded.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionSkipBroadcastsUpdateResponse"
example:
code: 200
data:
Details: Skip broadcasts configuration updated successfully
SkipBroadcasts: true
success: true
"400":
description: "Bad Request: the body is empty or not valid JSON, or `enabled` is not a boolean."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 400
error: could not decode payload
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: the flag could not be stored or the broadcasts cache could not be reloaded."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
update_failed:
summary: Database update failed
value:
code: 500
error: failed to update skip broadcasts configuration
success: false
cache_failed:
summary: Cache reload failed
value:
code: 500
error: failed to update skip broadcasts cache
success: false
get:
tags:
- Session Skips
summary: Get the broadcast and status events skip setting
description: |
Returns whether this instance currently drops events from broadcast chats and contacts' Status updates.
**Rules:**
- `SkipBroadcasts` is the per-instance value (`false` when never set).
- The server-wide `GLOBAL_SKIP_BROADCASTS` environment variable is not included in this response.
security:
- ApiKeyAuth: []
responses:
"200":
description: Per-instance broadcast skip flag.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionSkipBroadcastsGetResponse"
example:
code: 200
data:
SkipBroadcasts: true
Details: Skip broadcasts configuration retrieved successfully
success: true
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: the flag could not be read from the database."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 500
error: failed to get skip broadcasts configuration
success: false
/session/skipownmessages/config:
post:
tags:
- Session Skips
summary: Ignore or process events about your own messages
description: |
Controls whether this instance drops events generated by messages sent from this WhatsApp account (from the phone, other linked devices or this API).
**Rules:**
- `enabled: true` drops own-message events; `false` processes them again. An omitted `enabled` is treated as `false`.
- Dropped event types: `Message` and `Receipt` with `IsFromMe`, and `DeleteForMe`, `Star` and `MediaRetry` events about messages sent by this account.
- Dropped events never reach media download, webhooks or any transport.
- The server-wide `GLOBAL_SKIP_OWN_MESSAGES` environment variable drops own `Message`, `Receipt` and `MediaRetry` events for every instance, regardless of this flag.
- Sending through the API still works and still returns the message ID in the HTTP response.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/SkipOwnMessagesConfig"
examples:
ignore_own:
summary: Ignore own messages
description: A chatbot that must never react to its own replies stops receiving them as events.
value:
enabled: true
process_own:
summary: Process own messages again
description: Messages typed on the phone or sent by other devices are delivered again, useful for inbox mirroring.
value:
enabled: false
responses:
"200":
description: Flag stored and cache reloaded.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionSkipOwnMessagesUpdateResponse"
example:
code: 200
data:
Details: Skip own messages configuration updated successfully
SkipOwnMessages: true
success: true
"400":
description: "Bad Request: the body is empty or not valid JSON, or `enabled` is not a boolean."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 400
error: could not decode payload
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: the flag could not be stored or the own-messages cache could not be reloaded."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
update_failed:
summary: Database update failed
value:
code: 500
error: failed to update skip own messages configuration
success: false
cache_failed:
summary: Cache reload failed
value:
code: 500
error: failed to update skip own messages cache
success: false
get:
tags:
- Session Skips
summary: Get the own-message events skip setting
description: |
Returns whether this instance currently drops events about messages sent by this WhatsApp account.
**Rules:**
- `SkipOwnMessages` is the per-instance value (`false` when never set).
- The server-wide `GLOBAL_SKIP_OWN_MESSAGES` environment variable is not included in this response.
security:
- ApiKeyAuth: []
responses:
"200":
description: Per-instance own-message skip flag.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionSkipOwnMessagesGetResponse"
example:
code: 200
data:
SkipOwnMessages: false
Details: Skip own messages configuration retrieved successfully
success: true
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: the flag could not be read from the database."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 500
error: failed to get skip own messages configuration
success: false
/session/skipcalls/config:
post:
tags:
- Session Skips
summary: Auto-reject incoming calls
description: |
Turns automatic rejection of incoming WhatsApp calls on or off for this instance and sets the text message sent to the caller after rejecting.
**Rules:**
- `enabled: true` rejects every incoming 1:1 call offer and group call notice, then sends `reject_message` to the caller as a text message. An omitted `enabled` is treated as `false`.
- `CallOffer` and `CallOfferNotice` events are dropped (not delivered to webhooks or transports) while the flag is on.
- `reject_message` empty or omitted is stored as `Sorry, I cannot take calls at the moment.`
- `reject_type` accepts `busy`, `declined` or `unavailable`; empty or omitted is stored as `busy`; anything else returns **400**. The value is stored and logged only: the rejection sent to WhatsApp is the same for every type.
- When the native calls engine owns inbound calls for the instance (`/call/config`), the engine handles the call and no automatic rejection or message is sent.
- The server-wide `GLOBAL_SKIP_CALLS` environment variable also rejects calls and drops `CallOffer` events for every instance, regardless of this flag.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/SkipCallsConfig"
examples:
reject_with_message:
summary: Reject calls and reply with a custom text
description: Every incoming call is rejected and the caller receives the message as a WhatsApp text.
value:
enabled: true
reject_message: Sorry, I cannot take calls right now. Please send a message.
reject_type: busy
reject_with_defaults:
summary: Reject calls with the default text
description: Omitting `reject_message` and `reject_type` stores the default message and `busy`.
value:
enabled: true
accept_calls:
summary: Stop rejecting calls
description: Calls ring normally again and call events are delivered. The stored message and type are overwritten with the defaults.
value:
enabled: false
responses:
"200":
description: Settings stored and cache reloaded. `data` echoes the stored values, including defaults.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionSkipCallsUpdateResponse"
example:
code: 200
data:
Details: Skip calls configuration updated successfully
SkipCalls: true
RejectMessage: Sorry, I cannot take calls right now. Please send a message.
RejectType: busy
success: true
"400":
description: "Bad Request: the body is not valid JSON, or `reject_type` is not an accepted value."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
could_not_decode_payload:
summary: Body is not valid JSON
value:
code: 400
error: could not decode payload
success: false
invalid_reject_type:
summary: reject_type is not busy, declined or unavailable
value:
code: 400
error: "invalid reject_type, must be: busy, declined, or unavailable"
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: the settings could not be stored or the calls cache could not be reloaded."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
update_failed:
summary: Database update failed
value:
code: 500
error: failed to update skip calls configuration
success: false
cache_failed:
summary: Cache reload failed
value:
code: 500
error: failed to update skip calls cache
success: false
get:
tags:
- Session Skips
summary: Get the call auto-reject settings
description: |
Returns whether incoming calls are automatically rejected for this instance and which message is sent to the caller.
**Rules:**
- Defaults are returned when nothing is stored: `SkipCalls=false`, `RejectMessage=Sorry, I cannot take calls at the moment.`, `RejectType=busy`.
- The server-wide `GLOBAL_SKIP_CALLS` environment variable is not included in this response.
security:
- ApiKeyAuth: []
responses:
"200":
description: Stored auto-reject settings.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionSkipCallsGetResponse"
example:
code: 200
data:
SkipCalls: true
RejectMessage: Sorry, I cannot take calls right now. Please send a message.
RejectType: busy
Details: Skip calls configuration retrieved successfully
success: true
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: the settings could not be read from the database."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 500
error: failed to get skip calls configuration
success: false
/session/globaltransports/config:
post:
tags:
- Session Global Transports
summary: Opt this instance out of global event transports
operationId: configureGlobalTransportSkips
description: |
Sets per-instance flags that make the server-wide (global) event dispatcher skip this instance for selected transports:
the global webhook, RabbitMQ, SQS, Redis, WebSocket and the shared S3 media enrichment.
**Rules:**
- **Partial update:** only the flags present in the body are written; omitted flags keep their stored value.
- At least one flag is required; `{}` or a body with only unknown fields returns **400** `no fields provided`.
- Unknown fields are ignored. A non-boolean flag value or invalid JSON returns **400** `invalid request body`.
- Only the global dispatcher is affected. The instance's own webhook (`/webhook`) and RabbitMQ (`/session/rabbitmq/config`) keep working.
- The response is built from the reloaded cache. If the cache reload fails after the database update, the request still returns **200** and the flags apply once the cache is refreshed.
**Use Cases:**
- Keep one tenant's traffic out of a shared global RabbitMQ or SQS queue
- Stop uploading one instance's media to the global S3 bucket
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/GlobalTransportSkipsRequest"
examples:
skip_rabbitmq_and_s3:
summary: Opt out of global RabbitMQ and S3
description: Only these two flags change; webhook, SQS, Redis and WebSocket keep their stored values.
value:
skipGlobalRabbitMQ: true
skipGlobalS3: true
restore_webhook:
summary: Receive the global webhook again
description: Clears a single flag without touching the others.
value:
skipGlobalWebhook: false
set_all_flags:
summary: Set every flag explicitly
description: Useful to replicate a known configuration across instances.
value:
skipGlobalWebhook: false
skipGlobalRabbitMQ: true
skipGlobalSQS: false
skipGlobalRedis: false
skipGlobalWebSocket: false
skipGlobalS3: true
responses:
"200":
description: Flags stored. `data` contains all six flags after the update.
content:
application/json:
schema:
$ref: "#/components/schemas/GlobalTransportSkipsResponse"
example:
code: 200
data:
skipGlobalWebhook: false
skipGlobalRabbitMQ: true
skipGlobalSQS: false
skipGlobalRedis: false
skipGlobalWebSocket: false
skipGlobalS3: true
details: Global transport skip configuration updated successfully
success: true
"400":
description: "Bad Request: the body is not valid JSON, a flag is not a boolean, or no known flag was sent."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
invalid_request_body:
summary: Invalid JSON or non-boolean flag
value:
code: 400
error: invalid request body
success: false
no_fields_provided:
summary: No known flag in the body
value:
code: 400
error: no fields provided
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: the flags could not be stored."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 500
error: failed to update transport configuration
success: false
get:
tags:
- Session Global Transports
summary: Get the global transport opt-out flags
operationId: getGlobalTransportSkips
description: |
Returns the six per-instance flags that the global event dispatcher checks before delivering this instance's events to each global transport.
**Rules:**
- Values come from the user configuration cache; on a cache miss the configuration is loaded from the database first.
- A flag that was never set is returned as `false` (the instance receives that global transport).
- Whether each global transport is enabled at all is a server setting and is not part of this response.
security:
- ApiKeyAuth: []
responses:
"200":
description: Current opt-out flags of this instance.
content:
application/json:
schema:
$ref: "#/components/schemas/GlobalTransportSkipsResponse"
example:
code: 200
data:
skipGlobalWebhook: false
skipGlobalRabbitMQ: true
skipGlobalSQS: false
skipGlobalRedis: false
skipGlobalWebSocket: false
skipGlobalS3: true
details: Global transport skip configuration retrieved successfully
success: true
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: the configuration was not cached and could not be loaded from the database."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 500
error: failed to load user configuration
success: false
/session/presence/config:
post:
tags:
- Session Presence
summary: Turn automatic "unavailable" presence on or off
operationId: configureAutoPresenceUnavailable
description: |
Controls whether this instance marks itself as unavailable right after connecting, so the phone keeps receiving push notifications while the API session stays online.
**Rules:**
- `enabled: true`: after every connection (and after the initial app-state sync) the gateway sends the protocol-required `available` presence, waits 3 seconds, then sends `unavailable`.
- `enabled: false` (default, also used when `enabled` is omitted): the instance stays `available` after connecting, which can silence notifications on the phone.
- The setting applies from the next connection or app-state sync; it does not change the current presence immediately.
- Manual presence changes with `POST /user/presence` are not affected.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/SessionPresenceConfigRequest"
examples:
keep_phone_notifications:
summary: Go unavailable 3 seconds after connecting
description: Recommended when the same account is also used on the phone and notifications must keep arriving.
value:
enabled: true
stay_available:
summary: Stay available after connecting
description: Restores the default behavior.
value:
enabled: false
responses:
"200":
description: Setting stored and presence cache reloaded.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionPresenceConfigUpdateResponse"
example:
code: 200
data:
Details: Auto presence unavailable configuration updated successfully
AutoPresenceUnavailable: true
success: true
"400":
description: "Bad Request: the body is empty or not valid JSON, or `enabled` is not a boolean."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 400
error: could not decode payload
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: the setting could not be stored or the presence cache could not be reloaded."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
update_failed:
summary: Database update failed
value:
code: 500
error: failed to update auto presence unavailable configuration
success: false
cache_failed:
summary: Cache reload failed
value:
code: 500
error: failed to update presence cache
success: false
get:
tags:
- Session Presence
summary: Get the automatic "unavailable" presence setting
operationId: getAutoPresenceUnavailableConfig
description: |
Returns whether this instance sends an `unavailable` presence 3 seconds after connecting.
**Rules:**
- `AutoPresenceUnavailable` is `false` when the setting was never stored.
- This reports the stored setting, not the presence currently shown to contacts.
security:
- ApiKeyAuth: []
responses:
"200":
description: Stored setting.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionPresenceConfigGetResponse"
example:
code: 200
data:
AutoPresenceUnavailable: true
Details: Auto presence unavailable configuration retrieved successfully
success: true
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: the setting could not be read from the database."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 500
error: failed to get auto presence unavailable configuration
success: false
/user/info:
post:
tags:
- User
summary: Get user information
description: |
Fetches WhatsApp profile data for one or more accounts: status (about) text, profile picture ID, business verification, LID and the list of devices currently registered to each account.
**Rules:**
- Send the numbers in `phone`, or in the legacy `Phone` field. Both accept a single string or an array of strings; `phone` is read first and `Phone` only when `phone` yields no value.
- Each value may be a phone number with country code (a leading `+` is stripped) or a user JID. The first unparseable value aborts the request with **400**.
- Non-string items inside an array are ignored.
- A missing WhatsApp session returns **500** `no session`; a failed WhatsApp query returns **500**.
**Response:**
- `data.users` is an object keyed by JID. `verified_name`, `business_name`, `lid` and `first_device` are omitted when empty.
- `verified_certificate` only appears for business accounts that carry a certificate.
- `devices[].device` is the platform name derived from the device ID (see `POST /device/platform`).
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/UserInfoRequest"
examples:
single:
summary: One phone number
description: A single number sent as a plain string.
value:
phone: "5511999999999"
several:
summary: Several phone numbers
description: Up to the WhatsApp usync limits; every value must be a valid number or JID.
value:
phone:
- "5511999999999"
- "5511988888888"
legacy_field:
summary: Legacy Phone field with a JID
description: The capitalized `Phone` field is still accepted for backward compatibility.
value:
Phone:
- 5511999999999@s.whatsapp.net
responses:
"200":
description: Profile data keyed by JID.
content:
application/json:
schema:
$ref: "#/components/schemas/UserInfoResponse"
examples:
personal_account:
summary: Personal account with two devices
value:
code: 200
data:
users:
5511999999999@s.whatsapp.net:
jid: 5511999999999@s.whatsapp.net
status: Available
picture_id: "1700000000"
lid: 123456789012345@lid
is_business_account: false
device_count: 2
first_device: 5511999999999@s.whatsapp.net
devices:
- user: "5511999999999"
agent: "0"
device: UNKNOWN
server: s.whatsapp.net
ad: 5511999999999.0:0@s.whatsapp.net
jid: 5511999999999@s.whatsapp.net
- user: "5511999999999"
agent: "0"
device: SAFARI
server: s.whatsapp.net
ad: 5511999999999.0:5@s.whatsapp.net
jid: 5511999999999:5@s.whatsapp.net
success: true
business_account:
summary: Verified business account
value:
code: 200
data:
users:
5511988888888@s.whatsapp.net:
jid: 5511988888888@s.whatsapp.net
status: Open Monday to Friday
picture_id: "1728656243"
verified_name: Example Store
business_name: Example Store
is_business_account: true
device_count: 1
first_device: 5511988888888@s.whatsapp.net
verified_certificate:
has_signature: true
has_server_signature: true
devices:
- user: "5511988888888"
agent: "0"
device: UNKNOWN
server: s.whatsapp.net
ad: 5511988888888.0:0@s.whatsapp.net
jid: 5511988888888@s.whatsapp.net
success: true
"400":
description: "Bad Request: invalid JSON, no phone value, a field with the wrong type, or an unparseable number."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
could_not_decode_payload:
summary: Body is not valid JSON
value:
code: 400
error: "could not decode payload: unexpected EOF"
success: false
phone_wrong_type:
summary: phone is neither a string nor an array
value:
code: 400
error: phone field must be string or array of strings
success: false
legacy_phone_wrong_type:
summary: Phone is neither a string nor an array
value:
code: 400
error: Phone field must be string or array of strings
success: false
missing_phone:
summary: Neither phone nor Phone provided
value:
code: 400
error: missing phone numbers in payload. Use 'Phone' or 'phone' field
success: false
invalid_phone:
summary: A value is not a valid number or JID
value:
code: 400
error: "invalid phone number: @s.whatsapp.net"
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: no WhatsApp session for this user, or the WhatsApp user-info query failed."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: No WhatsApp session for this user
value:
code: 500
error: no session
success: false
query_failed:
summary: WhatsApp query failed
value:
code: 500
error: "Failed to get user info: websocket not connected"
success: false
/user/privacy/settings:
get:
tags:
- User
summary: Get privacy settings fresh from WhatsApp
description: |
Fetches the privacy settings of the connected account directly from WhatsApp, bypassing the library cache, and returns them as flat fields.
**Rules:**
- No query parameters or body. The cache is bypassed on every call.
- Unlike `GET /privacy/settings`, a failed fetch is reported as **500** instead of returning empty values.
**Values:**
- `group_add`, `last_seen`, `status`, `profile`: `all`, `contacts`, `contact_blacklist` or `none`.
- `read_receipts`: `all` or `none`. `online`: `all` or `match_last_seen`. `call_add`: `all` or `known`.
- A field is an empty string when WhatsApp did not report it.
security:
- ApiKeyAuth: []
responses:
"200":
description: Current privacy settings.
content:
application/json:
schema:
$ref: "#/components/schemas/UserPrivacySettingsResponse"
example:
code: 200
data:
group_add: contacts
last_seen: contacts
status: contacts
profile: all
read_receipts: all
online: match_last_seen
call_add: all
success: true
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: no WhatsApp session, or the privacy query failed."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: No WhatsApp session for this user
value:
code: 500
error: no session
success: false
fetch_failed:
summary: WhatsApp privacy query failed
value:
code: 500
error: "failed to get privacy settings: websocket not connected"
success: false
/user/pushname:
post:
tags:
- User
summary: Change your push name
description: |
Changes the push name (display name) of the connected account, the name recipients see next to your number when you are not in their contacts.
**Rules:**
- `push_name` is required and cannot be empty.
- The change is sent as an app-state `setting_pushName` mutation. On sync conflicts (409 or LTHash mismatch) the gateway runs a full app-state sync and retries up to 3 times before failing.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ChangePushNameRequest"
examples:
company_name:
summary: Company display name
description: A short brand name shown to people who have not saved your number.
value:
push_name: Example Store
agent_name:
summary: Personal display name
description: Any non-empty text is accepted; emoji are allowed.
value:
push_name: Maria from Support
responses:
"200":
description: Push name updated.
content:
application/json:
schema:
$ref: "#/components/schemas/UserPushNameResponse"
example:
code: 200
data:
success: true
message: Push name updated successfully
push_name: Example Store
success: true
"400":
description: "Bad Request: invalid JSON or empty `push_name`."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
could_not_decode_payload:
summary: Body is not valid JSON
value:
code: 400
error: could not decode payload
success: false
empty_push_name:
summary: push_name missing or empty
value:
code: 400
error: push name cannot be empty
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: no WhatsApp session, or the app-state update failed after the recovery attempts."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: No WhatsApp session for this user
value:
code: 500
error: no session
success: false
update_failed:
summary: App-state update failed
value:
code: 500
error: "failed to change push name: app state error (not recoverable): websocket not connected"
success: false
/user/contact/info:
post:
tags:
- User
summary: Get combined contact information
description: |
Builds one consolidated view of a contact from several WhatsApp sources: registration check, user info (status, devices), profile picture (downloaded and embedded as base64), saved contact names, LID mapping and business profile.
**Rules:**
- `phone` is required: a phone number, a user JID or a LID (`@lid`).
- A LID is first translated to the phone number using the local LID store; when no mapping is cached the request returns **404**.
- If the number is not on WhatsApp, the call still returns **200** with `is_on_whatsapp: false` and the lookup sections set to `null`.
- The registration check is mandatory (**500** when it fails); user info, avatar, contact names and business profile failures only null their section.
- The avatar lookup has a 10-second timeout and is skipped when WhatsApp reports no picture.
**Response:**
- `input_type` tells how `phone` was interpreted: `phone`, `jid` or `lid`.
- `jid` and `phone` are always phone-shaped; `lid` is the contact LID when known.
- `avatar.base64` is present only when the gateway could download the picture; `preview_url` only when both sizes were fetched.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/UserContactInfoRequest"
examples:
phone_number:
summary: Phone number
description: Phone number with country code, without `+`.
value:
phone: "5511999999999"
jid_format:
summary: User JID
description: A full phone JID; `input_type` becomes `jid`.
value:
phone: 5511999999999@s.whatsapp.net
lid_format:
summary: LID
description: Requires a cached LID-to-phone mapping; `input_type` becomes `lid`.
value:
phone: 123456789012345@lid
responses:
"200":
description: Consolidated contact information.
content:
application/json:
schema:
$ref: "#/components/schemas/UserContactInfoResponse"
examples:
business_contact:
summary: Registered business contact
value:
code: 200
data:
phone: "5511988888888"
jid: 5511988888888@s.whatsapp.net
input_type: phone
lid: 123456789012346@lid
is_on_whatsapp: true
verified_name: Example Store
user_info:
status: Open Monday to Friday
picture_id: "1728656243"
verified_name: Example Store
is_business_account: true
device_count: 1
devices:
- user: "5511988888888"
agent: "0"
device: UNKNOWN
server: s.whatsapp.net
ad: 5511988888888.0:0@s.whatsapp.net
jid: 5511988888888@s.whatsapp.net
avatar:
url: https://pps.whatsapp.net/v/t61.24694-24/123456789_1234567890123456_1234567890123456789_n.jpg?ccb=11-4&oh=01_Q5AaIExample&oe=68E0A1B2
id: "1728656243"
type: image
direct_path: /v/t61.24694-24/123456789_1234567890123456_1234567890123456789_n.jpg?ccb=11-4&oh=01_Q5AaIExample&oe=68E0A1B2
base64: data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2Q==
width: 640
height: 640
preview_url: https://pps.whatsapp.net/v/t61.24694-24/123456789_1234567890123456_1234567890123456789_n.jpg?stp=dst-jpg_s96x96&ccb=11-4&oh=01_Q5AaIExample&oe=68E0A1B2
preview_direct_path: /v/t61.24694-24/123456789_1234567890123456_1234567890123456789_n.jpg?stp=dst-jpg_s96x96&ccb=11-4&oh=01_Q5AaIExample&oe=68E0A1B2
contact_names:
first_name: Example
full_name: Example Store
push_name: Example Store
business_name: Example Store
business_profile:
address: 100 Example Avenue, Sao Paulo
email: contact@example.com
business_hours_timezone: America/Sao_Paulo
categories:
- id: "133436743388217"
name: Shopping & Retail
profile_options:
commerce_experience: catalog
business_hours:
- day_of_week: mon
mode: specific_hours
open_time: "09:00"
close_time: "18:00"
success: true
not_on_whatsapp:
summary: Number without WhatsApp
value:
code: 200
data:
phone: "5511977777777"
jid: 5511977777777@s.whatsapp.net
input_type: phone
is_on_whatsapp: false
lid: null
user_info: null
devices: null
avatar: null
contact_names: null
business_profile: null
success: true
"400":
description: "Bad Request: invalid JSON, `phone` missing, or `phone` is not a valid number/JID/LID."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
could_not_decode_payload:
summary: Body is not valid JSON
value:
code: 400
error: could not decode payload
success: false
missing_phone:
summary: phone missing
value:
code: 400
error: missing phone in payload
success: false
invalid_phone:
summary: phone cannot be parsed
value:
code: 400
error: invalid phone number, JID, or LID
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"404":
description: "Not Found: the LID has no cached phone mapping on this gateway."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 404
error: could not resolve LID to phone number. The LID mapping may not be cached locally
success: false
"500":
description: "Internal Server Error: no WhatsApp session, LID store unavailable, or the registration check failed."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: No WhatsApp session for this user
value:
code: 500
error: no session
success: false
lid_store_unavailable:
summary: LID input but the LID store is not initialized
value:
code: 500
error: LID store not available
success: false
check_failed:
summary: Registration check failed
value:
code: 500
error: "failed to check WhatsApp registration: websocket not connected"
success: false
/user/contact/add:
post:
tags:
- User
summary: Add or rename a contact
description: |
Saves a contact name in the account address book, or renames an existing contact. The change is synced to the phone and every linked device through app state.
**Rules:**
- `phone` and `full_name` are required and cannot be empty.
- `phone` accepts a phone number with country code or a user JID.
- On sync conflicts (409 or LTHash mismatch) the gateway runs a full app-state sync and retries up to 3 times before failing with **500**.
**Use Cases:**
- Keep WhatsApp contact names aligned with a CRM
- Save a lead so their profile photo and status become visible under "My contacts" privacy
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/UserContactAddRequest"
examples:
new_contact:
summary: Save a new contact
description: Adds the number to the address book with the given name.
value:
phone: "5511999999999"
full_name: Maria Silva
rename_by_jid:
summary: Rename an existing contact by JID
description: Sending an already saved contact replaces its name.
value:
phone: 5511988888888@s.whatsapp.net
full_name: Example Store - Sales
responses:
"200":
description: Contact saved and synced.
content:
application/json:
schema:
$ref: "#/components/schemas/UserContactAddResponse"
example:
code: 200
data:
success: true
message: Contact added successfully
phone: "5511999999999"
full_name: Maria Silva
success: true
"400":
description: "Bad Request: invalid JSON, a required field is empty, or `phone` cannot be parsed."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
could_not_decode_payload:
summary: Body is not valid JSON
value:
code: 400
error: could not decode payload
success: false
empty_phone:
summary: phone missing or empty
value:
code: 400
error: phone number cannot be empty
success: false
empty_full_name:
summary: full_name missing or empty
value:
code: 400
error: full name cannot be empty
success: false
invalid_phone:
summary: phone cannot be parsed
value:
code: 400
error: could not parse phone number
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: no WhatsApp session, or the app-state update failed after the recovery attempts."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: No WhatsApp session for this user
value:
code: 500
error: no session
success: false
update_failed:
summary: App-state update failed
value:
code: 500
error: "failed to add contact: app state error (not recoverable): websocket not connected"
success: false
/user/contact/remove:
post:
tags:
- User
summary: Remove a saved contact
description: |
Deletes a contact from the account address book. The removal is synced to the phone and every linked device; chats and messages are kept.
**Rules:**
- `phone` is required: a phone number with country code or a user JID.
- Removing a number that is not saved is forwarded to WhatsApp as is.
- On sync conflicts (409 or LTHash mismatch) the gateway runs a full app-state sync and retries up to 3 times before failing with **500**.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/UserContactRemoveRequest"
examples:
by_phone:
summary: Remove by phone number
description: Phone number with country code, without `+`.
value:
phone: "5511999999999"
by_jid:
summary: Remove by JID
description: A full phone JID is accepted as well.
value:
phone: 5511999999999@s.whatsapp.net
responses:
"200":
description: Contact removed and synced.
content:
application/json:
schema:
$ref: "#/components/schemas/UserContactRemoveResponse"
example:
code: 200
data:
success: true
message: Contact removed successfully
phone: "5511999999999"
success: true
"400":
description: "Bad Request: invalid JSON, `phone` empty, or `phone` cannot be parsed."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
could_not_decode_payload:
summary: Body is not valid JSON
value:
code: 400
error: could not decode payload
success: false
empty_phone:
summary: phone missing or empty
value:
code: 400
error: phone number cannot be empty
success: false
invalid_phone:
summary: phone cannot be parsed
value:
code: 400
error: could not parse phone number
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: no WhatsApp session, or the app-state update failed after the recovery attempts."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: No WhatsApp session for this user
value:
code: 500
error: no session
success: false
update_failed:
summary: App-state update failed
value:
code: 500
error: "failed to remove contact: app state error (not recoverable): websocket not connected"
success: false
/user/status:
get:
tags:
- User
summary: Get your status (about) text
description: |
Returns the status ("about") text of the connected account, as WhatsApp currently reports it.
**Rules:**
- No query parameters or body. The session must be paired; before pairing the call returns **500** `could not get own JID`.
- `status` is an empty string when no text is set.
security:
- ApiKeyAuth: []
responses:
"200":
description: Current status text.
content:
application/json:
schema:
$ref: "#/components/schemas/UserStatusGetResponse"
example:
code: 200
data:
status: Available for support 9am-6pm
success: true
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: no WhatsApp session, session not paired, or the WhatsApp query failed."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: No WhatsApp session for this user
value:
code: 500
error: no session
success: false
not_paired:
summary: Session has no own JID yet
value:
code: 500
error: could not get own JID
success: false
query_failed:
summary: WhatsApp query failed
value:
code: 500
error: "failed to get status: websocket not connected"
success: false
post:
tags:
- User
summary: Set your status (about) text
description: |
Sets the status ("about") text of the connected account, shown on your profile to people allowed by your status privacy.
**Rules:**
- `status` is sent as given; an empty string or a missing field clears the text.
- The gateway does not check the length; WhatsApp limits the text to 139 characters and rejects longer values with **500**.
- Emoji and other multibyte text are sent as given (validated live with `π» Setup Automatizado`).
- The text travels in the classic `` stanza, the same one the official web client uses for
the About field. The newer GraphQL "text status" mutation (emoji plus ephemeral duration) is gated per account and
answers `400 Bad Request` outside the rollout, so it is never used for a plain text status.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/SetMyStatusRequest"
examples:
business_hours:
summary: Set a status text
description: Replaces the current about text.
value:
status: Available for support 9am-6pm
clear:
summary: Clear the status text
description: An empty string removes the about text.
value:
status: ""
responses:
"200":
description: Status text updated.
content:
application/json:
schema:
$ref: "#/components/schemas/UserStatusSetResponse"
example:
code: 200
data:
success: true
message: Status updated successfully
status: Available for support 9am-6pm
success: true
"400":
description: "Bad Request: the body is not valid JSON."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 400
error: could not decode payload
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: no WhatsApp session, or WhatsApp rejected the status text."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: No WhatsApp session for this user
value:
code: 500
error: no session
success: false
set_failed:
summary: WhatsApp rejected the update
value:
code: 500
error: "failed to set status: websocket not connected"
success: false
/user/update:
post:
tags:
- User
summary: Update your gateway user name or token
description: |
Changes the gateway user record of the caller: its display name, its API token, or both. This does not touch the WhatsApp profile (see `POST /user/pushname` for that).
**Rules:**
- Send `name`, `token` or both. Empty strings and values equal to the current ones are ignored; if nothing changes the request returns **400**.
- `name` may have at most 255 characters. A new `token` needs at least 8 characters and must not belong to another user (**409**).
- The update uses optimistic locking on the current token; a concurrent change returns **409**.
**Side effects:**
- When the token changes, the old token stops authenticating immediately and the cached user configuration is reloaded under the new token.
- The response echoes the final token in clear text; treat it as a secret.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/UserUpdateRequest"
examples:
rename:
summary: Change only the name
description: The token stays the same.
value:
name: sales-team
rotate_token:
summary: Rotate the API token
description: The old token is revoked as soon as the response is sent.
value:
token: 9f8e7d6c5b4a3210fedcba98
both:
summary: Change name and token
description: Both values are written in the same update.
value:
name: support-team
token: 0a1b2c3d4e5f67890a1b2c3d
responses:
"200":
description: User record updated.
content:
application/json:
schema:
$ref: "#/components/schemas/UserUpdateResponse"
example:
code: 200
data:
id: 3f0b9f2c8e7d4a6b9c1d2e3f4a5b6c7d
name: sales-team
token: 9f8e7d6c5b4a3210fedcba98
message: Profile updated successfully
success: true
"400":
description: "Bad Request: invalid JSON, no effective change, name too long, or token shorter than 8 characters."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
invalid_json:
summary: Body is not valid JSON
value:
code: 400
error: Invalid JSON
success: false
no_changes:
summary: Both fields empty or equal to the current values
value:
code: 400
error: No changes detected
success: false
name_too_long:
summary: name longer than 255 characters
value:
code: 400
error: Name too long (max 255 characters)
success: false
token_too_short:
summary: New token shorter than 8 characters
value:
code: 400
error: Token too short (min 8 characters)
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"409":
description: "Conflict: the new token belongs to another user, or the record changed during the update."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
token_in_use:
summary: Token already used by another user
value:
code: 409
error: Token already in use
success: false
concurrent_update:
summary: Record modified by another request
value:
code: 409
error: Profile was modified by another request. Please try again
success: false
"500":
description: "Internal Server Error: database failure while checking or writing the record."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 500
error: "Failed to update profile: pq: could not serialize access due to concurrent update"
success: false
/user/business/profile:
post:
tags:
- User
summary: Get a business profile
description: |
Returns the public WhatsApp Business profile of an account: address, email, categories, business hours and profile options, together with its status text and verified name.
**Rules:**
- `phone` is required: a phone number with country code or a user JID.
- A personal account (no verified name) whose profile lookup fails with "not found" returns **404**; other lookup failures return **500**.
- A verified business whose profile data cannot be read still returns **200** with `is_business_account: true` and `profile_data_available: false`.
**Response:**
- `open_time`/`close_time` are formatted as `HH:MM`; `categories`, `business_hours` and `profile_options` are `null` when the profile has none.
- `verified_name`, `status` and `picture_id` are omitted when empty; `business_name` is never filled by this endpoint.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/BusinessProfileRequest"
examples:
by_phone:
summary: Business phone number
description: Phone number with country code, without `+`.
value:
phone: "5511988888888"
by_jid:
summary: Business JID
description: A full phone JID is accepted as well.
value:
phone: 5511988888888@s.whatsapp.net
responses:
"200":
description: Business profile data.
content:
application/json:
schema:
$ref: "#/components/schemas/UserBusinessProfileResponse"
examples:
full_profile:
summary: Business with public profile data
value:
code: 200
data:
jid: 5511988888888@s.whatsapp.net
email: contact@example.com
address: 100 Example Avenue, Sao Paulo
categories:
- id: "133436743388217"
name: Shopping & Retail
profile_options:
commerce_experience: catalog
business_hours_timezone: America/Sao_Paulo
business_hours:
- day_of_week: mon
mode: specific_hours
open_time: "09:00"
close_time: "18:00"
- day_of_week: sat
mode: open_24h
open_time: ""
close_time: ""
verified_name: Example Store
status: Open Monday to Friday
picture_id: "1728656243"
is_business_account: true
profile_data_available: true
success: true
verified_without_profile:
summary: Verified business without readable profile data
value:
code: 200
data:
jid: 5511988888888@s.whatsapp.net
email: ""
address: ""
categories: null
profile_options: null
business_hours_timezone: ""
business_hours: null
verified_name: Example Store
is_business_account: true
profile_data_available: false
success: true
"400":
description: "Bad Request: invalid JSON, `phone` missing, or `phone` cannot be parsed."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
could_not_decode_payload:
summary: Body is not valid JSON
value:
code: 400
error: could not decode payload
success: false
missing_phone:
summary: phone missing
value:
code: 400
error: missing phone number in payload
success: false
invalid_phone:
summary: phone cannot be parsed
value:
code: 400
error: invalid phone number
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"404":
description: "Not Found: the account is not a WhatsApp Business account or has no public business profile."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 404
error: this number is not a WhatsApp Business account or does not have a public business profile
success: false
"500":
description: "Internal Server Error: no WhatsApp session, or the business profile query failed for another reason."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: No WhatsApp session for this user
value:
code: 500
error: no session
success: false
query_failed:
summary: WhatsApp query failed
value:
code: 500
error: "failed to get business profile: info query timed out"
success: false
/user/check:
post:
tags:
- User
summary: Check if phone numbers are on WhatsApp
description: |
Checks whether phone numbers have a WhatsApp account and returns, for each one, the phone JID, the LID, business verification data, the username and the default disappearing-message setting.
**Rules:**
- `Phone` is required and must be a non-empty array of strings (a plain string fails to decode and returns **400**). The field name is matched case-insensitively, so `phone` also works.
- Send numbers in international format; the gateway passes them to WhatsApp as given.
- A missing WhatsApp session returns **500** `no session`; a failed WhatsApp query returns **500**.
**Response:**
- `data.Users` has one entry per number, in the order returned by WhatsApp.
- `JID` stays phone-shaped (`@s.whatsapp.net`) for backward compatibility; the LID is reported separately in `LID`.
- `Username`, `VerifiedLevel` and `DisappearingMode` are omitted when WhatsApp does not report them. Usernames are still rolling out, so `Username` is usually absent.
**Use Cases:**
- Clean a contact list before a campaign
- Discover the LID of a number before addressing it by LID
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/Checkuser"
examples:
single:
summary: One number
description: Checks a single number; the array form is mandatory even for one value.
value:
Phone:
- "5511999999999"
several:
summary: Several numbers
description: Checks three numbers in one WhatsApp query.
value:
Phone:
- "5511999999999"
- "5511988888888"
- "5511977777777"
responses:
"200":
description: One result per queried number.
content:
application/json:
schema:
$ref: "#/components/schemas/UserCheckResponse"
example:
code: 200
data:
Users:
- Query: "5511988888888"
IsInWhatsapp: true
JID: 5511988888888@s.whatsapp.net
LID: 123456789012346@lid
VerifiedName: Example Store
Username: examplestore
VerifiedLevel: high
DisappearingMode:
enabled: true
duration_sec: 604800
set_at: "2026-07-01T12:34:56Z"
- Query: "5511977777777"
IsInWhatsapp: false
JID: 5511977777777@s.whatsapp.net
LID: ""
VerifiedName: ""
success: true
"400":
description: "Bad Request: the body cannot be decoded (for example `Phone` sent as a string) or the list is empty."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
could_not_decode_payload:
summary: Invalid JSON or Phone is not an array
value:
code: 400
error: could not decode Payload
success: false
missing_phone:
summary: Phone missing or empty
value:
code: 400
error: missing Phone in Payload
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: no WhatsApp session for this user, or the WhatsApp registration query failed."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: No WhatsApp session for this user
value:
code: 500
error: no session
success: false
query_failed:
summary: WhatsApp query failed
value:
code: 500
error: "failed to check if users are on WhatsApp: websocket not connected"
success: false
/user/presence:
post:
tags:
- User
summary: Set your global presence
description: |
Sets the global presence of the connected account to `available` (online) or `unavailable` (offline). Contacts allowed by your "online" privacy setting see the change.
**Rules:**
- `type` is required and must be exactly `available` or `unavailable` (lower case).
- WhatsApp requires the account push name to be known; right after pairing, before the push name syncs, sending presence fails with **500**.
- Staying `available` keeps delivery receipts active and can stop push notifications on the phone. See `POST /session/presence/config` to switch back to `unavailable` automatically after connecting.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/UserPresence"
examples:
available:
summary: Appear online
description: Marks the account as online until changed or disconnected.
value:
type: available
unavailable:
summary: Appear offline
description: Marks the account as offline; the phone keeps receiving push notifications.
value:
type: unavailable
responses:
"200":
description: Presence sent to WhatsApp.
content:
application/json:
schema:
$ref: "#/components/schemas/UserPresenceResponse"
example:
code: 200
data:
Details: Presence set successfuly
success: true
"400":
description: "Bad Request: invalid JSON, or `type` is not `available`/`unavailable`."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
could_not_decode_payload:
summary: Body is not valid JSON
value:
code: 400
error: could not decode Payload
success: false
invalid_type:
summary: type missing or not allowed
value:
code: 400
error: "invalid presence type. Allowed values: 'available', 'unavailable'"
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: no WhatsApp session, or WhatsApp did not accept the presence (for example push name not synced yet)."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: No WhatsApp session for this user
value:
code: 500
error: no session
success: false
send_failed:
summary: Presence not accepted
value:
code: 500
error: failure sending presence to Whatsapp servers
success: false
/user/avatar:
post:
tags:
- User
summary: Get profile picture information
description: |
Returns the profile picture URL and metadata of a contact, group or community, either the full image or the small preview thumbnail. The image itself is not downloaded by the gateway.
**Features:**
- `Preview: true` returns the thumbnail; `false` returns the full-resolution image.
- `CommonGID` fetches a member's picture through a group you share, which can succeed when the contact restricts the picture to contacts.
- `InviteCode` fetches a group picture before joining, using the invite code.
- `PersonaID` fetches the picture of a Meta AI persona; `IsCommunity` marks a community JID.
**Rules:**
- `Phone` is required: phone number, user JID, group JID or community JID. Field names are matched case-insensitively.
- `CommonGID`, when present, must be a valid JID (**400** otherwise).
- WhatsApp errors, including "no profile picture" and "hidden by privacy", return **500** with the reason in the message.
- The returned `url` expires; download it promptly.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/Checkavatar"
examples:
preview:
summary: Thumbnail of a contact
description: Smallest payload; good for chat lists.
value:
Phone: "5511999999999"
Preview: true
full_via_group:
summary: Full picture through a shared group
description: Uses a group both accounts belong to as the access context.
value:
Phone: 5511999999999@s.whatsapp.net
Preview: false
CommonGID: 120363000000000011@g.us
group_invite:
summary: Group picture before joining
description: Reads the picture of a group you are not in, authorized by its invite code.
value:
Phone: 120363000000000011@g.us
Preview: true
InviteCode: AbCdEfGhIjKlMnOpQrStUv
community:
summary: Community picture
description: Full picture of a community parent group.
value:
Phone: 120363000000000022@g.us
Preview: false
IsCommunity: true
responses:
"200":
description: Profile picture metadata.
content:
application/json:
schema:
$ref: "#/components/schemas/UserAvatarResponse"
example:
code: 200
data:
url: https://pps.whatsapp.net/v/t61.24694-24/123456789_1234567890123456_1234567890123456789_n.jpg?ccb=11-4&oh=01_Q5AaIExample&oe=68E0A1B2
id: "1700000000"
type: preview
direct_path: /v/t61.24694-24/123456789_1234567890123456_1234567890123456789_n.jpg?ccb=11-4&oh=01_Q5AaIExample&oe=68E0A1B2
hash: null
success: true
"400":
description: "Bad Request: invalid JSON, `Phone` missing, or `Phone`/`CommonGID` is not a valid JID."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
could_not_decode_payload:
summary: Body is not valid JSON
value:
code: 400
error: could not decode Payload
success: false
missing_phone:
summary: Phone missing
value:
code: 400
error: missing Phone in Payload
success: false
invalid_phone:
summary: Phone is not a valid number or JID
value:
code: 400
error: could not parse Phone
success: false
invalid_common_gid:
summary: CommonGID is not a valid JID
value:
code: 400
error: could not parse CommonGID
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: no WhatsApp session, no picture set, picture hidden by privacy, or another WhatsApp failure."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: No WhatsApp session for this user
value:
code: 500
error: no session
success: false
not_set:
summary: The account has no profile picture
value:
code: 500
error: "failed to get avatar: that user or group does not have a profile picture"
success: false
hidden:
summary: Picture hidden by the contact's privacy settings
value:
code: 500
error: "failed to get avatar: the user has hidden their profile picture from you"
success: false
no_avatar_found:
summary: WhatsApp returned no picture information
value:
code: 500
error: no avatar found
success: false
/user/photo:
post:
tags:
- User
summary: Set your own profile photo
description: |
Sets or replaces the profile photo of the connected WhatsApp account. The change is visible to everyone allowed by your profile photo privacy setting.
**Rules:**
- `Image` is required: a base64 data URL (`data:image/jpeg;base64,...`) or an `http(s)` URL that the gateway downloads.
- The decoded bytes must be a JPEG image (checked by its file signature); PNG, WebP and other formats return **400**.
- Square images up to 640x640 px are recommended; WhatsApp may reject very large images.
**Response quirk:**
- When WhatsApp rejects the upload, the response has HTTP **500** but the legacy body `success: true` with the error text in `data` (no `error` field). Check the HTTP status, not `success`.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/SetProfilePhoto"
examples:
base64:
summary: JPEG as a base64 data URL
description: The data URL must carry JPEG bytes; the media type in the prefix is not checked, the bytes are.
value:
Image: data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/wAALCAABAAEBAREA/8QAFAABAAAAAAAAAAAAAAAAAAAACf/EABQQAQAAAAAAAAAAAAAAAAAAAAD/2gAIAQEAAD8AKp//2Q==
url:
summary: JPEG downloaded from a URL
description: The gateway downloads the file and validates the JPEG signature before uploading it.
value:
Image: https://example.com/images/profile.jpg
responses:
"200":
description: Profile photo updated.
content:
application/json:
schema:
$ref: "#/components/schemas/UserPhotoResponse"
example:
code: 200
data:
Details: Profile photo set successfully
PictureID: "1757862000"
success: true
"400":
description: "Bad Request: invalid JSON, `Image` missing or not a data URL/URL, download failure, empty data, or non-JPEG image."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
could_not_decode_payload:
summary: Body is not valid JSON
value:
code: 400
error: could not decode Payload
success: false
missing_image:
summary: Image missing
value:
code: 400
error: missing Image in Payload
success: false
unsupported_input:
summary: Image is neither a data URL nor an HTTP(S) URL
value:
code: 400
error: Image must be a base64 data URL ("data:image/jpeg;base64,...") or an HTTP/HTTPS URL
success: false
download_failed:
summary: The URL could not be downloaded
value:
code: 400
error: "could not download image from URL: HTTP error 404 when downloading from URL"
success: false
bad_base64:
summary: Invalid base64 in the data URL
value:
code: 400
error: could not decode base64 encoded data from payload
success: false
empty_image:
summary: Data URL without bytes
value:
code: 400
error: no image data found in payload
success: false
not_jpeg:
summary: Image is not JPEG
value:
code: 400
error: image must be in JPEG format. WhatsApp only accepts JPEG images for profile photos
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: no WhatsApp session (standard error body), or WhatsApp rejected the photo (legacy body with `success: true` and the message in `data`)."
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/ErrorEnvelope"
- $ref: "#/components/schemas/LegacyErrorEnvelope"
examples:
no_session:
summary: No WhatsApp session for this user
value:
code: 500
error: no session
success: false
upload_rejected_legacy:
summary: WhatsApp rejected the photo (legacy body)
value:
code: 500
data: "failed to set profile photo: websocket not connected"
success: true
/user/photo/remove:
post:
tags:
- User
summary: Remove your own profile photo
description: |
Removes the profile photo of the connected WhatsApp account; contacts then see the default placeholder avatar.
**Rules:**
- No request body is read.
- Removing when no photo is set is forwarded to WhatsApp as is.
**Response quirk:**
- When WhatsApp rejects the removal, the response has HTTP **500** but the legacy body `success: true` with the error text in `data` (no `error` field). Check the HTTP status, not `success`.
security:
- ApiKeyAuth: []
responses:
"200":
description: Profile photo removed.
content:
application/json:
schema:
$ref: "#/components/schemas/UserPhotoRemoveResponse"
example:
code: 200
data:
Details: Profile photo removed successfully
success: true
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: no WhatsApp session (standard error body), or WhatsApp rejected the removal (legacy body with `success: true` and the message in `data`)."
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/ErrorEnvelope"
- $ref: "#/components/schemas/LegacyErrorEnvelope"
examples:
no_session:
summary: No WhatsApp session for this user
value:
code: 500
error: no session
success: false
removal_rejected_legacy:
summary: WhatsApp rejected the removal (legacy body)
value:
code: 500
data: "failed to remove profile photo: websocket not connected"
success: true
/user/contacts:
get:
tags:
- User
summary: List saved contacts
description: |
Lists every contact kept in the local contact store of the session: saved address-book names, push names, business names and usernames learned from app state and messages.
**Rules:**
- No parameters. Data comes from the local store; WhatsApp is not queried.
- The session must be paired (**500** `not logged in`); an empty store returns **200** with an empty object.
**Response:**
- `data` is an object keyed by JID (phone JIDs and LIDs can both appear).
- `RedactedPhone` is only filled for LID members seen in groups, in the masked form WhatsApp shows (for example `+55ββββββββ99`).
security:
- ApiKeyAuth: []
responses:
"200":
description: Contacts keyed by JID.
content:
application/json:
schema:
$ref: "#/components/schemas/UserContactsResponse"
example:
code: 200
data:
5511999999999@s.whatsapp.net:
Found: true
FirstName: Maria
FullName: Maria Silva
PushName: Maria
BusinessName: ""
Username: ""
RedactedPhone: ""
123456789012346@lid:
Found: true
FirstName: ""
FullName: ""
PushName: Example Store
BusinessName: Example Store
Username: examplestore
RedactedPhone: "+55ββββββββ88"
success: true
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: no WhatsApp session, session not paired, or the contact store failed."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: No WhatsApp session for this user
value:
code: 500
error: no session
success: false
not_logged_in:
summary: Session not paired yet
value:
code: 500
error: not logged in
success: false
/user/lid/get:
get:
tags:
- User LID
summary: Look up the LID of a phone number (query string)
description: |
Looks up, in the local LID store of this session, the LID mapped to a phone number or phone JID. Use this GET form when the number fits in the query string.
**Rules:**
- Pass the number in the `phone` query parameter. Without it the handler tries to read a JSON body, and a GET without body fails with `Invalid JSON format`.
- `phone` accepts a number with country code (a leading `+` is stripped) or a phone JID. A value that is already a LID returns **400**.
- Only the local store is consulted; WhatsApp is not queried. An unknown number returns **200** with `has_lid: false`.
**Response quirk:**
- Validation and store errors of this endpoint use a legacy body: the HTTP status is 400/500 but the body has `success: true` and the message in `data.error`. Check the HTTP status.
security:
- ApiKeyAuth: []
parameters:
- name: phone
in: query
required: false
description: Phone number with country code, or phone JID. Required unless a JSON body with `phone` is sent.
schema:
type: string
example: "5511999999999"
responses:
"200":
description: Lookup result; `has_lid` tells whether a mapping exists.
content:
application/json:
schema:
$ref: "#/components/schemas/UserLIDGetResponse"
examples:
mapped:
summary: Mapping found
value:
code: 200
data:
success: true
phone: 5511999999999@s.whatsapp.net
lid: 123456789012345@lid
has_lid: true
success: true
not_mapped:
summary: No mapping stored yet
value:
code: 200
data:
success: true
phone: 5511977777777@s.whatsapp.net
lid: ""
has_lid: false
success: true
"400":
description: "Bad Request (legacy body): `phone` missing, unparseable, or already a LID."
content:
application/json:
schema:
$ref: "#/components/schemas/LegacyErrorEnvelope"
examples:
no_phone_no_body:
summary: No phone query parameter and no JSON body
value:
code: 400
data:
error: Invalid JSON format
success: true
phone_required:
summary: Body sent without phone
value:
code: 400
data:
error: Phone parameter is required
success: true
unparseable:
summary: phone is not a valid number or JID
value:
code: 400
data:
error: Could not parse phone number or JID
success: true
already_lid:
summary: phone is already a LID
value:
code: 400
data:
error: Provided identifier is already a LID, not a phone number
success: true
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error (legacy body): no WhatsApp session, or the LID store query failed."
content:
application/json:
schema:
$ref: "#/components/schemas/LegacyErrorEnvelope"
examples:
no_client:
summary: No WhatsApp session for this user
value:
code: 500
data:
error: WhatsApp client not found
success: true
store_failed:
summary: LID store query failed
value:
code: 500
data:
error: "Failed to get LID: sql: database is closed"
success: true
post:
tags:
- User LID
summary: Look up the LID of a phone number (JSON body)
description: |
Looks up, in the local LID store of this session, the LID mapped to a phone number or phone JID, taking the number from a JSON body. Behaves like the GET form; use it when your client prefers POST bodies.
**Rules:**
- Send `phone` in the body. If the `phone` query parameter is also present, the query value wins and the body is not read.
- `phone` accepts a number with country code (a leading `+` is stripped) or a phone JID. A value that is already a LID returns **400**.
- Only the local store is consulted; an unknown number returns **200** with `has_lid: false`.
**Response quirk:**
- Validation and store errors use a legacy body with `success: true` and the message in `data.error`, even though the HTTP status is 400/500.
security:
- ApiKeyAuth: []
parameters:
- name: phone
in: query
required: false
description: Optional override. When present, it is used instead of the body `phone`.
schema:
type: string
example: "5511999999999"
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/GetLIDRequest"
examples:
number:
summary: Phone number
description: Number with country code, without `+`.
value:
phone: "5511999999999"
jid:
summary: Phone JID
description: A full phone JID is accepted as well.
value:
phone: 5511999999999@s.whatsapp.net
responses:
"200":
description: Lookup result; `has_lid` tells whether a mapping exists.
content:
application/json:
schema:
$ref: "#/components/schemas/UserLIDGetResponse"
example:
code: 200
data:
success: true
phone: 5511999999999@s.whatsapp.net
lid: 123456789012345@lid
has_lid: true
success: true
"400":
description: "Bad Request (legacy body): invalid JSON, `phone` missing, unparseable, or already a LID."
content:
application/json:
schema:
$ref: "#/components/schemas/LegacyErrorEnvelope"
examples:
invalid_json:
summary: Body is not valid JSON
value:
code: 400
data:
error: Invalid JSON format
success: true
phone_required:
summary: phone missing or empty
value:
code: 400
data:
error: Phone parameter is required
success: true
unparseable:
summary: phone is not a valid number or JID
value:
code: 400
data:
error: Could not parse phone number or JID
success: true
already_lid:
summary: phone is already a LID
value:
code: 400
data:
error: Provided identifier is already a LID, not a phone number
success: true
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error (legacy body): no WhatsApp session, or the LID store query failed."
content:
application/json:
schema:
$ref: "#/components/schemas/LegacyErrorEnvelope"
examples:
no_client:
summary: No WhatsApp session for this user
value:
code: 500
data:
error: WhatsApp client not found
success: true
store_failed:
summary: LID store query failed
value:
code: 500
data:
error: "Failed to get LID: sql: database is closed"
success: true
/user/lid/from-lid:
get:
tags:
- User LID
summary: Look up the phone number of a LID (query string)
description: |
Translates a LID back to the phone JID using the local LID store of this session. This GET form takes the LID from the query string.
**Rules:**
- Pass the LID in the `lid` query parameter, including the `@lid` suffix. Without it the handler tries to read a JSON body, and a GET without body fails with `Invalid JSON format`.
- A value that is not an `@lid` JID returns **400**.
- Only the local store is consulted; a LID without a stored mapping returns **404**.
**Response quirk:**
- Every non-401 error uses a legacy body with `success: true` and the message in `data.error`. Check the HTTP status.
security:
- ApiKeyAuth: []
parameters:
- name: lid
in: query
required: false
description: LID with `@lid` suffix. Required unless a JSON body with `lid` is sent.
schema:
type: string
example: 123456789012345@lid
responses:
"200":
description: Phone JID mapped to the LID.
content:
application/json:
schema:
$ref: "#/components/schemas/UserJIDFromLIDResponse"
example:
code: 200
data:
success: true
lid: 123456789012345@lid
phone: 5511999999999@s.whatsapp.net
success: true
"400":
description: "Bad Request (legacy body): `lid` missing, malformed, or not an `@lid` JID."
content:
application/json:
schema:
$ref: "#/components/schemas/LegacyErrorEnvelope"
examples:
no_lid_no_body:
summary: No lid query parameter and no JSON body
value:
code: 400
data:
error: Invalid JSON format
success: true
lid_required:
summary: Body sent without lid
value:
code: 400
data:
error: LID parameter is required
success: true
malformed:
summary: lid cannot be parsed as a JID
value:
code: 400
data:
error: "Invalid LID format: unexpected number of dots in JID"
success: true
not_lid:
summary: lid is a phone JID
value:
code: 400
data:
error: Provided identifier is not a LID
success: true
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"404":
description: "Not Found (legacy body): the LID has no phone mapping in the local store."
content:
application/json:
schema:
$ref: "#/components/schemas/LegacyErrorEnvelope"
example:
code: 404
data:
error: Phone number not found for this LID
success: true
"500":
description: "Internal Server Error (legacy body): no WhatsApp session, or the LID store query failed."
content:
application/json:
schema:
$ref: "#/components/schemas/LegacyErrorEnvelope"
examples:
no_client:
summary: No WhatsApp session for this user
value:
code: 500
data:
error: WhatsApp client not found
success: true
store_failed:
summary: LID store query failed
value:
code: 500
data:
error: "Failed to get phone number: sql: database is closed"
success: true
post:
tags:
- User LID
summary: Look up the phone number of a LID (JSON body)
description: |
Translates a LID back to the phone JID using the local LID store of this session, taking the LID from a JSON body. Same result as the GET form.
**Rules:**
- Send `lid` in the body with the `@lid` suffix. If the `lid` query parameter is also present, the query value wins and the body is not read.
- A value that is not an `@lid` JID returns **400**; a LID without a stored mapping returns **404**.
**Response quirk:**
- Every non-401 error uses a legacy body with `success: true` and the message in `data.error`, even though the HTTP status is 400/404/500.
security:
- ApiKeyAuth: []
parameters:
- name: lid
in: query
required: false
description: Optional override. When present, it is used instead of the body `lid`.
schema:
type: string
example: 123456789012345@lid
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/GetJIDFromLIDRequest"
examples:
lid:
summary: LID from a group participant
description: LIDs usually come from group events, where members are addressed by LID.
value:
lid: 123456789012345@lid
responses:
"200":
description: Phone JID mapped to the LID.
content:
application/json:
schema:
$ref: "#/components/schemas/UserJIDFromLIDResponse"
example:
code: 200
data:
success: true
lid: 123456789012345@lid
phone: 5511999999999@s.whatsapp.net
success: true
"400":
description: "Bad Request (legacy body): invalid JSON, `lid` missing, malformed, or not an `@lid` JID."
content:
application/json:
schema:
$ref: "#/components/schemas/LegacyErrorEnvelope"
examples:
invalid_json:
summary: Body is not valid JSON
value:
code: 400
data:
error: Invalid JSON format
success: true
lid_required:
summary: lid missing or empty
value:
code: 400
data:
error: LID parameter is required
success: true
not_lid:
summary: lid is a phone JID
value:
code: 400
data:
error: Provided identifier is not a LID
success: true
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"404":
description: "Not Found (legacy body): the LID has no phone mapping in the local store."
content:
application/json:
schema:
$ref: "#/components/schemas/LegacyErrorEnvelope"
example:
code: 404
data:
error: Phone number not found for this LID
success: true
"500":
description: "Internal Server Error (legacy body): no WhatsApp session, or the LID store query failed."
content:
application/json:
schema:
$ref: "#/components/schemas/LegacyErrorEnvelope"
examples:
no_client:
summary: No WhatsApp session for this user
value:
code: 500
data:
error: WhatsApp client not found
success: true
store_failed:
summary: LID store query failed
value:
code: 500
data:
error: "Failed to get phone number: sql: database is closed"
success: true
/user/lid/mappings:
get:
tags:
- User LID
summary: List LID mappings of saved contacts
description: |
Lists the phone-to-LID mappings known for the contacts in the local contact store. For each stored contact the gateway looks up its LID and returns the pairs that exist.
**Rules:**
- No parameters; WhatsApp is not queried.
- Only contacts present in the contact store are considered, so this is not the complete LID table of the session.
- The session must be paired (**500** `not logged in`).
**Response:**
- `mappings` is `null` and `message` is `No LID mappings found` when no pair exists.
- A missing client and contact-store failures use a legacy error body (`success: true`, message in `data.error`).
security:
- ApiKeyAuth: []
responses:
"200":
description: Stored phone/LID pairs.
content:
application/json:
schema:
$ref: "#/components/schemas/LIDMappingsResponse"
examples:
with_mappings:
summary: Mappings found
value:
code: 200
data:
success: true
mappings:
- lid: 123456789012345@lid
phone: 5511999999999@s.whatsapp.net
- lid: 123456789012346@lid
phone: 5511988888888@s.whatsapp.net
count: 2
success: true
empty:
summary: No mappings yet
value:
code: 200
data:
success: true
mappings: null
count: 0
message: No LID mappings found
success: true
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: session not paired (standard body), or no client / contact store failure (legacy body)."
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/ErrorEnvelope"
- $ref: "#/components/schemas/LegacyErrorEnvelope"
examples:
not_logged_in:
summary: Session not paired yet
value:
code: 500
error: not logged in
success: false
no_client_legacy:
summary: No WhatsApp session for this user (legacy body)
value:
code: 500
data:
error: WhatsApp client not found
success: true
store_failed_legacy:
summary: Contact store failure (legacy body)
value:
code: 500
data:
error: "Failed to get contacts: sql: database is closed"
success: true
/chat/delete:
post:
tags:
- Chat
summary: Delete a message for everyone
description: |
Revokes a message so every participant of the chat sees "This message was deleted" (delete for everyone).
**Rules:**
- `Phone` and `Id` are required. `Phone` is the chat: a phone number, a user JID or a group JID.
- **Own message** (any chat): send only `Phone` and `Id`.
- **Group admin revoke:** to delete another participant's message in a group, add `Sender` with the original author's JID (`@s.whatsapp.net` or `@lid`). WhatsApp rejects it when this account is not a group admin.
- WhatsApp enforces its own time window for deleting messages; late revokes fail with **500**.
- `data.Id` echoes the revoked message ID, not the ID of the revoke protocol message.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ChatDeleteMessageRequest"
examples:
own_message:
summary: Revoke your own message
description: Deletes a message this account sent in a direct chat.
value:
Phone: "5511999999999"
Id: 3EB0C767D26A1D6B8A9F
group_admin_revoke:
summary: Group admin revokes another member's message
description: "`Sender` is the original author. WhatsApp rejects it when the session is not a group admin."
value:
Phone: "120363000000000011@g.us"
Id: 3EB0C767D26A1D6B8A9E
Sender: 123456789012345@lid
responses:
"200":
description: The revoke was sent and acknowledged by the WhatsApp server.
content:
application/json:
schema:
$ref: "#/components/schemas/ChatDeleteMessageResponse"
example:
code: 200
data:
Details: Deleted
Id: 3EB0C767D26A1D6B8A9F
Timestamp: "2026-09-15T10:30:00-03:00"
success: true
"400":
description: "Bad Request: the body is not valid JSON, `Phone` or `Id` is missing, or `Phone`/`Sender` cannot be parsed."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
could_not_decode_payload:
summary: Body is not valid JSON
value:
code: 400
error: could not decode Payload
success: false
missing_phone:
summary: Phone missing
value:
code: 400
error: missing Phone in Payload
success: false
missing_id:
summary: Id missing
value:
code: 400
error: missing Id in Payload
success: false
invalid_phone:
summary: Phone cannot be parsed
value:
code: 400
error: could not parse Phone
success: false
invalid_sender:
summary: Sender cannot be parsed
value:
code: 400
error: could not parse Sender
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: no WhatsApp session for this user, or WhatsApp rejected the revoke."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: No WhatsApp session for this user
value:
code: 500
error: no session
success: false
send_failed:
summary: Revoke rejected by the server
value:
code: 500
error: "error sending message: server returned error 403"
success: false
/chat/markread:
post:
tags:
- Chat
summary: Mark messages as read
description: |
Sends a read receipt for one or more messages of a chat, clearing the unread badge on the linked devices and, when privacy allows, showing blue ticks to the sender.
**Rules:**
- `Id` (array, at least one) and `Chat` are required.
- `Chat` must be the full chat JID as received in the webhook (`event.Info.Chat`), for example `5511999999999@s.whatsapp.net`, `123456789012345@lid` or `120363000000000011@g.us`. A bare phone number is **not** converted to a JID here; a malformed JID returns **400** `could not decode Payload`.
- `Sender` (`event.Info.Sender`) is required in groups, where it is sent as the receipt participant; it is ignored for direct chats.
- All IDs in one call must come from the same sender; call once per sender otherwise.
**Blue ticks:**
- When this account's `read_receipts` privacy setting is `none`, and always for channels (`@newsletter`), a `read-self` receipt is sent instead: the chat is marked as read on your own devices but no blue ticks are shown. The call still returns 200.
- A 200 means the receipt was handed to WhatsApp; there is no delivery confirmation.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ChatMarkReadRequest"
examples:
direct_chat:
summary: Mark two messages of a direct chat as read
description: "`Sender` is not needed for direct chats."
value:
Id:
- 3EB0C767D26A1D6B8A9F
- 3EB0A1B2C3D4E5F60718
Chat: 5511999999999@s.whatsapp.net
group_chat:
summary: Mark a group message as read
description: In groups `Sender` is required and identifies the author of the messages.
value:
Id:
- 3EB0C767D26A1D6B8A9F
Chat: 120363000000000011@g.us
Sender: 123456789012345@lid
responses:
"200":
description: The read receipt was sent to WhatsApp.
content:
application/json:
schema:
$ref: "#/components/schemas/ChatMarkReadResponse"
example:
code: 200
data:
Details: Message(s) marked as read
success: true
"400":
description: "Bad Request: the body is not valid JSON (or a JID is malformed), `Chat` is missing, or `Id` is empty."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
could_not_decode_payload:
summary: Body is not valid JSON or a JID is malformed
value:
code: 400
error: could not decode Payload
success: false
missing_chat:
summary: Chat missing
value:
code: 400
error: missing Chat in Payload
success: false
missing_id:
summary: Id empty or missing
value:
code: 400
error: missing Id in Payload
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: no WhatsApp session for this user, or the receipt could not be sent."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: No WhatsApp session for this user
value:
code: 500
error: no session
success: false
send_failed:
summary: Receipt could not be sent
value:
code: 500
error: failure marking messages as read
success: false
/chat/react:
post:
tags:
- Chat
summary: React to a message
description: |
Sends an emoji reaction to a message, or removes this account's reaction. The reaction is a new message with its own ID that targets the original message key.
**Addressing (iOS and LID):**
- iOS drops a reaction silently when its target key is not in the same namespace (phone number vs LID) as the stored original message. Android and Web are lenient.
- Send back what the webhook gave you: `Chat` with `event.Info.Chat` and, in groups, `Sender` with `event.Info.Sender`.
- When `Chat` is given it is used as both the send destination and the key chat; otherwise `Phone` is used and the library's LID migration realigns the key.
**Rules:**
- `Phone` and `Id` are required. `Body` is the emoji; an empty `Body` or `"remove"` removes the reaction.
- Prefix `Id` with `me:` when the target message was sent by this account.
- `Sender` is only used for another participant's message in a group and must be a full JID; an unparsable value is silently ignored.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ChatReactRequest"
examples:
private_received:
summary: React to a received message in a direct chat
description: The phone number is enough for direct chats.
value:
Phone: "5511999999999"
Body: "π₯"
Id: 2AFA4C0C20D815D8055A
private_own:
summary: React to your own message
description: The `me:` prefix marks the target message as sent by this account.
value:
Phone: "5511999999999"
Body: "π"
Id: me:3EB07B61F567BC21530C37
private_explicit_lid:
summary: Explicit LID addressing via Chat
description: "`Chat` with the webhook `@lid` chat guarantees rendering on iOS."
value:
Phone: "5511999999999"
Chat: 123456789012345@lid
Body: "π"
Id: 2AFA4C0C20D815D8055A
group_other_member:
summary: React to another member's group message
description: "`Sender` carries the author from the webhook (`event.Info.Sender`)."
value:
Phone: "120363000000000011@g.us"
Body: "β€οΈ"
Id: 2A565EE7389E4B787A9B
Sender: 123456789012345@lid
remove:
summary: Remove a reaction
description: An empty `Body` (or `"remove"`) clears this account's reaction.
value:
Phone: "5511999999999"
Body: remove
Id: 2AFA4C0C20D815D8055A
responses:
"200":
description: The reaction was sent and acknowledged by the WhatsApp server.
content:
application/json:
schema:
$ref: "#/components/schemas/ChatReactResponse"
example:
code: 200
data:
Details: Sent
Id: 3EB0D1E2F3A4B5C6D7E8
Timestamp: "2026-09-15T10:30:00-03:00"
success: true
"400":
description: "Bad Request: the body is not valid JSON, `Id` or `Phone` is missing, or `Phone`/`Chat` cannot be parsed."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
could_not_decode_payload:
summary: Body is not valid JSON
value:
code: 400
error: could not decode Payload
success: false
missing_fields:
summary: Id or Phone missing
value:
code: 400
error: id and phone are required
success: false
invalid_phone:
summary: Phone cannot be parsed
value:
code: 400
error: could not parse phone number
success: false
invalid_chat:
summary: Chat cannot be parsed
value:
code: 400
error: could not parse chat JID
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: no WhatsApp session for this user, or the reaction could not be sent."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: No WhatsApp session for this user
value:
code: 500
error: no session
success: false
send_failed:
summary: Reaction could not be sent
value:
code: 500
error: "error sending reaction: websocket not connected"
success: false
/chat/send/text:
post:
tags:
- Send
summary: Sends a text message
description: |
Sends a plain text message to a contact, group or channel.
**Features:**
- Optional custom `Id`; a random ID is generated otherwise
- Typing indicator (`Presence`, in ms) before sending
- Disappearing messages (`Duration`: 86400, 604800 or 7776000 seconds)
- Automatic link preview (`LinkPreview: true`) and number check (`NumberCheck: true`)
**Rules:**
- `Phone` and `Body` are required
- Replies: send `ContextInfo.stanzaID` (message being replied to) together with `ContextInfo.participant` (its author)
- Add `ContextInfo.quotedMessage` with the original content for a full reply preview on every device; without it the reply works but the preview may be missing
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/MessageText"
examples:
simple:
summary: Simple text
description: Sends a text message with a generated ID.
value:
Phone: "5511999999999"
Body: Hello! Your order has shipped.
reply_with_preview:
summary: Reply with full quote preview
description: Replies to a message and includes `quotedMessage` so every device shows the preview.
value:
Phone: "5511999999999"
Body: This is my reply to your message
ContextInfo:
stanzaID: 3EB06F9067F80BAB89FF
participant: 5511988888888@s.whatsapp.net
quotedMessage:
conversation: Original message text being replied to
typing_link_preview:
summary: Typing indicator, link preview and disappearing timer
description: Shows typing for 3 s, generates a link preview, checks the number and sets a 24 h timer.
value:
Phone: "5511999999999"
Body: Track your order at https://example.com/orders/1234
Id: 3EB0C767D26A1D6B8A9F
Presence: 3000
Duration: 86400
LinkPreview: true
NumberCheck: true
responses:
"200":
description: Response
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/SuccessEnvelope"
- type: object
properties:
data:
allOf:
- $ref: "#/components/schemas/SendMessageResult"
examples:
sent:
summary: Message acknowledged
value:
code: 200
data:
Details: Sent
Id: 90B2F8B13FAC8A9CF6B06E99C7834DC5
Timestamp: "2022-04-20T12:49:08-03:00"
success: true
"400":
description: |
The request was rejected before sending. Possible `error` values:
- `could not read request body`
- `could not decode Payload`
- `missing Phone in Payload`
- `missing Body in Payload`
- `could not parse Phone`
- `phone number is not registered on WhatsApp`
- `missing Participant in ContextInfo`
- `failed to check if user is on WhatsApp:` followed by the WhatsApp lookup error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
could_not_read_request_body:
summary: could not read request body
value:
code: 400
error: could not read request body
success: false
could_not_decode_payload:
summary: could not decode Payload
value:
code: 400
error: could not decode Payload
success: false
missing_phone_in_payload:
summary: missing Phone in Payload
value:
code: 400
error: missing Phone in Payload
success: false
missing_body_in_payload:
summary: missing Body in Payload
value:
code: 400
error: missing Body in Payload
success: false
could_not_parse_phone:
summary: could not parse Phone
value:
code: 400
error: could not parse Phone
success: false
number_check_failed:
summary: Number check failed
value:
code: 400
error: phone number is not registered on WhatsApp
success: false
reply_without_participant:
summary: Reply without participant
value:
code: 400
error: missing Participant in ContextInfo
success: false
number_check_lookup_failed:
summary: Number check lookup failed
value:
code: 400
error: "failed to check if user is on WhatsApp: websocket not connected"
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: |
The session is missing, or preparing or sending the message failed. Possible `error` values:
- `no session`
- `error sending message:` followed by the WhatsApp send error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: no session
value:
code: 500
error: no session
success: false
whatsapp_rejected_the_send:
summary: WhatsApp rejected the send
value:
code: 500
error: "error sending message: server returned error 479"
success: false
/chat/send/link:
post:
tags:
- Send
summary: Send a link message with optional preview override.
description: |
Sends a text message containing a link, with an automatic, customized or disabled preview card.
**Features:**
- Default: the preview (title, description, image) is scraped from the URL's OpenGraph tags
- `DisablePreview: true` sends the link as plain text without a card
- `Preview` with `fetch_missing` omitted/false: REPLACE mode, only the fields you set are used and nothing is scraped
- `Preview` with `fetch_missing: true`: MERGE mode, the URL is scraped first and non-empty override fields win
- Captions, mentions, replies and forwarding via `ContextInfo`
**Custom thumbnail (`Preview.image`):**
- Base64 data URL (β€ 5 MB) or http(s) URL (β€ 8 MB); PNG, WebP and GIF are re-encoded to JPEG (transparency flattened on white)
- For identical cards on mobile and Web/Desktop use a 1.91:1 landscape JPEG, ideally 1200 Γ 630 px (at least ~400 px on the long edge)
- The server uploads a high-res JPEG (downscaled to 800 px) and embeds a small inline JPEG (~200 px); Web paints the inline one first
- Square images of 200 px or less are treated as favicons (smaller card)
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/MessageLink"
examples:
auto-scrape:
summary: Auto-scraped preview (default)
description: "No `Preview` and no `DisablePreview`: the gateway scrapes the URL's OpenGraph tags. Works for public sites with valid metadata."
value:
Phone: "5511999999999"
Link: https://github.com/tulir/whatsmeow
Caption: Check out this WhatsApp library
Id: ABCDABCD1234
custom-preview-replace:
summary: Custom preview (REPLACE, no scrape)
description: "Full override: only the fields set in `Preview` are used and the URL is not fetched. Ideal for coupon links, trackers and URLs without OpenGraph."
value:
Phone: "5511999999999"
Link: https://example.com/promo
Caption: Check out this deal
Id: ABCDABCD1234
Preview:
title: "Coupon: 50% off everything"
description: Use code SAVE50 at checkout
image: data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==
matched_text: https://example.com/promo
type: image
custom-preview-merge:
summary: Custom preview (MERGE, scrape + override)
description: Auto-fetch first; then the non-empty `Preview` fields overwrite the scraped result. Useful to fix only the title/image while keeping the rest.
value:
Phone: "5511999999999"
Link: https://github.com/tulir/whatsmeow
Id: ABCDABCD1234
Preview:
title: π Custom title overrides the scraped one
fetch_missing: true
image-url-preview:
summary: Custom preview with an image URL
description: Same as REPLACE, but the card image is downloaded server-side from a public URL (β€ 8 MB) instead of base64.
value:
Phone: "5511999999999"
Link: https://example.com/article
Id: ABCDABCD1234
Preview:
title: Blog article
description: Summary of the content
image: https://picsum.photos/seed/zuckzapgo/600/315
type: image
video-preview:
summary: Video preview card
description: "Video-type preview card. WhatsApp tries to play it inline unless `do_not_play_inline: true`."
value:
Phone: "5511999999999"
Link: https://www.youtube.com/watch?v=dQw4w9WgXcQ
Caption: π¬
Id: ABCDABCD1234
Preview:
title: Never Gonna Give You Up
description: Rick Astley β official video
image: data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==
type: video
do_not_play_inline: false
disable-preview:
summary: No preview (plain text)
description: Sends the link as plain text without a card. Auto-scrape is skipped; `Preview`, if sent, is ignored.
value:
Phone: "5511999999999"
Link: https://internal.example.com/sensitive-tracker?uid=abc123
Caption: Internal link (no preview)
Id: ABCDABCD1234
DisablePreview: true
reply-with-preview:
summary: Reply with a custom preview
description: Combines a quote (`ContextInfo.stanzaID`) with a custom preview card.
value:
Phone: "5511999999999"
Link: https://example.com/promo
Id: ABCDABCD1234
Preview:
title: Reply with link
description: Custom reply card
type: placeholder
ContextInfo:
stanzaID: 3EB06F9067F80BAB89FF
participant: 5511999999999@s.whatsapp.net
responses:
"200":
description: Response
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/SuccessEnvelope"
- type: object
properties:
data:
allOf:
- $ref: "#/components/schemas/SendMessageResult"
examples:
sent:
summary: Message acknowledged
value:
code: 200
data:
Details: Sent
Id: 90B2F8B13FAC8A9CF6B06E99C7834DC5
Timestamp: "2022-04-20T12:49:08-03:00"
success: true
"400":
description: |
The request was rejected before sending. Possible `error` values:
- `could not read request body`
- `could not decode payload`
- `missing Phone in payload`
- `missing Link in payload`
- `invalid URL format`
- `invalid preview.type: must be 'image', 'video', 'none', or 'placeholder'`
- `could not parse Phone`
- `phone number is not registered on WhatsApp`
- `missing Participant in ContextInfo`
- `failed to check if user is on WhatsApp:` followed by the WhatsApp lookup error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
could_not_read_request_body:
summary: could not read request body
value:
code: 400
error: could not read request body
success: false
could_not_decode_payload:
summary: could not decode payload
value:
code: 400
error: could not decode payload
success: false
missing_phone_in_payload:
summary: missing Phone in payload
value:
code: 400
error: missing Phone in payload
success: false
missing_link_in_payload:
summary: missing Link in payload
value:
code: 400
error: missing Link in payload
success: false
invalid_url_format:
summary: invalid URL format
value:
code: 400
error: invalid URL format
success: false
unknown_preview_type:
summary: Unknown preview type
value:
code: 400
error: "invalid preview.type: must be 'image', 'video', 'none', or 'placeholder'"
success: false
could_not_parse_phone:
summary: could not parse Phone
value:
code: 400
error: could not parse Phone
success: false
number_check_failed:
summary: Number check failed
value:
code: 400
error: phone number is not registered on WhatsApp
success: false
reply_without_participant:
summary: Reply without participant
value:
code: 400
error: missing Participant in ContextInfo
success: false
number_check_lookup_failed:
summary: Number check lookup failed
value:
code: 400
error: "failed to check if user is on WhatsApp: websocket not connected"
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: |
The session is missing, or preparing or sending the message failed. Possible `error` values:
- `no session`
- `error sending link message:` followed by the WhatsApp send error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: no session
value:
code: 500
error: no session
success: false
whatsapp_rejected_the_send:
summary: WhatsApp rejected the send
value:
code: 500
error: "error sending link message: server returned error 479"
success: false
/chat/send/edit:
post:
tags:
- Send
summary: Edit an existing message (text or media caption)
description: |
Edits a message previously sent by this session, within 15 minutes of sending.
**Features:**
- Edits the **text** of a text message or the **caption** of an image, video or document
- The target type is detected automatically from the message `Id`; `Body` carries the new text or caption
- Captions can be edited on media sent through this API and on media sent from the operator's phone
**Rules:**
- `Phone`, the message ID (`Id`, or the `MessageID`/`message_id` alias, which takes precedence) and `Body` are required
- When the ID is unknown to this instance the edit is sent as a text edit
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/MessageEdit"
examples:
text_edit:
summary: Edit the text of a sent message
value:
Phone: "5511999999999"
Id: 3EB0C767D26A1D6B8A9F
Body: Meeting moved to 3 PM
description: Replaces the text of a message sent by this session.
caption_edit_message_id:
summary: Edit an image caption using the MessageID alias
description: "`MessageID`/`message_id` takes precedence over `Id`. The target type (text, image, video, document) is detected from the remembered message."
value:
Phone: 120363000000000001@g.us
MessageID: 3EB0C767D26A1D6B8A9F
Body: Updated price list (valid until Friday)
snake_case_link_preview:
summary: snake_case keys with link preview on a text edit
value:
phone: "5511988888888"
message_id: 3EB0C767D26A1D6B8A9F
body: "New link: https://example.com/checkout"
link_preview: true
description: Edits a text message with snake_case keys and generates a link preview for the new URL.
responses:
"200":
description: Edit sent
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/SuccessEnvelope"
- type: object
properties:
data:
allOf:
- $ref: "#/components/schemas/SendMessageResult"
examples:
sent:
summary: Message acknowledged
value:
code: 200
data:
Details: Sent
Id: 3EB0C767D26A1D6B8A9F
Timestamp: "2026-09-15T10:30:00-03:00"
success: true
"400":
description: |
The request was rejected before sending. Possible `error` values:
- `could not read request body`
- `could not decode Payload`
- `missing Phone in Payload`
- `missing Body in Payload`
- `missing Id or MessageID in Payload`
- `could not parse Phone`
- `phone number is not registered on WhatsApp`
- `missing Participant in ContextInfo`
- `failed to check if user is on WhatsApp:` followed by the WhatsApp lookup error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
could_not_read_request_body:
summary: could not read request body
value:
code: 400
error: could not read request body
success: false
could_not_decode_payload:
summary: could not decode Payload
value:
code: 400
error: could not decode Payload
success: false
missing_phone_in_payload:
summary: missing Phone in Payload
value:
code: 400
error: missing Phone in Payload
success: false
missing_body_in_payload:
summary: missing Body in Payload
value:
code: 400
error: missing Body in Payload
success: false
missing_id_or_messageid_in_payload:
summary: missing Id or MessageID in Payload
value:
code: 400
error: missing Id or MessageID in Payload
success: false
could_not_parse_phone:
summary: could not parse Phone
value:
code: 400
error: could not parse Phone
success: false
number_check_failed:
summary: Number check failed
value:
code: 400
error: phone number is not registered on WhatsApp
success: false
reply_without_participant:
summary: Reply without participant
value:
code: 400
error: missing Participant in ContextInfo
success: false
number_check_lookup_failed:
summary: Number check lookup failed
value:
code: 400
error: "failed to check if user is on WhatsApp: websocket not connected"
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: |
The session is missing, or preparing or sending the message failed. Possible `error` values:
- `no session`
- `error sending edit message:` followed by the WhatsApp send error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: no session
value:
code: 500
error: no session
success: false
whatsapp_rejected_the_send:
summary: WhatsApp rejected the send
value:
code: 500
error: "error sending edit message: server returned error 479"
success: false
/chat/send/image:
post:
tags:
- Send
summary: Sends an image/picture message
description: |
Sends an image to a contact, group or channel.
**Media input (`Image`):** a base64 data URL (`data:image/png;base64,...`) or an `http://`/`https://` URL downloaded server-side (30 s timeout, must answer 200). For data URLs the type comes from the data URL header; for URLs it is detected from the content. The detected type must be `image/jpeg`, `image/png`, `image/gif` or `image/webp` (400 `invalid image format. Supported: JPEG, PNG, GIF, WebP`). The bytes must be a decodable image because a 72 px thumbnail is generated (500 otherwise). The handler enforces no size limit; WhatsApp's media limits apply.
**Accepted keys** (either spelling): `phone`/`Phone`, `image`/`Image`, `caption`/`Caption`, `id`/`Id`, `mime_type`/`MimeType`, `presence`/`Presence`, `view_once`/`ViewOnce`, `duration`/`Duration`, `number_check`/`NumberCheck`, `context_info`/`ContextInfo`, plus `mention_info`, `forward_info` and `EchoApi`/`echoApi`/`echo_api`.
**Rules:**
- `Phone` and `Image` are required.
- `MimeType` only overrides the `mimetype` written in the message; it does not bypass the format check.
- `presence` (ms) shows a typing indicator and **delays the HTTP response** by that time.
- `duration` (seconds) is snapped to the nearest of 86400, 604800 or 7776000.
- `number_check: true` verifies the number first (400 `phone number is not registered on WhatsApp`).
- Replies: `ContextInfo.stanzaID` and `ContextInfo.participant` must be sent together (400 `missing Participant in ContextInfo`); add `quotedMessage` for a full preview. With the PascalCase `ContextInfo` key the object is only applied when it has `stanzaID` β to mention or forward without replying use `mention_info` (`mentioned_jid`, `mention_all`) or `forward_info.is_forwarded`.
- Invalid media input returns 400 (`invalid media input: must be either base64 data URL or HTTP(S) URL`, `could not decode base64 data: ...`, `HTTP error 404 when downloading from URL`).
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/MessageImage"
examples:
url_with_caption:
summary: Image from an HTTPS URL with caption
value:
Phone: "5511999999999"
Image: https://example.com/media/product.jpg
Caption: Your order is ready for pickup
Id: 3EB0C767D26A1D6B8A9F
description: Downloads the image server-side and sends it with a caption and a custom message ID.
base64_png:
summary: Image as a short base64 data URL
value:
Phone: "5511999999999"
Image: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==
Caption: Test pixel
NumberCheck: true
description: Sends a tiny PNG embedded as a data URL after checking that the number is on WhatsApp.
snake_case_view_once:
summary: snake_case keys, view once, typing delay
value:
phone: "5511988888888"
image: https://example.com/media/receipt.png
view_once: true
presence: 2000
number_check: true
EchoApi: true
description: Uses snake_case keys, sends as view once and shows a 2 s typing indicator first.
group_reply_with_mention:
summary: Group reply quoting a message and mentioning a member
value:
Phone: 120363000000000001@g.us
Image: https://example.com/media/chart.png
Caption: Here is the chart @5511988888888
ContextInfo:
stanzaID: 3EB0A1B2C3D4E5F60718
participant: 5511988888888@s.whatsapp.net
quotedMessage:
conversation: Can you share the chart?
mention_info:
mentioned_jid:
- 5511988888888@s.whatsapp.net
description: Replies to a group message with a full quote preview and mentions a member.
responses:
"200":
description: Response
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/SuccessEnvelope"
- type: object
properties:
data:
allOf:
- $ref: "#/components/schemas/SendMessageResult"
examples:
sent:
summary: Message acknowledged
value:
code: 200
data:
Details: Sent
Id: 90B2F8B13FAC8A9CF6B06E99C7834DC5
Timestamp: "2022-04-20T12:49:08-03:00"
success: true
"400":
description: |
The request was rejected before sending. Possible `error` values:
- `could not read request body`
- `could not decode Payload`
- `missing Phone in Payload`
- `missing Image in Payload`
- `invalid image format. Supported: JPEG, PNG, GIF, WebP`
- `invalid media input: must be either base64 data URL or HTTP(S) URL`
- `could not decode base64 data:` followed by the base64 decoding error
- `HTTP error 404 when downloading from URL`
- `could not parse Phone`
- `phone number is not registered on WhatsApp`
- `missing Participant in ContextInfo`
- `failed to check if user is on WhatsApp:` followed by the WhatsApp lookup error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
could_not_read_request_body:
summary: could not read request body
value:
code: 400
error: could not read request body
success: false
could_not_decode_payload:
summary: could not decode Payload
value:
code: 400
error: could not decode Payload
success: false
missing_phone_in_payload:
summary: missing Phone in Payload
value:
code: 400
error: missing Phone in Payload
success: false
missing_image_in_payload:
summary: missing Image in Payload
value:
code: 400
error: missing Image in Payload
success: false
unsupported_image_type:
summary: Unsupported image type
value:
code: 400
error: "invalid image format. Supported: JPEG, PNG, GIF, WebP"
success: false
media_is_neither_data_url_nor_http_s_url:
summary: Media is neither data URL nor HTTP(S) URL
value:
code: 400
error: "invalid media input: must be either base64 data URL or HTTP(S) URL"
success: false
invalid_base64_data:
summary: Invalid base64 data
value:
code: 400
error: "could not decode base64 data: illegal base64 data at input byte 12"
success: false
media_url_returned_404:
summary: Media URL returned 404
value:
code: 400
error: HTTP error 404 when downloading from URL
success: false
could_not_parse_phone:
summary: could not parse Phone
value:
code: 400
error: could not parse Phone
success: false
number_check_failed:
summary: Number check failed
value:
code: 400
error: phone number is not registered on WhatsApp
success: false
reply_without_participant:
summary: Reply without participant
value:
code: 400
error: missing Participant in ContextInfo
success: false
number_check_lookup_failed:
summary: Number check lookup failed
value:
code: 400
error: "failed to check if user is on WhatsApp: websocket not connected"
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: |
The session is missing, or preparing or sending the message failed. Possible `error` values:
- `no session`
- `failed to upload file:` followed by the WhatsApp media upload error
- `could not decode image for thumbnail preparation:` followed by the image decoding error
- `Could not create temp file for thumbnail:` followed by the file system error
- `Failed to encode jpeg:` followed by the JPEG encoding error
- `Failed to read` followed by the temporary thumbnail path and the read error
- `Error sending message:` followed by the WhatsApp send error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: no session
value:
code: 500
error: no session
success: false
upload_failed:
summary: Upload failed
value:
code: 500
error: "failed to upload file: failed to refresh media connections: websocket not connected"
success: false
image_cannot_be_decoded:
summary: Image cannot be decoded
value:
code: 500
error: "could not decode image for thumbnail preparation: image: unknown format"
success: false
thumbnail_temp_file_failed:
summary: Thumbnail temp file failed
value:
code: 500
error: "Could not create temp file for thumbnail: open /tmp/resized-2718281828.jpg: no space left on device"
success: false
thumbnail_encoding_failed:
summary: Thumbnail encoding failed
value:
code: 500
error: "Failed to encode jpeg: write /tmp/resized-2718281828.jpg: no space left on device"
success: false
thumbnail_read_failed:
summary: Thumbnail read failed
value:
code: 500
error: "Failed to read /tmp/resized-2718281828.jpg: unexpected EOF"
success: false
whatsapp_rejected_the_send:
summary: WhatsApp rejected the send
value:
code: 500
error: "Error sending message: server returned error 479"
success: false
/chat/send/audio:
post:
tags:
- Send
summary: Sends an audio message
description: |
Sends an audio file or a voice note (PTT) to a contact, group or channel.
**Media input (`Audio`):** a base64 data URL (`data:audio/ogg;base64,...`) or an `http://`/`https://` URL downloaded server-side (30 s timeout). Any audio type is accepted; OGG/Opus gives the best voice-note playback.
**Accepted keys** (either spelling): `phone`/`Phone`, `audio`/`Audio`, `caption`/`Caption`, `id`/`Id`, `ptt`/`PTT`, `presence`/`Presence`, `view_once`/`ViewOnce`, `duration`/`Duration`, `number_check`/`NumberCheck`, `context_info`/`ContextInfo`, plus `mention_info`, `forward_info` and `EchoApi`/`echoApi`/`echo_api`.
**Rules:**
- `Phone` and `Audio` are required.
- `PTT` defaults to **true** (voice note). For PTT a missing, unsupported or `application/octet-stream` type is sent as `audio/ogg; codecs=opus`; Opus content in OGG is always labelled `audio/ogg; codecs=opus`. With `PTT: false` unknown types fall back to `audio/mpeg`.
- The duration in seconds (1β3600) is computed from the file and a waveform is always generated.
- `Caption` is accepted but audio messages carry no caption, so it is not delivered.
- `presence` (ms) shows a **recording audio** indicator and delays the HTTP response by that time.
- `duration` (seconds) is snapped to 86400, 604800 or 7776000; `number_check: true` verifies the number first.
- Replies need `ContextInfo.stanzaID` + `ContextInfo.participant` together.
The 200 response adds `Source` (`base64`|`url`), `PTT`, `Type` (`voice_note`|`audio_file`), `Duration` (seconds), `HasWaveform` and the final `MimeType`.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/MessageAudio"
examples:
voice_note_url:
summary: Voice note from an HTTPS URL with recording indicator
value:
Phone: "5511999999999"
Audio: https://example.com/media/voice-note.ogg
PTT: true
Presence: 2000
description: Sends an OGG/Opus file as a voice note (PTT) after a 2 s recording indicator.
voice_note_base64:
summary: Voice note as a short base64 data URL
value:
Phone: "5511999999999"
Audio: data:audio/ogg;base64,T2dnUwACAAAAAAAAAABK
Id: 3EB0C767D26A1D6B8A9F
description: Sends a short voice note embedded as a data URL with a custom message ID.
audio_file_snake_case:
summary: MP3 sent as an audio file (snake_case keys)
value:
phone: "5511988888888"
audio: https://example.com/media/podcast-intro.mp3
ptt: false
number_check: true
echo_api: true
description: "Sends an MP3 as a regular audio file (`ptt: false`) and forces an API echo event."
group_reply:
summary: Voice note replying to a group message
value:
Phone: 120363000000000001@g.us
Audio: https://example.com/media/reply.ogg
ContextInfo:
stanzaID: 3EB0A1B2C3D4E5F60718
participant: 5511988888888@s.whatsapp.net
quotedMessage:
conversation: Can you explain by audio?
description: Replies to a group message with a voice note quoting the original text.
responses:
"200":
description: Audio sent
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/SuccessEnvelope"
- type: object
properties:
data:
description: Result of a successful send.
allOf:
- $ref: "#/components/schemas/SendMessageResult"
- type: object
properties:
Duration:
type: integer
description: Detected duration in seconds.
example: 7
HasWaveform:
type: boolean
description: True when a waveform was generated for the voice note.
example: true
MimeType:
type: string
description: MIME type written in the message.
example: audio/ogg; codecs=opus
PTT:
type: boolean
description: True when sent as a voice note.
example: true
Source:
type: string
description: Media input kind (`url` or `base64`).
example: url
Type:
type: string
description: "`voice_note` or `audio_file`."
example: voice_note
examples:
sent:
summary: Message acknowledged
value:
code: 200
data:
Details: Sent
Duration: 7
HasWaveform: true
Id: 3EB0C767D26A1D6B8A9F
MimeType: audio/ogg; codecs=opus
PTT: true
Source: url
Timestamp: "2026-09-15T10:30:00-03:00"
Type: voice_note
success: true
"400":
description: |
The request was rejected before sending. Possible `error` values:
- `could not read request body`
- `could not decode Payload`
- `missing Phone in Payload`
- `missing Audio in Payload`
- `invalid media input: must be either base64 data URL or HTTP(S) URL`
- `could not decode base64 data:` followed by the base64 decoding error
- `HTTP error 404 when downloading from URL`
- `could not parse Phone`
- `phone number is not registered on WhatsApp`
- `missing Participant in ContextInfo`
- `failed to check if user is on WhatsApp:` followed by the WhatsApp lookup error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
could_not_read_request_body:
summary: could not read request body
value:
code: 400
error: could not read request body
success: false
could_not_decode_payload:
summary: could not decode Payload
value:
code: 400
error: could not decode Payload
success: false
missing_phone_in_payload:
summary: missing Phone in Payload
value:
code: 400
error: missing Phone in Payload
success: false
missing_audio_in_payload:
summary: missing Audio in Payload
value:
code: 400
error: missing Audio in Payload
success: false
media_is_neither_data_url_nor_http_s_url:
summary: Media is neither data URL nor HTTP(S) URL
value:
code: 400
error: "invalid media input: must be either base64 data URL or HTTP(S) URL"
success: false
invalid_base64_data:
summary: Invalid base64 data
value:
code: 400
error: "could not decode base64 data: illegal base64 data at input byte 12"
success: false
media_url_returned_404:
summary: Media URL returned 404
value:
code: 400
error: HTTP error 404 when downloading from URL
success: false
could_not_parse_phone:
summary: could not parse Phone
value:
code: 400
error: could not parse Phone
success: false
number_check_failed:
summary: Number check failed
value:
code: 400
error: phone number is not registered on WhatsApp
success: false
reply_without_participant:
summary: Reply without participant
value:
code: 400
error: missing Participant in ContextInfo
success: false
number_check_lookup_failed:
summary: Number check lookup failed
value:
code: 400
error: "failed to check if user is on WhatsApp: websocket not connected"
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: |
The session is missing, or preparing or sending the message failed. Possible `error` values:
- `no session`
- `failed to upload audio:` followed by the WhatsApp media upload error
- `Error sending message:` followed by the WhatsApp send error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: no session
value:
code: 500
error: no session
success: false
upload_failed:
summary: Upload failed
value:
code: 500
error: "failed to upload audio: failed to refresh media connections: websocket not connected"
success: false
whatsapp_rejected_the_send:
summary: WhatsApp rejected the send
value:
code: 500
error: "Error sending message: server returned error 479"
success: false
/chat/send/document:
post:
tags:
- Send
summary: Sends a document message
description: |
Sends a document (any file type) to a contact, group or channel.
**Media input (`Document`):** a base64 data URL (`data:application/pdf;base64,...`) or an `http://`/`https://` URL downloaded server-side (30 s timeout). No type restriction; the type comes from the data URL header or is detected from the downloaded content. PDFs get page count and a first-page thumbnail when they can be rendered.
**Accepted keys:** `Phone`, `Document`, `FileName`, `Id`, `MimeType` and `Caption` (matched case-insensitively, so `phone`/`document`/`filename` also work β but not `file_name`), `presence`/`Presence`, `duration`/`Duration`, `number_check`/`NumberCheck`, `ContextInfo` (case-insensitive; `context_info` is not read here), plus `mention_info`, `forward_info` and `EchoApi`/`echoApi`/`echo_api`.
**Rules:**
- `Phone`, `Document` and `FileName` are required (`FileName` is what the recipient sees, include the extension).
- `MimeType` overrides the detected type in the message.
- `presence` (ms) shows a typing indicator and delays the HTTP response; `duration` is snapped to 86400, 604800 or 7776000; `number_check: true` verifies the number first.
- Replies need `ContextInfo.stanzaID` + `ContextInfo.participant` together; `ContextInfo` is only applied when it has `stanzaID` (use `mention_info`/`forward_info` for mentions or forwarding without a reply).
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/MessageDocument"
examples:
pdf_url:
summary: PDF from an HTTPS URL
value:
Phone: "5511999999999"
Document: https://example.com/files/invoice-2026-09.pdf
FileName: invoice-2026-09.pdf
Caption: Invoice for September
description: Downloads a PDF server-side and sends it with file name and caption.
pdf_base64:
summary: Small PDF as base64 data URL with MIME override
value:
Phone: "5511999999999"
Document: data:application/pdf;base64,JVBERi0xLjQKJeLjz9MKMSAwIG9iajw8Pj5lbmRvYmoKdHJhaWxlcjw8Pj4KJSVFT0Y=
FileName: contract.pdf
MimeType: application/pdf
Id: 3EB0C767D26A1D6B8A9F
description: Sends a small PDF embedded as a data URL and overrides the MIME type.
group_with_mention:
summary: Spreadsheet to a group mentioning a member
value:
phone: 120363000000000001@g.us
document: https://example.com/files/report.xlsx
fileName: report.xlsx
caption: Monthly report @5511988888888
presence: 1500
mention_info:
mentioned_jid:
- 5511988888888@s.whatsapp.net
description: Sends a spreadsheet to a group, mentions a member and shows a typing indicator.
reply:
summary: Document replying to a message
value:
Phone: "5511988888888"
Document: https://example.com/files/terms.pdf
FileName: terms.pdf
ContextInfo:
stanzaID: 3EB0A1B2C3D4E5F60718
participant: 5511988888888@s.whatsapp.net
quotedMessage:
conversation: Please send the terms
description: Sends a document that quotes the message asking for it.
responses:
"200":
description: Response
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/SuccessEnvelope"
- type: object
properties:
data:
allOf:
- $ref: "#/components/schemas/SendMessageResult"
examples:
sent:
summary: Message acknowledged
value:
code: 200
data:
Details: Sent
Id: 90B2F8B13FAC8A9CF6B06E99C7834DC5
Timestamp: "2022-04-20T12:49:08-03:00"
success: true
"400":
description: |
The request was rejected before sending. Possible `error` values:
- `could not read request body`
- `could not decode Payload`
- `missing Phone in Payload`
- `missing Document in Payload`
- `missing FileName in Payload`
- `invalid media input: must be either base64 data URL or HTTP(S) URL`
- `could not decode base64 data:` followed by the base64 decoding error
- `HTTP error 404 when downloading from URL`
- `could not parse Phone`
- `phone number is not registered on WhatsApp`
- `missing Participant in ContextInfo`
- `failed to check if user is on WhatsApp:` followed by the WhatsApp lookup error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
could_not_read_request_body:
summary: could not read request body
value:
code: 400
error: could not read request body
success: false
could_not_decode_payload:
summary: could not decode Payload
value:
code: 400
error: could not decode Payload
success: false
missing_phone_in_payload:
summary: missing Phone in Payload
value:
code: 400
error: missing Phone in Payload
success: false
missing_document_in_payload:
summary: missing Document in Payload
value:
code: 400
error: missing Document in Payload
success: false
missing_filename_in_payload:
summary: missing FileName in Payload
value:
code: 400
error: missing FileName in Payload
success: false
media_is_neither_data_url_nor_http_s_url:
summary: Media is neither data URL nor HTTP(S) URL
value:
code: 400
error: "invalid media input: must be either base64 data URL or HTTP(S) URL"
success: false
invalid_base64_data:
summary: Invalid base64 data
value:
code: 400
error: "could not decode base64 data: illegal base64 data at input byte 12"
success: false
media_url_returned_404:
summary: Media URL returned 404
value:
code: 400
error: HTTP error 404 when downloading from URL
success: false
could_not_parse_phone:
summary: could not parse Phone
value:
code: 400
error: could not parse Phone
success: false
number_check_failed:
summary: Number check failed
value:
code: 400
error: phone number is not registered on WhatsApp
success: false
reply_without_participant:
summary: Reply without participant
value:
code: 400
error: missing Participant in ContextInfo
success: false
number_check_lookup_failed:
summary: Number check lookup failed
value:
code: 400
error: "failed to check if user is on WhatsApp: websocket not connected"
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: |
The session is missing, or preparing or sending the message failed. Possible `error` values:
- `no session`
- `failed to upload file:` followed by the WhatsApp media upload error
- `Error sending message:` followed by the WhatsApp send error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: no session
value:
code: 500
error: no session
success: false
upload_failed:
summary: Upload failed
value:
code: 500
error: "failed to upload file: failed to refresh media connections: websocket not connected"
success: false
whatsapp_rejected_the_send:
summary: WhatsApp rejected the send
value:
code: 500
error: "Error sending message: server returned error 479"
success: false
/chat/send/video:
post:
tags:
- Send
summary: Sends a video message
description: |
Sends a video to a contact, group or channel.
**Media input (`Video`):** a base64 data URL (`data:video/mp4;base64,...`) or an `http://`/`https://` URL downloaded server-side (30 s timeout). The detected type must be `video/mp4`, `video/3gpp`, `video/quicktime` or `video/x-ms-asf` (400 `invalid video format. Supported: MP4, 3GP, MOV, ASF`). For reliable playback use H.264 video with AAC audio.
**Accepted keys** (either spelling): `phone`/`Phone`, `video`/`Video`, `caption`/`Caption`, `id`/`Id`, `jpeg_thumbnail`/`JPEGThumbnail`, `mime_type`/`MimeType`, `gif`/`GIF`, `presence`/`Presence`, `view_once`/`ViewOnce`, `duration`/`Duration`, `number_check`/`NumberCheck`, `context_info`/`ContextInfo`, plus `mention_info`, `forward_info` and `EchoApi`/`echoApi`/`echo_api`.
**Rules:**
- `Phone` and `Video` are required.
- `JPEGThumbnail` is a **plain base64** JPEG (no `data:` prefix). When omitted a thumbnail is generated from the video, falling back to a generic image.
- The length in seconds is read from MP4 files only.
- `GIF: true` sends it as a looping GIF (videos longer than 6 s may not display as GIF).
- `MimeType` only overrides the `mimetype` in the message; it does not bypass the format check.
- `presence` (ms) shows a typing indicator and delays the HTTP response; `duration` is snapped to 86400, 604800 or 7776000; `number_check: true` verifies the number first.
- Replies need `ContextInfo.stanzaID` + `ContextInfo.participant` together; with the PascalCase `ContextInfo` key the object is only applied when it has `stanzaID` (use `mention_info`/`forward_info` otherwise).
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/MessageVideo"
examples:
url_with_caption:
summary: MP4 from an HTTPS URL with caption
value:
Phone: "5511999999999"
Video: https://example.com/media/tutorial.mp4
Caption: Step-by-step setup
description: Downloads an MP4 server-side and sends it with a caption.
base64_with_thumbnail:
summary: Short base64 data URL with explicit thumbnail
value:
Phone: "5511999999999"
Video: data:video/mp4;base64,AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1wNDE=
JPEGThumbnail: /9j/4AAQSkZJRgABAQEASABIAAD/wAARCAABAAEBAREAAhEBAxEB/8QAFAABAAAAAAAAAAAAAAAAAAAACP/aAAgBAQAAPwAA/9k=
MimeType: video/mp4
description: Sends a short MP4 embedded as a data URL with an explicit JPEG thumbnail.
gif_snake_case:
summary: Looping GIF-style video (snake_case keys)
value:
phone: "5511988888888"
video: https://example.com/media/celebration.mp4
gif: true
view_once: false
presence: 1500
number_check: true
description: Sends a looping GIF-style video using snake_case keys.
group_reply:
summary: Video replying to a group message
value:
Phone: 120363000000000001@g.us
Video: https://example.com/media/answer.mp4
Caption: As requested
ContextInfo:
stanzaID: 3EB0A1B2C3D4E5F60718
participant: 5511988888888@s.whatsapp.net
quotedMessage:
conversation: Do you have a video of it?
description: Replies to a group message with a video.
responses:
"200":
description: Response
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/SuccessEnvelope"
- type: object
properties:
data:
allOf:
- $ref: "#/components/schemas/SendMessageResult"
examples:
sent:
summary: Message acknowledged
value:
code: 200
data:
Details: Sent
Id: 90B2F8B13FAC8A9CF6B06E99C7834DC5
Timestamp: "2022-04-20T12:49:08-03:00"
success: true
"400":
description: |
The request was rejected before sending. Possible `error` values:
- `could not read request body`
- `could not decode Payload`
- `missing Phone in Payload`
- `missing Video in Payload`
- `invalid video format. Supported: MP4, 3GP, MOV, ASF`
- `invalid media input: must be either base64 data URL or HTTP(S) URL`
- `could not decode base64 data:` followed by the base64 decoding error
- `HTTP error 404 when downloading from URL`
- `could not parse Phone`
- `phone number is not registered on WhatsApp`
- `missing Participant in ContextInfo`
- `failed to check if user is on WhatsApp:` followed by the WhatsApp lookup error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
could_not_read_request_body:
summary: could not read request body
value:
code: 400
error: could not read request body
success: false
could_not_decode_payload:
summary: could not decode Payload
value:
code: 400
error: could not decode Payload
success: false
missing_phone_in_payload:
summary: missing Phone in Payload
value:
code: 400
error: missing Phone in Payload
success: false
missing_video_in_payload:
summary: missing Video in Payload
value:
code: 400
error: missing Video in Payload
success: false
unsupported_video_type:
summary: Unsupported video type
value:
code: 400
error: "invalid video format. Supported: MP4, 3GP, MOV, ASF"
success: false
media_is_neither_data_url_nor_http_s_url:
summary: Media is neither data URL nor HTTP(S) URL
value:
code: 400
error: "invalid media input: must be either base64 data URL or HTTP(S) URL"
success: false
invalid_base64_data:
summary: Invalid base64 data
value:
code: 400
error: "could not decode base64 data: illegal base64 data at input byte 12"
success: false
media_url_returned_404:
summary: Media URL returned 404
value:
code: 400
error: HTTP error 404 when downloading from URL
success: false
could_not_parse_phone:
summary: could not parse Phone
value:
code: 400
error: could not parse Phone
success: false
number_check_failed:
summary: Number check failed
value:
code: 400
error: phone number is not registered on WhatsApp
success: false
reply_without_participant:
summary: Reply without participant
value:
code: 400
error: missing Participant in ContextInfo
success: false
number_check_lookup_failed:
summary: Number check lookup failed
value:
code: 400
error: "failed to check if user is on WhatsApp: websocket not connected"
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: |
The session is missing, or preparing or sending the message failed. Possible `error` values:
- `no session`
- `failed to upload file:` followed by the WhatsApp media upload error
- `error sending message:` followed by the WhatsApp send error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: no session
value:
code: 500
error: no session
success: false
upload_failed:
summary: Upload failed
value:
code: 500
error: "failed to upload file: failed to refresh media connections: websocket not connected"
success: false
whatsapp_rejected_the_send:
summary: WhatsApp rejected the send
value:
code: 500
error: "error sending message: server returned error 479"
success: false
/chat/send/ptv:
post:
tags:
- Send
summary: Send a round video note (PTV)
description: |
Sends a **PTV** message: the round, auto-playing video note, to a contact, group or channel.
**Rules:**
- Body: only `Phone` and `Video` (keys matched case-insensitively), plus the optional `EchoApi`/`echoApi`/`echo_api` flag; both are required (`400 missing phone or video`)
- `Video` is a base64 data URL or an `http://`/`https://` URL downloaded server-side (30 s timeout); errors return `400 error processing video: `
- The type is not validated: send a short, square MP4 (H.264/AAC) so the round preview looks right; a JPEG thumbnail is generated from the video
**Not supported:**
- Caption, custom `Id` (always generated), `presence`, `duration`, `number_check`, replies (`ContextInfo`), mentions and forwarding
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/MessagePTV"
examples:
url:
summary: Video note from an HTTPS URL
value:
Phone: "5511999999999"
Video: https://example.com/media/hello-note.mp4
description: Downloads a short square MP4 and sends it as a round video note.
base64:
summary: Video note as a short base64 data URL
value:
phone: "5511999999999"
video: data:video/mp4;base64,AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1wNDE=
EchoApi: true
description: Sends a video note embedded as a data URL and forces an API echo event.
responses:
"200":
description: Response
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/SuccessEnvelope"
- type: object
properties:
data:
allOf:
- $ref: "#/components/schemas/SendMessageResult"
examples:
sent:
summary: Message acknowledged
value:
code: 200
data:
Details: Sent
Id: 90B2F8B13FAC8A9CF6B06E99C7834DC5
Timestamp: "2022-04-20T12:49:08-03:00"
success: true
"400":
description: |
The request was rejected before sending. Possible `error` values:
- `could not read request body`
- `could not decode Payload`
- `missing phone or video`
- `could not parse Phone`
- `error processing video:` followed by the media download or decoding error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
could_not_read_request_body:
summary: could not read request body
value:
code: 400
error: could not read request body
success: false
could_not_decode_payload:
summary: could not decode Payload
value:
code: 400
error: could not decode Payload
success: false
missing_phone_or_video:
summary: missing phone or video
value:
code: 400
error: missing phone or video
success: false
could_not_parse_phone:
summary: could not parse Phone
value:
code: 400
error: could not parse Phone
success: false
video_cannot_be_processed:
summary: Video cannot be processed
value:
code: 400
error: "error processing video: HTTP error 404 when downloading from URL"
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: |
The session is missing, or preparing or sending the message failed. Possible `error` values:
- `no session`
- `error uploading video:` followed by the WhatsApp media upload error
- `Error sending ptv:` followed by the WhatsApp send error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: no session
value:
code: 500
error: no session
success: false
upload_failed:
summary: Upload failed
value:
code: 500
error: "error uploading video: failed to refresh media connections: websocket not connected"
success: false
whatsapp_rejected_the_send:
summary: WhatsApp rejected the send
value:
code: 500
error: "Error sending ptv: server returned error 479"
success: false
/chat/send/sticker:
post:
tags:
- Send
summary: Sends a sticker message
description: |
Sends a sticker to a contact, group or channel.
**Media input (`Sticker`):** a base64 data URL (`data:image/webp;base64,...`) or an `http://`/`https://` URL downloaded server-side (30 s timeout). The detected type must be `image/jpeg`, `image/png`, `image/gif` or `image/webp` (400 `invalid sticker format. Supported: JPEG, PNG, GIF, WebP`). The file is sent **as is** (no conversion or resizing): WhatsApp clients expect a 512Γ512 WebP, so other formats may not render as a sticker.
**Accepted keys:** `Phone`, `Sticker`, `Id`, `MimeType`, `PngThumbnail` (case-insensitive), `presence`/`Presence`, `number_check`/`NumberCheck`, `ContextInfo` (case-insensitive), plus `mention_info`, `forward_info` and `EchoApi`/`echoApi`/`echo_api`.
**Rules:**
- `Phone` and `Sticker` are required.
- `PngThumbnail` is a **plain base64** PNG (no `data:` prefix).
- No `Duration`/`ViewOnce` support on this endpoint.
- `presence` (ms) shows a typing indicator and delays the HTTP response; `number_check: true` verifies the number first.
- Replies need `ContextInfo.stanzaID` + `ContextInfo.participant` together.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/MessageSticker"
examples:
webp_url:
summary: WebP sticker from an HTTPS URL
value:
Phone: "5511999999999"
Sticker: https://example.com/stickers/thumbs-up.webp
description: Downloads a WebP sticker server-side and sends it.
webp_base64:
summary: WebP sticker as a short base64 data URL
value:
Phone: "5511999999999"
Sticker: data:image/webp;base64,UklGRh4AAABXRUJQVlA4TBEAAAAvAAAAAAfQ//73v/+BiOh/AAA=
MimeType: image/webp
Id: 3EB0C767D26A1D6B8A9F
description: Sends a WebP sticker embedded as a data URL with a custom message ID.
group_reply:
summary: Sticker replying in a group
value:
phone: 120363000000000001@g.us
sticker: https://example.com/stickers/party.webp
number_check: false
ContextInfo:
stanzaID: 3EB0A1B2C3D4E5F60718
participant: 5511988888888@s.whatsapp.net
quotedMessage:
conversation: We closed the deal!
description: Replies to a group message with a sticker.
responses:
"200":
description: Response
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/SuccessEnvelope"
- type: object
properties:
data:
allOf:
- $ref: "#/components/schemas/SendMessageResult"
examples:
sent:
summary: Message acknowledged
value:
code: 200
data:
Details: Sent
Id: 90B2F8B13FAC8A9CF6B06E99C7834DC5
Timestamp: "2022-04-20T12:49:08-03:00"
success: true
"400":
description: |
The request was rejected before sending. Possible `error` values:
- `could not read request body`
- `could not decode Payload`
- `missing Phone in Payload`
- `missing Sticker in Payload`
- `invalid sticker format. Supported: JPEG, PNG, GIF, WebP`
- `invalid media input: must be either base64 data URL or HTTP(S) URL`
- `could not decode base64 data:` followed by the base64 decoding error
- `HTTP error 404 when downloading from URL`
- `could not parse Phone`
- `phone number is not registered on WhatsApp`
- `missing Participant in ContextInfo`
- `failed to check if user is on WhatsApp:` followed by the WhatsApp lookup error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
could_not_read_request_body:
summary: could not read request body
value:
code: 400
error: could not read request body
success: false
could_not_decode_payload:
summary: could not decode Payload
value:
code: 400
error: could not decode Payload
success: false
missing_phone_in_payload:
summary: missing Phone in Payload
value:
code: 400
error: missing Phone in Payload
success: false
missing_sticker_in_payload:
summary: missing Sticker in Payload
value:
code: 400
error: missing Sticker in Payload
success: false
unsupported_sticker_type:
summary: Unsupported sticker type
value:
code: 400
error: "invalid sticker format. Supported: JPEG, PNG, GIF, WebP"
success: false
media_is_neither_data_url_nor_http_s_url:
summary: Media is neither data URL nor HTTP(S) URL
value:
code: 400
error: "invalid media input: must be either base64 data URL or HTTP(S) URL"
success: false
invalid_base64_data:
summary: Invalid base64 data
value:
code: 400
error: "could not decode base64 data: illegal base64 data at input byte 12"
success: false
media_url_returned_404:
summary: Media URL returned 404
value:
code: 400
error: HTTP error 404 when downloading from URL
success: false
could_not_parse_phone:
summary: could not parse Phone
value:
code: 400
error: could not parse Phone
success: false
number_check_failed:
summary: Number check failed
value:
code: 400
error: phone number is not registered on WhatsApp
success: false
reply_without_participant:
summary: Reply without participant
value:
code: 400
error: missing Participant in ContextInfo
success: false
number_check_lookup_failed:
summary: Number check lookup failed
value:
code: 400
error: "failed to check if user is on WhatsApp: websocket not connected"
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: |
The session is missing, or preparing or sending the message failed. Possible `error` values:
- `no session`
- `Failed to upload file:` followed by the WhatsApp media upload error
- `Error sending message:` followed by the WhatsApp send error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: no session
value:
code: 500
error: no session
success: false
upload_failed:
summary: Upload failed
value:
code: 500
error: "Failed to upload file: failed to refresh media connections: websocket not connected"
success: false
whatsapp_rejected_the_send:
summary: WhatsApp rejected the send
value:
code: 500
error: "Error sending message: server returned error 479"
success: false
/chat/send/location:
post:
tags:
- Send
summary: Send a location pin
description: |
Sends a static location (map pin) to a contact or group.
**Accepted keys:** `Phone`, `Latitude`, `Longitude`, `Name`, `Id` (matched case-insensitively, so `latitude`/`longitude` also work), `presence`/`Presence`, `duration`/`Duration`, `number_check`/`NumberCheck`, `ContextInfo` (case-insensitive), plus `mention_info`, `forward_info` and `EchoApi`/`echoApi`/`echo_api`.
**Rules:**
- `Phone`, `Latitude` and `Longitude` are required. Coordinates are decimal degrees (numbers, not strings).
- A coordinate equal to **exactly 0** is treated as missing (400 `missing Latitude in Payload` / `missing Longitude in Payload`), so points on the Equator or the prime meridian cannot be sent as-is.
- `Name` is an optional label shown with the pin; there is no separate address field.
- `Id` sets a custom message ID; otherwise one is generated.
- `presence` (ms) shows a typing indicator and delays the HTTP response.
- `duration` is accepted but **not applied** on this endpoint.
- `number_check: true` verifies the number first.
- Replies need `ContextInfo.stanzaID` + `ContextInfo.participant` together. Mentions via `mention_info`; forwarding via `forward_info.is_forwarded`.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/MessageLocation"
examples:
basic:
summary: Location with a name
value:
Phone: "5511999999999"
Latitude: -23.561414
Longitude: -46.655881
Name: Example Store - Paulista Ave
description: Sends a named location pin.
lowercase_keys:
summary: Lowercase keys with typing delay and number check
value:
phone: "5511988888888"
latitude: -22.951916
longitude: -43.210487
name: Meeting point
presence: 1500
number_check: true
description: Uses lowercase keys, checks the number and shows a typing indicator first.
group_reply:
summary: Location replying in a group
value:
Phone: 120363000000000001@g.us
Latitude: -25.428356
Longitude: -49.273252
Name: Warehouse
ContextInfo:
stanzaID: 3EB0A1B2C3D4E5F60718
participant: 5511988888888@s.whatsapp.net
quotedMessage:
conversation: Where do we pick it up?
description: Replies to a group question with the pickup location.
responses:
"200":
description: Response
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/SuccessEnvelope"
- type: object
properties:
data:
allOf:
- $ref: "#/components/schemas/SendMessageResult"
examples:
sent:
summary: Message acknowledged
value:
code: 200
data:
Details: Sent
Id: 90B2F8B13FAC8A9CF6B06E99C7834DC5
Timestamp: "2022-04-20T12:49:08-03:00"
success: true
"400":
description: |
The request was rejected before sending. Possible `error` values:
- `could not read request body`
- `could not decode Payload`
- `missing Phone in Payload`
- `missing Latitude in Payload`
- `missing Longitude in Payload`
- `could not parse Phone`
- `phone number is not registered on WhatsApp`
- `missing Participant in ContextInfo`
- `failed to check if user is on WhatsApp:` followed by the WhatsApp lookup error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
could_not_read_request_body:
summary: could not read request body
value:
code: 400
error: could not read request body
success: false
could_not_decode_payload:
summary: could not decode Payload
value:
code: 400
error: could not decode Payload
success: false
missing_phone_in_payload:
summary: missing Phone in Payload
value:
code: 400
error: missing Phone in Payload
success: false
missing_latitude_in_payload:
summary: missing Latitude in Payload
value:
code: 400
error: missing Latitude in Payload
success: false
missing_longitude_in_payload:
summary: missing Longitude in Payload
value:
code: 400
error: missing Longitude in Payload
success: false
could_not_parse_phone:
summary: could not parse Phone
value:
code: 400
error: could not parse Phone
success: false
number_check_failed:
summary: Number check failed
value:
code: 400
error: phone number is not registered on WhatsApp
success: false
reply_without_participant:
summary: Reply without participant
value:
code: 400
error: missing Participant in ContextInfo
success: false
number_check_lookup_failed:
summary: Number check lookup failed
value:
code: 400
error: "failed to check if user is on WhatsApp: websocket not connected"
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: |
The session is missing, or preparing or sending the message failed. Possible `error` values:
- `no session`
- `error sending message:` followed by the WhatsApp send error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: no session
value:
code: 500
error: no session
success: false
whatsapp_rejected_the_send:
summary: WhatsApp rejected the send
value:
code: 500
error: "error sending message: server returned error 479"
success: false
/chat/send/contact:
post:
tags:
- Send
summary: Send a contact card (vCard)
description: |
Sends a contact card to a contact or group. The recipient sees `Name` and can open or save the card.
**Accepted keys:** `Phone`, `Name`, `Vcard`, `Id` (matched case-insensitively), `presence`/`Presence`, `duration`/`Duration`, `number_check`/`NumberCheck`, `ContextInfo` (case-insensitive), plus `mention_info`, `forward_info` and `EchoApi`/`echoApi`/`echo_api`.
**Rules:**
- `Phone`, `Name` and `Vcard` are required (400 `missing Name in Payload` / `missing Vcard in Payload`).
- `Name` becomes the card display name. `Vcard` is sent **verbatim** (not validated); use vCard 3.0 with `\n` line breaks. Add `waid=` to the `TEL` line so WhatsApp links the card to the account (Message/Add buttons).
- `Id` sets a custom message ID; otherwise one is generated.
- `presence` (ms) shows a typing indicator and delays the HTTP response.
- `duration` is accepted but **not applied** on this endpoint.
- `number_check: true` verifies the number first (400 `phone number is not registered on WhatsApp`).
- Replies need `ContextInfo.stanzaID` + `ContextInfo.participant` together (400 `missing Participant in ContextInfo`). Mentions via `mention_info`; forwarding via `forward_info.is_forwarded`.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/MessageContact"
examples:
basic:
summary: Share a contact with WhatsApp link
value:
Phone: "5511999999999"
Name: Maria Souza
Vcard: |-
BEGIN:VCARD
VERSION:3.0
N:Souza;Maria;;;
FN:Maria Souza
ORG:Example Ltda
TEL;type=CELL;waid=5511988888888:+55 11 98888-8888
EMAIL;type=INTERNET:maria@example.com
END:VCARD
description: Shares a vCard whose `waid` makes the contact open directly in WhatsApp.
reply_snake_case:
summary: Contact card replying to a message, with number check
value:
phone: "5511977777777"
name: Support Team
vcard: |-
BEGIN:VCARD
VERSION:3.0
FN:Support Team
TEL;type=WORK;waid=5511988888888:+55 11 98888-8888
END:VCARD
number_check: true
presence: 1000
ContextInfo:
stanzaID: 3EB0A1B2C3D4E5F60718
participant: 5511977777777@s.whatsapp.net
quotedMessage:
conversation: Who can help me?
description: Replies with a support contact card using snake_case keys and number check.
responses:
"200":
description: Response
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/SuccessEnvelope"
- type: object
properties:
data:
allOf:
- $ref: "#/components/schemas/SendMessageResult"
examples:
sent:
summary: Message acknowledged
value:
code: 200
data:
Details: Sent
Id: 90B2F8B13FAC8A9CF6B06E99C7834DC5
Timestamp: "2022-04-20T12:49:08-03:00"
success: true
"400":
description: |
The request was rejected before sending. Possible `error` values:
- `could not read request body`
- `could not decode Payload`
- `missing Phone in Payload`
- `missing Name in Payload`
- `missing Vcard in Payload`
- `could not parse Phone`
- `phone number is not registered on WhatsApp`
- `missing Participant in ContextInfo`
- `failed to check if user is on WhatsApp:` followed by the WhatsApp lookup error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
could_not_read_request_body:
summary: could not read request body
value:
code: 400
error: could not read request body
success: false
could_not_decode_payload:
summary: could not decode Payload
value:
code: 400
error: could not decode Payload
success: false
missing_phone_in_payload:
summary: missing Phone in Payload
value:
code: 400
error: missing Phone in Payload
success: false
missing_name_in_payload:
summary: missing Name in Payload
value:
code: 400
error: missing Name in Payload
success: false
missing_vcard_in_payload:
summary: missing Vcard in Payload
value:
code: 400
error: missing Vcard in Payload
success: false
could_not_parse_phone:
summary: could not parse Phone
value:
code: 400
error: could not parse Phone
success: false
number_check_failed:
summary: Number check failed
value:
code: 400
error: phone number is not registered on WhatsApp
success: false
reply_without_participant:
summary: Reply without participant
value:
code: 400
error: missing Participant in ContextInfo
success: false
number_check_lookup_failed:
summary: Number check lookup failed
value:
code: 400
error: "failed to check if user is on WhatsApp: websocket not connected"
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: |
The session is missing, or preparing or sending the message failed. Possible `error` values:
- `no session`
- `error sending message:` followed by the WhatsApp send error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: no session
value:
code: 500
error: no session
success: false
whatsapp_rejected_the_send:
summary: WhatsApp rejected the send
value:
code: 500
error: "error sending message: server returned error 479"
success: false
/chat/send/list:
post:
tags:
- Send
summary: Send a list message
description: |
Sends a single-select **list message**: a text body plus a button that opens sections of selectable rows. The user's choice arrives later as an incoming `Message` event (`listResponseMessage`) carrying the selected `RowId`.
**Accepted keys** (either spelling): `phone`/`Phone`, `text`/`Text`, `title`/`Title`, `footer`/`Footer`, `buttonText`/`ButtonText`, `sections`/`Sections`, `id`/`Id`, `presence`/`Presence`, `duration`/`Duration`, `number_check`/`NumberCheck`, `context_info`/`ContextInfo`, plus `EchoApi`/`echoApi`/`echo_api`. Section: `title`/`Title`, `rows`/`Rows`. Row: `rowId`/`RowId`/`RowID`, `title`/`Title`, `description`/`Description`.
**Validation (lengths are counted in bytes):**
- `Phone`, `Text` and `ButtonText` are required (400 `missing Text in Payload`, `missing ButtonText in Payload`).
- At least one section, and each section needs at least one row (400 `empty Array sections for list message`, `rows canΒ΄t be empty`).
- `Title` β€ 60 (`title max 60 characters`), `Text` β€ 1024 (`body max 1024 characters`), `ButtonText` β€ 20 (`buttonDisplay max 20 characters`), `Footer` β€ 60 (`footer max 60 characters`), section `Title` β€ 60.
- The gateway does not limit the number of sections/rows nor row title/description length; WhatsApp clients apply their own limits. Give every row a unique `RowId`.
**Other rules:**
- Message ID: when the server has `LICENSE_KEY` set, the ID is `` and `Id` is **ignored**; otherwise `Id` is used or a random ID is generated.
- `presence` (ms) shows a typing indicator and delays the HTTP response; `duration` is snapped to 86400, 604800 or 7776000; `number_check: true` verifies the number first.
- Replies need `ContextInfo.stanzaID` + `ContextInfo.participant` together; `ContextInfo.mention_all` in groups mentions every member.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/MessageList"
examples:
product_menu:
summary: Plans and services menu
description: Interactive list with two sections of rows.
value:
Phone: "5511988888888"
Title: 2026 Plans
Text: See this month's highlights
Footer: Choose an option below
ButtonText: See options
Sections:
- Title: Available plans
Rows:
- RowId: plan_basic
Title: Basic plan
Description: Ideal for small teams
- RowId: plan_pro
Title: Pro plan
Description: Advanced features and priority support
- Title: Additional services
Rows:
- RowId: service_consulting
Title: Consulting
Description: 1:1 sessions with specialists
- RowId: service_training
Title: Training
Description: Custom workshops for teams
restaurant_menu:
summary: Restaurant menu in a group
description: Menu sections and dishes sent to a group.
value:
Phone: 120363000000000011@g.us
Title: Weekly special menu
Text: Select your dish below
Footer: Open from 11 AM to 11 PM
ButtonText: Choose a dish
Sections:
- Title: Starters
Rows:
- RowId: starter_01
Title: Bruschetta
Description: Tomato, basil and olive oil
- RowId: starter_02
Title: Carpaccio
Description: Thin beef slices with sauce
- Title: Main courses
Rows:
- RowId: main_01
Title: Shrimp risotto
Description: Arborio rice and grilled shrimp
- RowId: main_02
Title: Filet mignon
Description: Served with gratin potatoes
responses:
"200":
description: Response
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/SuccessEnvelope"
- type: object
properties:
data:
allOf:
- $ref: "#/components/schemas/SendMessageResult"
examples:
sent:
summary: Message acknowledged
value:
code: 200
data:
Details: Sent
Id: 90B2F8B13FAC8A9CF6B06E99C7834DC5
Timestamp: "2022-04-20T12:49:08-03:00"
success: true
"400":
description: |
The request was rejected before sending. Possible `error` values:
- `could not read request body`
- `could not decode Payload`
- `missing Phone in Payload`
- `missing Text in Payload`
- `missing ButtonText in Payload`
- `could not parse Phone`
- `phone number is not registered on WhatsApp`
- `missing Participant in ContextInfo`
- `failed to check if user is on WhatsApp:` followed by the WhatsApp lookup error
- `rows canΒ΄t be empty`
- `title max 60 characters`
- `buttonDisplay max 20 characters`
- `body max 1024 characters`
- `footer max 60 characters`
- `empty Array sections for list message`
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
could_not_read_request_body:
summary: could not read request body
value:
code: 400
error: could not read request body
success: false
could_not_decode_payload:
summary: could not decode Payload
value:
code: 400
error: could not decode Payload
success: false
missing_phone_in_payload:
summary: missing Phone in Payload
value:
code: 400
error: missing Phone in Payload
success: false
missing_text_in_payload:
summary: missing Text in Payload
value:
code: 400
error: missing Text in Payload
success: false
missing_buttontext_in_payload:
summary: missing ButtonText in Payload
value:
code: 400
error: missing ButtonText in Payload
success: false
could_not_parse_phone:
summary: could not parse Phone
value:
code: 400
error: could not parse Phone
success: false
number_check_failed:
summary: Number check failed
value:
code: 400
error: phone number is not registered on WhatsApp
success: false
reply_without_participant:
summary: Reply without participant
value:
code: 400
error: missing Participant in ContextInfo
success: false
number_check_lookup_failed:
summary: Number check lookup failed
value:
code: 400
error: "failed to check if user is on WhatsApp: websocket not connected"
success: false
section_without_rows:
summary: Section without rows
value:
code: 400
error: rows canΒ΄t be empty
success: false
title_or_section_title_longer_than_60_characters:
summary: Title or section title longer than 60 characters
value:
code: 400
error: title max 60 characters
success: false
buttontext_longer_than_20_characters:
summary: ButtonText longer than 20 characters
value:
code: 400
error: buttonDisplay max 20 characters
success: false
text_longer_than_1024_characters:
summary: Text longer than 1024 characters
value:
code: 400
error: body max 1024 characters
success: false
footer_longer_than_60_characters:
summary: Footer longer than 60 characters
value:
code: 400
error: footer max 60 characters
success: false
no_sections:
summary: No sections
value:
code: 400
error: empty Array sections for list message
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: |
The session is missing, or preparing or sending the message failed. Possible `error` values:
- `no session`
- `Error sending message:` followed by the WhatsApp send error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: no session
value:
code: 500
error: no session
success: false
whatsapp_rejected_the_send:
summary: WhatsApp rejected the send
value:
code: 500
error: "Error sending message: server returned error 479"
success: false
/chat/send/poll:
post:
tags:
- Send
summary: Sends a Poll to some group
description: |
Sends a poll (single or multiple choice) to a group or directly to a contact.
**Features:**
- Question in `Header` (or its alias `Question`; `Header` wins when both are sent) with at least 2 `Options`
- `MaxAnswer` limits how many options each participant can choose (default 1)
- Optional typing indicator (`Presence`), number check, disappearing `Duration`, replies, mentions and forwarding
**Rules:**
- `Group` (group JID such as `120363000000000011@g.us`) or `Phone` is required (`400 missing Group or Phone in payload`); `Group` wins when both are sent
- `400 missing Header or Question in payload`, `at least 2 options are required`, `max_answer must be at least 1`, `max_answer cannot be greater than options length ()`
- Vote from this session with `POST /chat/send/pollvote`
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/MessagePoll"
examples:
group_poll:
summary: Poll in a group
description: Multi-answer poll sent to a group with a typing indicator.
value:
Group: 120363000000000011@g.us
Header: What is the best time?
Options:
- "09:00"
- "14:00"
- "19:00"
MaxAnswer: 2
Presence: 2000
NumberCheck: true
direct_poll:
summary: Direct poll to a contact
description: Single-answer poll sent directly to a contact with a 24 h disappearing timer.
value:
Phone: "5511988888888"
Question: Would you recommend our support?
Options:
- "Yes"
- Maybe
- "No"
MaxAnswer: 1
Duration: 86400
responses:
"200":
description: Response
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/SuccessEnvelope"
- type: object
properties:
data:
type: object
description: Result of a successful poll send.
properties:
Details:
type: string
description: Always `Poll sent successfully`.
example: Poll sent successfully
Id:
type: string
description: WhatsApp message ID of the poll.
example: 3EB0C767D26A1D6B8A9F
examples:
sent:
summary: Message acknowledged
value:
code: 200
data:
Details: Poll sent successfully
Id: 90B2F8B13FAC8A9CF6B06E99C7834DC5
success: true
"400":
description: |
The request was rejected before sending. Possible `error` values:
- `could not read request body`
- `could not decode payload`
- `missing Group or Phone in payload`
- `missing Header or Question in payload`
- `at least 2 options are required`
- `max_answer must be at least 1`
- `max_answer cannot be greater than options length (3)`
- `could not parse Phone`
- `phone number is not registered on WhatsApp`
- `missing Participant in ContextInfo`
- `failed to check if user is on WhatsApp:` followed by the WhatsApp lookup error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
could_not_read_request_body:
summary: could not read request body
value:
code: 400
error: could not read request body
success: false
could_not_decode_payload:
summary: could not decode payload
value:
code: 400
error: could not decode payload
success: false
missing_group_or_phone_in_payload:
summary: missing Group or Phone in payload
value:
code: 400
error: missing Group or Phone in payload
success: false
missing_header_or_question_in_payload:
summary: missing Header or Question in payload
value:
code: 400
error: missing Header or Question in payload
success: false
at_least_2_options_are_required:
summary: at least 2 options are required
value:
code: 400
error: at least 2 options are required
success: false
max_answer_must_be_at_least_1:
summary: max_answer must be at least 1
value:
code: 400
error: max_answer must be at least 1
success: false
max_answer_above_the_number_of_options:
summary: max_answer above the number of options
value:
code: 400
error: max_answer cannot be greater than options length (3)
success: false
could_not_parse_phone:
summary: could not parse Phone
value:
code: 400
error: could not parse Phone
success: false
number_check_failed:
summary: Number check failed
value:
code: 400
error: phone number is not registered on WhatsApp
success: false
reply_without_participant:
summary: Reply without participant
value:
code: 400
error: missing Participant in ContextInfo
success: false
number_check_lookup_failed:
summary: Number check lookup failed
value:
code: 400
error: "failed to check if user is on WhatsApp: websocket not connected"
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: |
The session is missing, or preparing or sending the message failed. Possible `error` values:
- `no session`
- `failed to send poll:` followed by the WhatsApp send error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: no session
value:
code: 500
error: no session
success: false
whatsapp_rejected_the_send:
summary: WhatsApp rejected the send
value:
code: 500
error: "failed to send poll: server returned error 479"
success: false
/chat/send/pollvote:
post:
tags:
- Send
summary: Vote on a poll
description: |
Casts or retracts this session's vote on a poll.
**Rules:**
- The poll is identified by the message ID of its creation message (`poll_message_id`)
- Option names must match the poll's options exactly; unknown options are rejected with `400` instead of being sent as an empty vote
- Multi-select polls accept more than one option, up to the poll's own limit
- An empty `options: []` array retracts the vote
- The vote is encrypted with the poll's message secret, so the poll must have been sent or received by this session (`404` otherwise)
- Polls created before this instance recorded poll creator info cannot be voted on (`409`); a vote is never sent with a guessed identity, which WhatsApp would silently drop
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/PollVote"
examples:
single_choice:
summary: Vote on a single-choice poll
value:
phone: "5511999999999"
poll_message_id: 90B2F8B13FAC8A9CF6B06E99C7834DC5
options:
- "09:00"
description: Votes for one option of a single-choice poll.
multi_choice:
summary: Vote on a multi-select poll
value:
phone: 120363000000000011@g.us
poll_message_id: 90B2F8B13FAC8A9CF6B06E99C7834DC5
options:
- "09:00"
- "14:00"
description: Votes for two options of a multi-select poll in a group.
retract:
summary: Retract the vote (empty options)
value:
phone: "5511999999999"
poll_message_id: 90B2F8B13FAC8A9CF6B06E99C7834DC5
options: []
description: Sends an empty options list to retract the previous vote.
responses:
"200":
description: Vote sent
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/SuccessEnvelope"
- type: object
properties:
data:
description: Result of a successful send.
allOf:
- $ref: "#/components/schemas/SendMessageResult"
- type: object
properties:
Options:
type: array
description: Options voted (empty when the vote was retracted).
items:
type: string
example:
- "09:00"
examples:
sent:
summary: Message acknowledged
value:
code: 200
data:
Details: Sent
Id: 3EB0C767D26B8F4A1C42
Options:
- "09:00"
Timestamp: "2026-07-13T18:22:41Z"
success: true
"400":
description: |
The request was rejected before sending. Possible `error` values:
- `could not read request body`
- `could not decode Payload`
- `missing phone in Payload`
- `missing poll_message_id in Payload`
- `could not parse Phone`
- `option "20:00" is not one of this poll's options: [09:00 14:00 19:00]`
- `poll allows at most 1 selected option(s), got 2`
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
could_not_read_request_body:
summary: could not read request body
value:
code: 400
error: could not read request body
success: false
could_not_decode_payload:
summary: could not decode Payload
value:
code: 400
error: could not decode Payload
success: false
missing_phone_in_payload:
summary: missing phone in Payload
value:
code: 400
error: missing phone in Payload
success: false
missing_poll_message_id_in_payload:
summary: missing poll_message_id in Payload
value:
code: 400
error: missing poll_message_id in Payload
success: false
could_not_parse_phone:
summary: could not parse Phone
value:
code: 400
error: could not parse Phone
success: false
unknown_option:
summary: Unknown option
value:
code: 400
error: "option \"20:00\" is not one of this poll's options: [09:00 14:00 19:00]"
success: false
too_many_options_selected:
summary: Too many options selected
value:
code: 400
error: poll allows at most 1 selected option(s), got 2
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"404":
description: |
The referenced message is unknown to this session. Possible `error` values:
- `unknown poll_message_id: this session never sent or received that poll`
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
unknown_poll:
summary: Unknown poll
value:
code: 404
error: "unknown poll_message_id: this session never sent or received that poll"
success: false
"409":
description: |
The message cannot be answered by this session. Possible `error` values:
- `this poll predates vote support (its creator info was never recorded) and cannot be voted on`
- `the poll's message secret is unknown to this session, so its vote cannot be encrypted`
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
poll_predates_vote_support:
summary: Poll predates vote support
value:
code: 409
error: this poll predates vote support (its creator info was never recorded) and cannot be voted on
success: false
poll_secret_unknown:
summary: Poll secret unknown
value:
code: 409
error: the poll's message secret is unknown to this session, so its vote cannot be encrypted
success: false
"500":
description: |
The session is missing, or preparing or sending the message failed. Possible `error` values:
- `no session`
- `failed to load poll metadata`
- `failed to build poll vote:` followed by the vote encryption error
- `error sending poll vote:` followed by the WhatsApp send error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: no session
value:
code: 500
error: no session
success: false
failed_to_load_poll_metadata:
summary: failed to load poll metadata
value:
code: 500
error: failed to load poll metadata
success: false
vote_cannot_be_built:
summary: Vote cannot be built
value:
code: 500
error: "failed to build poll vote: original message secret key not found"
success: false
whatsapp_rejected_the_vote:
summary: WhatsApp rejected the vote
value:
code: 500
error: "error sending poll vote: server returned error 479"
success: false
/chat/send/eventresponse:
post:
tags:
- Send
summary: Respond (RSVP) to a calendar event
description: |
Sends an RSVP to a calendar event message.
**Rules:**
- The event is identified by the message ID of its creation message (`event_message_id`)
- `response` is `GOING`, `NOT_GOING`, `MAYBE` or `UNKNOWN`; anything else returns `400`. `UNKNOWN` removes a previous RSVP
- The RSVP is encrypted with the event's message secret, so the event must have been sent or received by this session (`404` otherwise)
- Events created before this instance recorded event creator info cannot be answered (`409`)
**Guest:**
- Send `with_guest: true` (alias `WithGuest`) for "Going with guest"; the official app sends it as `extraGuestCount=1`
- The guest only applies to `GOING` and is ignored for other responses; `with_guest` takes precedence over `extra_guest_count`
- `extra_guest_count` is deprecated but accepted: `0` means no guest and values of 1 or more are sent as one guest; negative values return `400`
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/EventResponse"
examples:
going:
summary: Confirm attendance
value:
phone: "5511999999999"
event_message_id: 90B2F8B13FAC8A9CF6B06E99C7834DC5
response: GOING
with_guest: false
description: Confirms attendance without a guest.
going_with_guest:
summary: Going with guest
value:
phone: "5511999999999"
event_message_id: 90B2F8B13FAC8A9CF6B06E99C7834DC5
response: GOING
with_guest: true
description: Confirms attendance with one guest.
not_going:
summary: Decline the invitation
value:
phone: "5511999999999"
event_message_id: 90B2F8B13FAC8A9CF6B06E99C7834DC5
response: NOT_GOING
description: Declines the event invitation.
remove:
summary: Remove the RSVP (UNKNOWN)
value:
phone: "5511999999999"
event_message_id: 90B2F8B13FAC8A9CF6B06E99C7834DC5
response: UNKNOWN
description: Removes the previous RSVP by sending `UNKNOWN`.
legacy_extra_guest_count:
summary: Legacy extra_guest_count (deprecated)
value:
phone: "5511999999999"
event_message_id: 90B2F8B13FAC8A9CF6B06E99C7834DC5
response: GOING
extra_guest_count: 1
description: "Deprecated field: any `extra_guest_count` of 1 or more is sent as a single guest."
responses:
"200":
description: RSVP sent
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/SuccessEnvelope"
- type: object
properties:
data:
description: Result of a successful send.
allOf:
- $ref: "#/components/schemas/SendMessageResult"
- type: object
properties:
Response:
type: string
description: RSVP sent.
example: GOING
examples:
sent:
summary: Message acknowledged
value:
code: 200
data:
Details: Sent
Id: 3EB0C767D26B8F4A1C42
Response: GOING
Timestamp: "2026-07-13T18:22:41Z"
success: true
"400":
description: |
The request was rejected before sending. Possible `error` values:
- `could not read request body`
- `could not decode Payload`
- `missing phone in Payload`
- `missing event_message_id in Payload`
- `missing response in Payload`
- `extra_guest_count cannot be negative`
- `could not parse Phone`
- `response must be one of GOING, NOT_GOING, MAYBE or UNKNOWN`
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
could_not_read_request_body:
summary: could not read request body
value:
code: 400
error: could not read request body
success: false
could_not_decode_payload:
summary: could not decode Payload
value:
code: 400
error: could not decode Payload
success: false
missing_phone_in_payload:
summary: missing phone in Payload
value:
code: 400
error: missing phone in Payload
success: false
missing_event_message_id_in_payload:
summary: missing event_message_id in Payload
value:
code: 400
error: missing event_message_id in Payload
success: false
missing_response_in_payload:
summary: missing response in Payload
value:
code: 400
error: missing response in Payload
success: false
extra_guest_count_cannot_be_negative:
summary: extra_guest_count cannot be negative
value:
code: 400
error: extra_guest_count cannot be negative
success: false
could_not_parse_phone:
summary: could not parse Phone
value:
code: 400
error: could not parse Phone
success: false
unknown_response_value:
summary: Unknown response value
value:
code: 400
error: response must be one of GOING, NOT_GOING, MAYBE or UNKNOWN
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"404":
description: |
The referenced message is unknown to this session. Possible `error` values:
- `unknown event_message_id: this session never sent or received that event`
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
unknown_event:
summary: Unknown event
value:
code: 404
error: "unknown event_message_id: this session never sent or received that event"
success: false
"409":
description: |
The message cannot be answered by this session. Possible `error` values:
- `this event predates RSVP support (its creator info was never recorded) and cannot be answered`
- `the event's message secret is unknown to this session, so its RSVP cannot be encrypted`
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
event_predates_rsvp_support:
summary: Event predates RSVP support
value:
code: 409
error: this event predates RSVP support (its creator info was never recorded) and cannot be answered
success: false
event_secret_unknown:
summary: Event secret unknown
value:
code: 409
error: the event's message secret is unknown to this session, so its RSVP cannot be encrypted
success: false
"500":
description: |
The session is missing, or preparing or sending the message failed. Possible `error` values:
- `no session`
- `failed to load event metadata`
- `failed to build event response:` followed by the RSVP encryption error
- `error sending event response:` followed by the WhatsApp send error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: no session
value:
code: 500
error: no session
success: false
failed_to_load_event_metadata:
summary: failed to load event metadata
value:
code: 500
error: failed to load event metadata
success: false
rsvp_cannot_be_built:
summary: RSVP cannot be built
value:
code: 500
error: "failed to build event response: failed to encrypt event response: original message secret key not found"
success: false
whatsapp_rejected_the_rsvp:
summary: WhatsApp rejected the RSVP
value:
code: 500
error: "error sending event response: server returned error 479"
success: false
/chat/send/event:
post:
tags:
- Send
summary: Send event message
description: |
Send calendar event invitation with date, time, location, and description to a WhatsApp contact or group.
Recipients can add the event to their calendar. Perfect for meetings, appointments, conferences, and scheduled calls.
**Features:**
- **Event Details**: Name, description, start/end times
- **Location Support**: GPS coordinates and address
- **Call Integration**: Schedule video/voice meetings
- **Guest Management**: Allow additional guests
- **Cancellation**: Mark events as cancelled
- **Message Enhancements**: Replies, forwarding, mentions, expiration
**Use Cases:**
- π Meeting invitations
- π Event planning (parties, conferences)
- π Scheduled calls
- π’ Location-based events
- β Event cancellations
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/MessageEvent"
examples:
business_meeting:
summary: Business Meeting
description: Schedule a business meeting with location
value:
Phone: "5511999999999"
Name: Weekly Team Sync π
Description: Discussion of project updates, blockers, and next steps
StartTime: 2524608000
EndTime: 2556143999
ExtraGuestsAllowed: true
IsScheduleCall: true
Location:
Name: Conference Room A, Main Office
DegreesLatitude: -23.5505
DegreesLongitude: -46.6333
NumberCheck: true
ContextInfo:
MentionedJID:
- 5511999999999@s.whatsapp.net
virtual_event:
summary: Virtual Event
description: Online event without physical location
value:
Phone: 120363000000000011@g.us
Name: Product Launch Event π
Description: Join us for the launch of our new product line
StartTime: 1703184000
EndTime: 1703191200
ExtraGuestsAllowed: true
IsScheduleCall: true
MentionInfo:
MentionAll: true
responses:
"200":
description: Event message sent successfully
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/SuccessEnvelope"
- type: object
properties:
data:
allOf:
- $ref: "#/components/schemas/SendMessageResult"
examples:
sent:
summary: Message acknowledged
value:
code: 200
data:
Details: Sent
Id: 3EB0C767D26A1D6B8A9F
Timestamp: "2022-04-20T12:49:08-03:00"
success: true
"400":
description: |
The request was rejected before sending. Possible `error` values:
- `could not read request body`
- `Could not decode Payload`
- `Missing phone in Payload`
- `Missing name in Payload`
- `Missing start_time in Payload`
- `Could not parse JID`
- `Number is not on WhatsApp`
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
could_not_read_request_body:
summary: could not read request body
value:
code: 400
error: could not read request body
success: false
could_not_decode_payload:
summary: Could not decode Payload
value:
code: 400
error: Could not decode Payload
success: false
missing_phone_in_payload:
summary: Missing phone in Payload
value:
code: 400
error: Missing phone in Payload
success: false
missing_name_in_payload:
summary: Missing name in Payload
value:
code: 400
error: Missing name in Payload
success: false
missing_start_time_in_payload:
summary: Missing start_time in Payload
value:
code: 400
error: Missing start_time in Payload
success: false
could_not_parse_jid:
summary: Could not parse JID
value:
code: 400
error: Could not parse JID
success: false
number_check_failed:
summary: Number check failed
value:
code: 400
error: Number is not on WhatsApp
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: |
The session is missing, or preparing or sending the message failed. Possible `error` values:
- `No session`
- `Failed to check if 5511999999999 is on WhatsApp:` followed by the phone number and the WhatsApp lookup error
- `Error sending event:` followed by the WhatsApp send error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: No session
value:
code: 500
error: No session
success: false
number_check_lookup_failed:
summary: Number check lookup failed
value:
code: 500
error: "Failed to check if 5511999999999 is on WhatsApp: websocket not connected"
success: false
whatsapp_rejected_the_send:
summary: WhatsApp rejected the send
value:
code: 500
error: "Error sending event: server returned error 479"
success: false
/chat/send/buttons:
post:
tags:
- Send
summary: Send interactive buttons message
description: |
Send an interactive message with buttons to a WhatsApp contact or group. Supports multiple button types and media headers.
**β οΈ IMPORTANT - Text fields (canonical casing):**
- Payloads should use `lowerCamelCase` (e.g. `buttonId`, `displayText`) and, where applicable, the optional snake_case fields such as `pix_key`.
- With a **media header** (`image`/`video`/`document`): put the main content in `caption` or `text`.
- **Without** media: use `text` or `body`. The handler mirrors one into the other automatically.
- Media examples use `text` for backend compatibility.
**Supported Button Types:**
- π **reply/quick_reply** β quick reply button (returns `buttonId`)
- π **url/cta_url** β opens an HTTP(S) link (`url` or `merchant_url`)
- π **call/cta_call** β starts a voice call (`phone` in E.164 format)
- π **copy/cta_copy** β copies a code (`code`)
- π° **pix/payment_info** β PIX payment button (`pix_key`, `merchant_name`, `pix_type`, ...)
- π³ **review_and_pay** β review and pay with an item list (`items[]`)
A reply/quick_reply button cannot be mixed with other button types in the same message (400 `if a ButtonReply is present, other button types are not allowed`).
**Media Header Support:**
- πΌοΈ `image` β shows an image above the buttons (`image.url` required)
- π₯ `video` β shows a short video (`video.url`)
- π `document` β shows a document (`document.url`)
**Button Configuration:**
Each button requires `buttonId`, `buttonText.displayText` and `type`.
Additional fields depend on the type:
- **url/cta_url**: `url` or `merchant_url`
- **call/cta_call**: `phone`
- **copy/cta_copy**: `code`
- **pix/payment_info**: `pix_key`, `merchant_name`, `pix_type`, `currency`, `total_value`, `total_offset`
- **review_and_pay**: `reference_id` and `items[]` with `name`, `quantity`, `amount_value`, `amount_offset`
**Payment Items Structure** (`review_and_pay`):
Each item must provide `name`, `quantity`, `amount_value`, `amount_offset`.
**Text Fields:**
- **title**: Required main title (1 to 60 characters). Do not send only spaces: WhatsApp would show an empty header area.
- **text/body**: Message content (required when there is no media)
- **footer**: Secondary text (optional)
- **caption**: Used as the body when sending media
Requires an Enterprise license (403 otherwise).
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ButtonsMessage"
examples:
pix_payment:
summary: PIX payment button
description: PIX key button using the camelCase/snake_case payload accepted by the API.
value:
phone: "5511988888888"
title: PIX payment
body: Scan the QR code to pay with PIX
footer: Secure instant payment
buttons:
- buttonId: pix_btn_1
buttonText:
displayText: Pay with PIX
type: pix
pix_key: "11999999999"
merchant_name: Example Store
pix_type: PHONE
review_and_pay:
summary: Review and pay
description: Order review with an item list and PIX payment (amounts in minor units).
value:
phone: "5511988888888"
title: Review your order
text: Confirm the items before paying
footer: Ships within 24 hours after confirmation
buttons:
- buttonId: review_pay_btn
buttonText:
displayText: Review and pay
type: review_and_pay
pix_key: "11999999999"
merchant_name: Example Store
pix_type: PHONE
currency: BRL
total_value: 10990
total_offset: 100
reference_id: ORDER-2026-001
items:
- name: Headphones
quantity: 1
amount_value: 7990
amount_offset: 100
- name: USB-C cable
quantity: 1
amount_value: 1990
amount_offset: 100
- name: Express shipping
quantity: 1
amount_value: 1000
amount_offset: 100
pix_with_pdf:
summary: PIX with a PDF invoice
description: "review_and_pay button with a PDF document header, suited to invoices and bills. Supported pix_type values: CPF, CNPJ, EMAIL, PHONE, EVP (random key)."
value:
phone: "5511988888888"
title: Monthly invoice
text: Your invoice is available. Pay with PIX.
footer: "Due date: 2026-10-15"
document:
url: https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf
buttons:
- buttonId: pix_invoice_1
buttonText:
displayText: Pay invoice
type: review_and_pay
pix_key: billing@example.com
merchant_name: Example Company Ltd
pix_type: EMAIL
currency: BRL
total_value: 29990
total_offset: 100
reference_id: INV-2026-09-001
items:
- name: September subscription
quantity: 1
amount_value: 24990
amount_offset: 100
- name: Service fee
quantity: 1
amount_value: 5000
amount_offset: 100
pix_evp:
summary: PIX with a random key (EVP)
description: PIX button with a random EVP key, suited to one-off payments.
value:
phone: "5511988888888"
title: PIX payment
body: Copy the PIX key and pay in your banking app
footer: Secure instant payment
buttons:
- buttonId: pix_evp_1
buttonText:
displayText: Copy PIX key
type: pix
pix_key: 123e4567-e89b-12d3-a456-426614174000
merchant_name: Example Store
pix_type: EVP
video_cta_url:
summary: Video header with a URL button
description: Product demo video with a button that opens the offer page.
value:
phone: "5511988888888"
title: Product demo
text: Watch the video and buy!
footer: Instant payment
video:
url: https://download.blender.org/durian/trailer/sintel_trailer-480p.mp4
buttons:
- buttonId: cta_url_1
buttonText:
displayText: Open site
type: cta_url
url: https://example.com/offer
document_cta_url:
summary: PDF catalog with a URL button
description: Catalog download with a CTA URL button.
value:
phone: "5511988888888"
title: Product catalog
text: Download our catalog
footer: PDF with every product
document:
url: https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf
buttons:
- buttonId: cta_url_1
buttonText:
displayText: Open site
type: cta_url
url: https://example.com/offer
image_quick_reply:
summary: Image header with a quick reply
description: Attendance confirmation using a quick reply button.
value:
phone: "5511988888888"
title: Confirm your attendance
text: VIP event on Oct 12 at 8 PM
footer: Reply below
image:
url: https://picsum.photos/600/400.jpg
buttons:
- buttonId: reply_maybe
buttonText:
displayText: Maybe
type: quick_reply
multi_action:
summary: Copy + URL + call buttons
description: Mixes copy code, URL and call buttons in one message.
value:
phone: "5511988888888"
title: Deals of the day
text: "Choose an action below:"
footer: ZuckZapGo team
buttons:
- buttonId: cta_copy_1
buttonText:
displayText: Copy coupon
type: cta_copy
code: COUPON123
- buttonId: cta_url_1
buttonText:
displayText: Open site
type: cta_url
url: https://example.com/offer
- buttonId: cta_call_1
buttonText:
displayText: Call sales
type: cta_call
phone: "+5511988888888"
responses:
"200":
description: Buttons message sent successfully
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/SuccessEnvelope"
- type: object
properties:
data:
allOf:
- $ref: "#/components/schemas/SendMessageResult"
examples:
sent:
summary: Message acknowledged
value:
code: 200
data:
Details: Sent
Id: 3EB0C767D26A1D6B8A9F
Timestamp: "2022-04-20T12:49:08-03:00"
success: true
"400":
description: |
The request was rejected before sending. Possible `error` values:
- `could not read request body`
- `could not decode Payload`
- `missing Phone in Payload`
- `could not parse Phone`
- `phone number is not registered on WhatsApp`
- `missing Participant in ContextInfo`
- `failed to check if user is on WhatsApp:` followed by the WhatsApp lookup error
- `button type not found:` followed by the unknown `type` value
- `button type not specified`
- `url required`
- `url example.com/offer is not valid`
- `text canΒ΄t be null`
- `text max 30 characters`
- `phone required`
- `code required`
- `id required`
- `BANK is not pix type, valid type: PHONE, CPF, CNPJ, EMAIL and EVP`
- `error processing media:` followed by the header media download or decoding error
- `no body text provided`
- `header canΒ΄t be null`
- `title max 60 characters`
- `text max 1024 characters`
- `footer max 1024 characters`
- `empty Array buttons`
- `3 buttons is the limit`
- `if a ButtonReply is present, other button types are not allowed`
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
could_not_read_request_body:
summary: could not read request body
value:
code: 400
error: could not read request body
success: false
could_not_decode_payload:
summary: could not decode Payload
value:
code: 400
error: could not decode Payload
success: false
missing_phone_in_payload:
summary: missing Phone in Payload
value:
code: 400
error: missing Phone in Payload
success: false
could_not_parse_phone:
summary: could not parse Phone
value:
code: 400
error: could not parse Phone
success: false
number_check_failed:
summary: Number check failed
value:
code: 400
error: phone number is not registered on WhatsApp
success: false
reply_without_participant:
summary: Reply without participant
value:
code: 400
error: missing Participant in ContextInfo
success: false
number_check_lookup_failed:
summary: Number check lookup failed
value:
code: 400
error: "failed to check if user is on WhatsApp: websocket not connected"
success: false
unknown_button_type:
summary: Unknown button type
value:
code: 400
error: "button type not found: carousel"
success: false
button_without_type:
summary: Button without type
value:
code: 400
error: button type not specified
success: false
url_button_without_url:
summary: URL button without url
value:
code: 400
error: url required
success: false
invalid_button_url:
summary: Invalid button URL
value:
code: 400
error: url example.com/offer is not valid
success: false
button_without_displaytext:
summary: Button without displayText
value:
code: 400
error: text canΒ΄t be null
success: false
displaytext_longer_than_30_characters:
summary: displayText longer than 30 characters
value:
code: 400
error: text max 30 characters
success: false
call_button_without_phone:
summary: Call button without phone
value:
code: 400
error: phone required
success: false
copy_button_without_code:
summary: Copy button without code
value:
code: 400
error: code required
success: false
reply_button_without_buttonid:
summary: Reply button without buttonId
value:
code: 400
error: id required
success: false
unknown_pix_type:
summary: Unknown pix_type
value:
code: 400
error: "BANK is not pix type, valid type: PHONE, CPF, CNPJ, EMAIL and EVP"
success: false
header_media_cannot_be_processed:
summary: Header media cannot be processed
value:
code: 400
error: "error processing media: HTTP error 404 when downloading from URL"
success: false
no_body_text:
summary: No body text
value:
code: 400
error: no body text provided
success: false
empty_title:
summary: Empty title
value:
code: 400
error: header canΒ΄t be null
success: false
title_longer_than_60_characters:
summary: Title longer than 60 characters
value:
code: 400
error: title max 60 characters
success: false
body_longer_than_1024_characters:
summary: Body longer than 1024 characters
value:
code: 400
error: text max 1024 characters
success: false
footer_longer_than_1024_characters:
summary: Footer longer than 1024 characters
value:
code: 400
error: footer max 1024 characters
success: false
no_buttons:
summary: No buttons
value:
code: 400
error: empty Array buttons
success: false
more_than_3_buttons:
summary: More than 3 buttons
value:
code: 400
error: 3 buttons is the limit
success: false
reply_mixed_with_other_button_types:
summary: Reply mixed with other button types
value:
code: 400
error: if a ButtonReply is present, other button types are not allowed
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"403":
description: "Forbidden: this route requires an Enterprise license. The server returns the fixed Portuguese message shown in the example."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 403
error: este recurso requer licença Enterprise; entre em contato com o suporte para adquirir acesso
success: false
"500":
description: |
The session is missing, or preparing or sending the message failed. Possible `error` values:
- `no session`
- `error uploading media:` followed by the WhatsApp media upload error
- `Error sending message:` followed by the WhatsApp send error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: no session
value:
code: 500
error: no session
success: false
header_upload_failed:
summary: Header upload failed
value:
code: 500
error: "error uploading media: failed to refresh media connections: websocket not connected"
success: false
whatsapp_rejected_the_send:
summary: WhatsApp rejected the send
value:
code: 500
error: "Error sending message: server returned error 479"
success: false
/chat/send/flow:
post:
tags:
- Send
summary: Send native flow interactive message
description: |
Sends a WhatsApp Flow (an interactive form) to a contact.
**How to use:**
- Create the form in the WhatsApp Business app (Tools β Forms)
- Send that form once from the app to any chat; the message reaches your webhook, where you copy `flow_id` (and the rest of `button_params_json`) and save it
- Send the form through this endpoint with button `name` `galaxy_message` and the saved `flow_id` inside `button_params_json`
- Submitted answers arrive at your configured webhook
**Rules:**
- Requires an Enterprise license (`403`)
- Replace `flow_id` in the examples with your own form's ID
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/FlowMessage"
examples:
contact_details_form:
summary: Customer info form
description: Asks the contact for name, email, phone and document. Replace flow_id with your form's id.
value:
phone: "5511999999999"
body: Please send us your details.
message_version: 3
buttons:
- name: galaxy_message
button_params_json: '{"flow_message_version":"4","flow_id":"1380039803972405","flow_action_payload":{"screen":"contact_details","data":{"full_name_visible":true,"phone_number_visible":true,"email_visible":true,"cpf_or_cnpj_visible":true,"delivery_address_visible":false,"citizenship_card_visible":false,"custom_fields":[{"type":"TEXT_INPUT","label":"Delivery address"}]}},"well_version":"V700","flow_cta":"__localize:FLOWS_COMPLETE_FORM_BUTTON_TITLE","flow_action":"navigate","flow_token":"Q1VTVE9NRVJfSU5GTw==","form_type":"template"}'
offer_signup_form:
summary: Offer sign-up form
description: Sign-up form with an offer title and description. Replace flow_id with your form's id.
value:
phone: "5511999999999"
body: Claim your offer β fill out the form.
message_version: 3
buttons:
- name: galaxy_message
button_params_json: '{"flow_message_version":"4","flow_id":"2804269256615624","flow_action_payload":{"screen":"contact_details","data":{"full_name_visible":true,"phone_number_visible":true,"email_visible":true,"delivery_address_visible":false,"cpf_or_cnpj_visible":false,"citizenship_card_visible":false,"offer_name":"Special offer","offer_description":"offer description"}},"well_version":"V700","flow_cta":"__localize:FLOWS_COMPLETE_FORM_BUTTON_TITLE","flow_action":"navigate","flow_token":"T0ZGRVJfU0lHTlVQ","form_type":"template"}'
responses:
"200":
description: Flow message sent successfully
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/SuccessEnvelope"
- type: object
properties:
data:
allOf:
- $ref: "#/components/schemas/SendMessageResult"
examples:
sent:
summary: Message acknowledged
value:
code: 200
data:
Details: Sent
Id: 3EB0C767D26A1D6B8A9F
Timestamp: "2022-04-20T12:49:08-03:00"
success: true
"400":
description: |
The request was rejected before sending. Possible `error` values:
- `could not read request body`
- `could not decode Payload`
- `missing body text in Payload`
- `missing Phone in Payload`
- `at least one button is required`
- `button name is required`
- `could not parse Phone`
- `phone number is not registered on WhatsApp`
- `missing Participant in ContextInfo`
- `failed to check if user is on WhatsApp:` followed by the WhatsApp lookup error
- `invalid button name "flow": it renders as "message not compatible" on the recipient. For a real WhatsApp flow form use name "galaxy_message" with buttonParamsJson form_type "template". See this endpoint's description for a complete, working example.`
- `invalid button name "send form": native_flow button names are snake_case without spaces (e.g. "galaxy_message")`
- `button params required for 'galaxy_message'`
- `invalid JSON in button params for button 'galaxy_message'`
- `invalid JSON in message_params`
- `error processing header media:` followed by the header media download or decoding error
- `unsupported header media type:` followed by the unsupported `Header.Media.Type`
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
could_not_read_request_body:
summary: could not read request body
value:
code: 400
error: could not read request body
success: false
could_not_decode_payload:
summary: could not decode Payload
value:
code: 400
error: could not decode Payload
success: false
missing_body_text_in_payload:
summary: missing body text in Payload
value:
code: 400
error: missing body text in Payload
success: false
missing_phone_in_payload:
summary: missing Phone in Payload
value:
code: 400
error: missing Phone in Payload
success: false
at_least_one_button_is_required:
summary: at least one button is required
value:
code: 400
error: at least one button is required
success: false
button_name_is_required:
summary: button name is required
value:
code: 400
error: button name is required
success: false
could_not_parse_phone:
summary: could not parse Phone
value:
code: 400
error: could not parse Phone
success: false
number_check_failed:
summary: Number check failed
value:
code: 400
error: phone number is not registered on WhatsApp
success: false
reply_without_participant:
summary: Reply without participant
value:
code: 400
error: missing Participant in ContextInfo
success: false
number_check_lookup_failed:
summary: Number check lookup failed
value:
code: 400
error: "failed to check if user is on WhatsApp: websocket not connected"
success: false
button_named_flow:
summary: Button named flow
value:
code: 400
error: "invalid button name \"flow\": it renders as \"message not compatible\" on the recipient. For a real WhatsApp flow form use name \"galaxy_message\" with buttonParamsJson form_type \"template\". See this endpoint's description for a complete, working example."
success: false
button_name_with_spaces:
summary: Button name with spaces
value:
code: 400
error: 'invalid button name "send form": native_flow button names are snake_case without spaces (e.g. "galaxy_message")'
success: false
button_without_params:
summary: Button without params
value:
code: 400
error: button params required for 'galaxy_message'
success: false
invalid_button_params_json:
summary: Invalid button params JSON
value:
code: 400
error: invalid JSON in button params for button 'galaxy_message'
success: false
invalid_message_params_json:
summary: Invalid message_params JSON
value:
code: 400
error: invalid JSON in message_params
success: false
header_media_cannot_be_processed:
summary: Header media cannot be processed
value:
code: 400
error: "error processing header media: HTTP error 404 when downloading from URL"
success: false
unsupported_header_media_type:
summary: Unsupported header media type
value:
code: 400
error: "unsupported header media type: audio"
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"403":
description: "Forbidden: this route requires an Enterprise license. The server returns the fixed Portuguese message shown in the example."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 403
error: este recurso requer licença Enterprise; entre em contato com o suporte para adquirir acesso
success: false
"500":
description: |
The session is missing, or preparing or sending the message failed. Possible `error` values:
- `no session`
- `error uploading header media:` followed by the WhatsApp media upload error
- `Error sending message:` followed by the WhatsApp send error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: no session
value:
code: 500
error: no session
success: false
header_upload_failed:
summary: Header upload failed
value:
code: 500
error: "error uploading header media: failed to refresh media connections: websocket not connected"
success: false
whatsapp_rejected_the_send:
summary: WhatsApp rejected the send
value:
code: 500
error: "Error sending message: server returned error 479"
success: false
/chat/send/carousel:
post:
tags:
- Send
summary: Send carousel message with multiple cards
description: |
Send a carousel message containing multiple scrollable cards. Each card can include media (image, video, document),
text content, and interactive buttons. Perfect for product showcases, service catalogs, and multi-option presentations.
**Carousel Structure:**
- **Phone**: Recipient phone number or group JID (required)
- **Message**: Introductory message text before carousel (required)
- **Carousel**: Array of card objects (required, at least 1 card)
**Card Structure:**
Each card can contain:
- **Text**: Card body text (required)
- **MediaUrl**: URL or base64 data URL for media (optional)
- **MediaType**: Type of media - image, video, or document (required if MediaUrl provided)
- **Filename**: Document filename (optional, for documents)
- **Caption**: Media caption text (optional)
- **Buttons**: Array of button objects (required)
**Button Types:**
- π **reply** - Quick reply button (id + label)
- π **url** - Opens web link (url + label)
- π **copy** - Copies code to clipboard (id as code + label)
- π **call** - Initiates phone call (id as phone + label)
**Button Structure:**
- **Id**: Button identifier (for reply/copy) or phone number (for call)
- **Label**: Button display text
- **Url**: Destination URL (for url type buttons)
- **Type**: Button type (reply, url, copy, call)
**Media Support:**
- **Images**: JPEG, PNG, WebP (recommended max 5MB)
- **Videos**: MP4, 3GP (recommended max 16MB, max 90 seconds)
- **Documents**: PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT
**Common Use Cases:**
- ποΈ Product catalogs with images and buy buttons
- π¨ Hotel room options with photos and booking links
- π Restaurant menu with dishes and order buttons
- π Course offerings with descriptions and enrollment
- π’ Service packages with pricing and contact options
- π± Feature comparisons with specifications
**Best Practices:**
- Use 2-10 cards per carousel (optimal user experience)
- Keep card text concise (50-100 characters recommended)
- Use high-quality images (at least 800x600px)
- Limit to 1-3 buttons per card
- Maintain consistent card structure throughout carousel
**Advanced Features:**
- Context info for replying to messages
- Mention support for tagging users
- Forward info for message forwarding
- Presence and duration control
- Number validation before sending
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CarouselMessage"
examples:
product_catalog:
summary: Product Catalog
description: E-commerce product showcase with images
value:
Phone: "5511999999999"
Message: Check out our featured products! ποΈ
Carousel:
- Text: |-
Premium Wireless Headphones π§
β’ Noise cancellation
β’ 30h battery
β’ Premium sound
$299.99
MediaUrl: https://picsum.photos/600/400.jpg
MediaType: image
Caption: Best Seller!
Buttons:
- Id: buy_headphones
Label: π Buy Now
Url: https://store.example.com/headphones
Type: url
- Id: headphones_details
Label: βΉοΈ Details
Type: reply
- Text: |-
Smart Watch Pro β
β’ Fitness tracking
β’ Heart rate monitor
β’ Water resistant
$199.99
MediaUrl: https://picsum.photos/600/400.jpg
MediaType: image
Caption: New Arrival!
Buttons:
- Id: buy_watch
Label: π Buy Now
Url: https://store.example.com/watch
Type: url
- Id: watch_details
Label: βΉοΈ Details
Type: reply
- Text: |-
Bluetooth Speaker π
β’ 360Β° sound
β’ 12h battery
β’ Portable design
$79.99
MediaUrl: https://picsum.photos/600/400.jpg
MediaType: image
Caption: Hot Deal!
Buttons:
- Id: buy_speaker
Label: π Buy Now
Url: https://store.example.com/speaker
Type: url
- Id: speaker_details
Label: βΉοΈ Details
Type: reply
video_carousel:
summary: Video Carousel
description: Product demos with video previews
value:
Phone: "5511999999999"
Message: Watch our product demonstrations! π₯
Carousel:
- Text: |-
Product Setup Tutorial
Learn how to set up your new device in under 5 minutes
MediaUrl: https://download.blender.org/durian/trailer/sintel_trailer-480p.mp4
MediaType: video
Caption: Quick Setup Guide
Buttons:
- Id: PDF_MANUAL_123
Label: π Copy Manual Code
Type: copy
- Id: full_tutorial
Label: π¬ Full Tutorial
Url: https://youtube.com/watch?v=example
Type: url
- Text: |-
Advanced Features Demo
Discover pro tips and hidden features
MediaUrl: https://download.blender.org/durian/trailer/sintel_trailer-480p.mp4
MediaType: video
Caption: Pro Tips
Buttons:
- Id: features_guide
Label: π Feature Guide
Type: reply
responses:
"200":
description: Carousel message sent successfully
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/SuccessEnvelope"
- type: object
properties:
data:
allOf:
- $ref: "#/components/schemas/SendMessageResult"
examples:
sent:
summary: Message acknowledged
value:
code: 200
data:
Details: Sent
Id: 3EB0C767D26A1D6B8A9F
Timestamp: "2022-04-20T12:49:08-03:00"
success: true
"400":
description: |
The request was rejected before sending. Possible `error` values:
- `could not read request body`
- `could not decode Payload`
- `missing Phone in Payload`
- `missing Carousel in Payload`
- `could not parse Phone`
- `phone number is not registered on WhatsApp`
- `missing Participant in ContextInfo`
- `failed to check if user is on WhatsApp:` followed by the WhatsApp lookup error
- `error processing media:` followed by the card media download or decoding error
- `invalid media type`
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
could_not_read_request_body:
summary: could not read request body
value:
code: 400
error: could not read request body
success: false
could_not_decode_payload:
summary: could not decode Payload
value:
code: 400
error: could not decode Payload
success: false
missing_phone_in_payload:
summary: missing Phone in Payload
value:
code: 400
error: missing Phone in Payload
success: false
missing_carousel_in_payload:
summary: missing Carousel in Payload
value:
code: 400
error: missing Carousel in Payload
success: false
could_not_parse_phone:
summary: could not parse Phone
value:
code: 400
error: could not parse Phone
success: false
number_check_failed:
summary: Number check failed
value:
code: 400
error: phone number is not registered on WhatsApp
success: false
reply_without_participant:
summary: Reply without participant
value:
code: 400
error: missing Participant in ContextInfo
success: false
number_check_lookup_failed:
summary: Number check lookup failed
value:
code: 400
error: "failed to check if user is on WhatsApp: websocket not connected"
success: false
card_media_cannot_be_processed:
summary: Card media cannot be processed
value:
code: 400
error: "error processing media: HTTP error 404 when downloading from URL"
success: false
unknown_card_media_type:
summary: Unknown card media type
value:
code: 400
error: invalid media type
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"403":
description: "Forbidden: this route requires an Enterprise license. The server returns the fixed Portuguese message shown in the example."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 403
error: este recurso requer licença Enterprise; entre em contato com o suporte para adquirir acesso
success: false
"500":
description: |
The session is missing, or preparing or sending the message failed. Possible `error` values:
- `no session`
- `failed to upload file:` followed by the WhatsApp media upload error
- `Error sending carousel message:` followed by the WhatsApp send error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: no session
value:
code: 500
error: no session
success: false
upload_failed:
summary: Upload failed
value:
code: 500
error: "failed to upload file: failed to refresh media connections: websocket not connected"
success: false
whatsapp_rejected_the_send:
summary: WhatsApp rejected the send
value:
code: 500
error: "Error sending carousel message: server returned error 479"
success: false
/chat/downloadimage:
post:
tags:
- Chat
summary: Download the image of a message
description: |
Downloads and decrypts the image of a received or sent message and returns the whole file inline as a base64 data URL, ready for an HTML `` tag or to be saved to disk.
**Where the fields come from:** Copy the fields from `event.Message.imageMessage` of the `Message` webhook event (view-once images are nested under `viewOnceMessageV2.message.imageMessage`). Keys are matched case-insensitively and unknown keys are ignored, so that `imageMessage` object can be posted unchanged.
**Rules (image):**
- `DirectPath`, `MediaKey`, `FileEncSHA256` and `FileSHA256` are what the image download needs; without `DirectPath` it fails with **500** `failed to download image no url present`.
- The image `MediaKey` and both hashes are standard base64 strings exactly as in the webhook JSON; a value that is not valid base64 returns **400** `could not decode Payload`.
- A key or hash that does not match the image fails with **500** `failed to download image invalid media hmac` (or a hash mismatch detail); an expired CDN link fails with `download failed with status code 404` or `410`.
- `Url` and `FileLength` are accepted but not used for the image. `Mimetype` is not validated: it is echoed in the response and used as the image data URL media type.
- JPEG is the usual format; `Data` starts with `data:image/jpeg;base64,`.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ChatDownloadMediaRequest"
examples:
image_fields:
summary: Fields copied from the webhook imageMessage
description: Minimal body with the gateway field names.
value:
Url: "https://mmg.whatsapp.net/o1/v/t62.7118-24/f2/m231/AQ_example_image.enc?ccb=9-4&oh=01_Q5Aa0000&oe=68F0A1B2&_nc_sid=e6ed6c"
DirectPath: "/o1/v/t62.7118-24/f2/m231/AQ_example_image.enc?ccb=9-4&oh=01_Q5Aa0000&oe=68F0A1B2&_nc_sid=e6ed6c"
MediaKey: "aQGcesqhANsFce2gBbNeXnE4LU9wA6LM5lA1ztbBduM="
Mimetype: "image/jpeg"
FileEncSHA256: "8wdTCF7kBugCQhneOg2YLsDye4Eqwu7N8kzyXKJXoIU="
FileSHA256: "Gc6NIzcYSI596Ke0Y0sO1VstRgq8FpAUzOglP06aYyE="
FileLength: 48213
webhook_object_verbatim:
summary: Posting event.Message.imageMessage unchanged
description: Webhook keys (`URL`, `directPath`, `mediaKey`, ...) map case-insensitively to the body fields; extra keys are ignored.
value:
URL: "https://mmg.whatsapp.net/o1/v/t62.7118-24/f2/m231/AQ_example_image.enc?ccb=9-4&oh=01_Q5Aa0000&oe=68F0A1B2&_nc_sid=e6ed6c"
directPath: "/o1/v/t62.7118-24/f2/m231/AQ_example_image.enc?ccb=9-4&oh=01_Q5Aa0000&oe=68F0A1B2&_nc_sid=e6ed6c"
mediaKey: "aQGcesqhANsFce2gBbNeXnE4LU9wA6LM5lA1ztbBduM="
mimetype: "image/jpeg"
fileEncSHA256: "8wdTCF7kBugCQhneOg2YLsDye4Eqwu7N8kzyXKJXoIU="
fileSHA256: "Gc6NIzcYSI596Ke0Y0sO1VstRgq8FpAUzOglP06aYyE="
fileLength: 48213
caption: "Order photo"
height: 1280
width: 960
mediaKeyTimestamp: 1757862000
responses:
"200":
description: The image was downloaded and decrypted; `data.Data` holds the whole file as a data URL (truncated in this example).
content:
application/json:
schema:
$ref: "#/components/schemas/ChatDownloadMediaResponse"
example:
code: 200
data:
Mimetype: "image/jpeg"
Data: "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgyIRwhMjIyMjIyMjIyMjIy"
success: true
"400":
description: "Bad Request: the body is not valid JSON, or `MediaKey`/`FileEncSHA256`/`FileSHA256` is not valid base64."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 400
error: could not decode Payload
success: false
"401":
description: Missing or invalid user token (header `token` or query `token`).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
example:
code: 401
error: unauthorized
success: false
"500":
description: "Internal Server Error: no WhatsApp session, the per-user files directory could not be created, or the image download/decryption failed."
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
examples:
no_session:
summary: No WhatsApp session for this user
value:
code: 500
error: no session
success: false
no_url_present:
summary: DirectPath missing
value:
code: 500
error: failed to download image no url present
success: false
invalid_media_hmac:
summary: MediaKey does not match the file
value:
code: 500
error: failed to download image invalid media hmac
success: false
expired_link:
summary: CDN link expired
value:
code: 500
error: failed to download image download failed with status code 410
success: false
user_directory:
summary: Files directory could not be created
value:
code: 500
error: could not create user directory (/opt/zuckzapgo/files/user_3f2a9c1d)
success: false
/chat/downloadvideo:
post:
tags:
- Chat
summary: Download the video of a message
description: |
Downloads and decrypts the video of a received or sent message and returns the whole file inline as a base64 data URL, ready for an HTML `