# Whatsapp Gateway

> Operate a connected WhatsApp account through a self-hosted, authenticated, durable WhatsApp Gateway API.

- Skill: `kortix-ai/whatsapp-gateway` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add kortix-ai/whatsapp-gateway`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kortix-ai/whatsapp-gateway/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: kortix-ai (https://skillmd.com/u/kortix-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kortix-ai/whatsapp-gateway

---


# 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

1. Read `GET /v1/capabilities.md` for the compact route map.
2. Read `GET /openapi.json` for all REST schemas.
3. Read `GET /v1/baileys-actions` for every managed WhatsApp action, exact Baileys method, ordered arguments, description, and permission.
4. Read `GET /v1/mcp/manifest` or connect to `POST /mcp` for agent-native Android and WhatsApp tools.

## Workflow

1. Call `GET /v1/accounts`; a connection-scoped key should return exactly its assigned number.
2. Resolve ambiguous recipients through chats, contacts, groups, and messages.
3. Execute WhatsApp operations with `POST /v1/accounts/{accountId}/actions/{action}` and `{"args":[...]}`.
4. Retry safely with an `Idempotency-Key` header.
5. If the response is pending, poll `GET /v1/commands/{commandId}?wait_seconds=30` until completed or failed.
6. 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.