| name | whatsapp-gateway |
| description | Operate a connected WhatsApp account through a self-hosted, authenticated, durable WhatsApp Gateway API. |
WhatsApp Gateway
Obtain the gateway base URL and a connection-scoped API key from the owner. Set them as WHATSAPP_GATEWAY_URL and WHATSAPP_GATEWAY_API_KEY. Never print, persist, commit, or transmit the key elsewhere.
Authenticate with X-API-Key: $WHATSAPP_GATEWAY_API_KEY.
Discover the contract
- Read
GET /v1/capabilities.md for the compact route map.
- Read
GET /openapi.json for all REST schemas.
- Read
GET /v1/baileys-actions for every managed WhatsApp action, exact Baileys method, ordered arguments, description, and permission.
- Read
GET /v1/mcp/manifest or connect to POST /mcp for agent-native Android and WhatsApp tools.
Workflow
- Call
GET /v1/accounts; a connection-scoped key should return exactly its assigned number.
- Resolve ambiguous recipients through chats, contacts, groups, and messages.
- Execute WhatsApp operations with
POST /v1/accounts/{accountId}/actions/{action} and {"args":[...]}.
- Retry safely with an
Idempotency-Key header.
- If the response is pending, poll
GET /v1/commands/{commandId}?wait_seconds=30 until completed or failed.
- Consume normalized state through
GET /v1/events or signed webhooks.
Owner-only API key routes are GET|POST /v1/api-keys and DELETE /v1/api-keys/{keyId}. Account and pairing routes are GET|POST /v1/accounts, GET /v1/accounts/{accountId}, GET /v1/accounts/{accountId}/status, POST /v1/accounts/{accountId}/pair/qr, POST /v1/accounts/{accountId}/pair/code, and DELETE /v1/accounts/{accountId}/session.
Native Android fleet routes are GET|POST /v1/android/instances, GET|DELETE /v1/android/instances/{instanceId}, GET /v1/android/instances/{instanceId}/status, POST /v1/android/instances/{instanceId}/actions, POST /v1/android/instances/{instanceId}/start, POST /v1/android/instances/{instanceId}/upgrade, and POST /v1/android/instances/{instanceId}/stop. Actions cover native WhatsApp send/open, notification retrieval, apps and URLs, clipboard/share, Appium UI selectors, proxy verification, screenshots, and bounded input. Provision from the clean pre-enrollment Platinum snapshot only. Never clone an enrolled Android instance.
Persisted state routes are GET /v1/accounts/{accountId}/chats, GET /v1/accounts/{accountId}/contacts, GET /v1/accounts/{accountId}/groups, GET /v1/accounts/{accountId}/messages, and GET /v1/events. Read GET /v1/chat.md (also shipped here as CHAT.md) before writing any message: it covers tone, WhatsApp's formatting rules (which are not Markdown), and how to behave in a chat.
Add q to GET /v1/accounts/{accountId}/messages to full-text search message text. To retrieve an attachment, call GET /v1/accounts/{accountId}/messages/{messageId}/media, which returns the decrypted image, video, audio, or document bytes with their original content-type (add ?download=1 to force a file download). To send a local file use POST /v1/accounts/{accountId}/messages/media (multipart/form-data with to and file). Message and chat conveniences are POST /v1/accounts/{accountId}/messages/{messageId}/reaction, POST /v1/accounts/{accountId}/messages/{messageId}/read, PATCH /v1/accounts/{accountId}/chats/{chatJid}, and POST /v1/accounts/{accountId}/presence. Durable control routes are GET /v1/baileys-actions, POST /v1/accounts/{accountId}/actions/{action}, and GET /v1/commands/{commandId}.
Convenience mutation aliases are POST /v1/accounts/{accountId}/messages, POST /v1/accounts/{accountId}/groups, PATCH /v1/accounts/{accountId}/groups/{groupId}, POST /v1/accounts/{accountId}/groups/{groupId}/participants, and DELETE /v1/accounts/{accountId}/groups/{groupId}/participants/{participantId}.
Webhook routes are GET /v1/webhook-event-types, GET|POST /v1/webhook-endpoints, GET|PATCH|DELETE /v1/webhook-endpoints/{endpointId}, POST /v1/webhook-endpoints/{endpointId}/rotate-secret, GET /v1/webhook-deliveries, GET /v1/webhook-deliveries/{deliveryId}, and POST /v1/webhook-deliveries/{deliveryId}/replay.
Webhook delivery list and detail responses include lastError, lastStatusCode,
lastResponse, attemptCount, and nextAttemptAt. Use these fields to report
the receiver's exact rejection or transport failure and the current retry state;
do not reduce a failed delivery to only retrying or failed.
Discovery routes are GET /v1/mcp/manifest, POST /mcp, GET /v1/skill.md, GET /v1/capabilities.md, GET /openapi.json, and GET /docs.
Ask before sending messages, creating groups, changing participants, or disconnecting unless explicitly requested. Never expose API keys, pairing QR codes, pairing codes, or webhook secrets.
