REST API documentation

Quick start

1. Create a workspace     →  https://console.whatsmcp.com/register
2. Link a WhatsApp number →  Console → Pair device (scan the QR with your phone)
                             …or, for a Business (official) number: Add a number → Connect with Facebook
3. Create an API key      →  https://console.whatsmcp.com/keys

Then:

curl -H "X-API-Key: $WAMCP_KEY" https://api.whatsmcp.com/v1/accounts

The REST API is the same workspace as the MCP server: the same accounts, the same plan, the same API keys. Use MCP for AI agents; use REST for scripts, backends, CRMs and anything else that speaks HTTP.

Base URL

https://api.whatsmcp.com

Every endpoint is under /v1. Requests and responses are JSON over HTTPS.

The contract is published as an OpenAPI 3.1 document, generated from the code that serves it, so it cannot drift:

In the interactive reference, Authorize with your key and every endpoint gets a Try it out button that calls your real workspace.

Authentication

Every /v1 request carries an API key, in either header:

curl -H "Authorization: Bearer $WAMCP_KEY" https://api.whatsmcp.com/v1/accounts
curl -H "X-API-Key: $WAMCP_KEY"            https://api.whatsmcp.com/v1/accounts

Create keys at Console → API keys. They look like wamcp_live_XXXXXXXXXXXX_… and are shown exactly once — we store only a hash, so a lost key is replaced, never recovered. Mint one key per service or environment and revoke individually.

The key is the workspace. There is no tenant parameter anywhere, and no request can reach another workspace’s accounts or messages.

A missing, unknown or revoked key — or a suspended workspace — is answered 401.

Accounts

GET /v1/accounts

The WhatsApp accounts in your workspace. Every per-account call needs an account_id from here, and a number can act only while its status is live (its state then reads connected).

curl -H "X-API-Key: $WAMCP_KEY" https://api.whatsmcp.com/v1/accounts

{
  "accounts": [
    {
      "account_id": "01J8Z3Q4R5S6T7V8W9X0Y1Z2A3",
      "phone": "447700900123",
      "push_name": "Support",
      "state": "connected",
      "status": "live",
      "country": "GB",
      "egress": "wireguard",
      "egress_configured": "wireguard",
      "egress_ip": "203.0.113.24"
    }
  ]
}

Fields that do not apply are omitted rather than sent empty.

Account status

status says whether a number is working right now, not just what its connection last reported. A call that needs the number’s WhatsApp connection (sending, editing, deleting or reacting to messages, presence, loading history, contacts, profiles, the blocklist) is refused at once on a number that is not working, with 409 account_not_connected (see Errors). Reads of stored messages keep working whatever the status.

A Business (official) number has no connection of its own to run, so its status follows its plan: suspended with billing or no_plan, otherwise live. This check never refuses its calls; the Cloud API’s own checks answer for it.

Plan, limits and usage

Messages

GET /v1/messages

Messages across all your accounts, oldest first, with a cursor.

curl -H "X-API-Key: $WAMCP_KEY" \
  "https://api.whatsmcp.com/v1/messages?after_cursor=1041&limit=100"

{
  "messages": [
    {
      "cursor": 1042,
      "account_id": "01J8Z3Q4R5S6T7V8W9X0Y1Z2A3",
      "direction": "inbound",
      "peer": "447700900456",
      "chat": "[email protected]",
      "chat_kind": "dm",
      "text": "Hi, is my order on its way?",
      "kind": "text",
      "at": "2026-09-25T09:14:03Z",
      "message_id": "3EB0C767D26A1D5F8C21"
    }
  ],
  "next_cursor": 1042,
  "has_more": false
}

Reading incoming messages

The API never pushes: you read on your own schedule, and the cursor is what makes that reliable — no gaps and no duplicates, even for two messages in the same millisecond, which a timestamp cannot promise.

after = 0                                   # or the cursor you stored last time
repeat:
    r = GET /v1/messages?after_cursor={after}&limit=200
    for m in r.messages:
        if m.direction == "inbound":
            handle(m)
    after = r.next_cursor                   # persist it — it is your bookmark
    if not r.has_more:
        sleep(a few seconds)                # caught up; poll again later

Store next_cursor durably and a restart resumes exactly where it stopped.

Webhook

If you would rather be called than poll, register a webhook: each inbound message is POSTed to your HTTPS endpoint as it arrives (paid plans). A workspace has one webhook, so the path carries no account.

curl -X PUT -H "X-API-Key: $WAMCP_KEY" -H "Content-Type: application/json" \
  https://api.whatsmcp.com/v1/webhook \
  -d '{"url":"https://example.com/whatsapp"}'

To stop deliveries for a while, PATCH rather than delete and re-create: re-creating issues a new secret. Messages keep arriving either way and stay readable with GET /v1/messages. The delivery payload, its headers and how to verify the signature are in Webhooks; the same webhook can be managed over MCP or in Console → Webhooks.

Sending and messaging

Per-account operations live under /v1/accounts/{account_id}/…, where {account_id} is one of the ids from GET /v1/accounts. Send a message:

curl -X POST -H "X-API-Key: $WAMCP_KEY" -H "Content-Type: application/json" \
  https://api.whatsmcp.com/v1/accounts/$ACCOUNT_ID/messages \
  -d '{"to":"447700900123","text":"Your order is on its way."}'

A send answers 200 when WhatsApp confirmed it ("status":"sent"), or 202 when it was accepted but not yet confirmed ("status":"queued") — queued messages may still arrive, so do not resend. A send to a number that is not working is refused before anything is sent: 409 account_not_connected, with the number’s account_status (see Account status). Nothing was queued, so sending again once the number is live cannot deliver it twice. Attach an image, document or audio clip as base64 (image_base64, document_base64, audio_base64); the text becomes the caption. For a Business (Cloud API) number, template sends a pre-approved template.

A {chat} or {message_id} path segment is URL-encoded as usual — a group JID [email protected] becomes 1203630%40g.us.

Contacts

Every per-account call is gated by the same plan rules as its MCP twin, resolves the account only within your workspace, and answers a refusal the same way (see Errors). The full request and response shape of each is in the interactive reference.

Business (official) numbers

The REST API serves Business (official) numbers — those on Meta’s WhatsApp Cloud API — through the same endpoints as Personal ones: list accounts, read messages, send. Each account in the accounts list carries its backend and features. What differs:

• Templates. List a number’s templates with their review status, submit a new one for Meta’s review, or delete one:

  Endpoint	Does
  GET /v1/accounts/{account_id}/templates	Every template with its status (APPROVED, PENDING, REJECTED + rejected_reason), language, category and variables count, plus call_permission: true on one that asks to allow calls
  POST /v1/accounts/{account_id}/templates	Submit a template (name, category MARKETING/UTILITY, body, body_examples, optional header, footer, buttons, or call_permission instead of buttons); answers 201 with "status":"PENDING"
  DELETE /v1/accounts/{account_id}/templates/{name}	Delete it — one language with ?language=pt_BR, or every language of the name

  curl -X POST -H "X-API-Key: $WAMCP_KEY" -H "Content-Type: application/json" \
    https://api.whatsmcp.com/v1/accounts/$ACCOUNT_ID/templates \
    -d '{"name":"order_update","category":"UTILITY",
         "body":"Hi {{1}}, order {{2}} is on its way.","body_examples":["Ada","#1042"]}'

  Meta reviews a new template, usually within minutes; poll the list until it is APPROVED, then send it with template, template_language and template_variables (one per variables, in order). A draft that breaks Meta’s rules is refused up front with a 400.

• The 24-hour window. Outside 24 hours from the customer’s last message, a free-form send to them is refused; only a template can reopen the conversation.

• Calls. A Business number takes WhatsApp calls on a line of its own. With Calls out on, the line also calls customers, from the Pipedrive call window or a phone on the line, once each customer has allowed your calls. Both are set up in the console, on the number’s SIP trunk page. Over REST you ask for the permission. Submit a template with "call_permission": true. Meta takes it on MARKETING and UTILITY templates only, never beside buttons, so a draft with both is refused with a 400:

  curl -X POST -H "X-API-Key: $WAMCP_KEY" -H "Content-Type: application/json" \
    https://api.whatsmcp.com/v1/accounts/$ACCOUNT_ID/templates \
    -d '{"name":"call_ok","category":"UTILITY","call_permission":true,
         "body":"Can we call you on WhatsApp about your order? You can change this any time."}'

  Once it is APPROVED, send it like any template; the customer sees Allow and Don’t allow under your text. Their answer arrives in GET /v1/messages as an inbound message of kind call_permission, whose text is one of Allowed calls (no expiry), Allowed calls until 23 Oct, Declined calls or Calls permission withdrawn automatically. A request sent from the Pipedrive call window is stored outbound with its own text. Call customers on WhatsApp from your Business number walks through the whole flow, with WhatsApp’s limits and what calls cost.

Errors

Errors are RFC 9457 problem documents, Content-Type: application/problem+json:

{
  "status": 403,
  "title": "Forbidden",
  "detail": "wa_list_messages is not included in your plan …",
  "reason": "plan_required"
}

reason is a stable code you can branch on; detail is for humans and may change. When waiting helps, retry_after_seconds is set and the response carries a Retry-After header — when it is absent, retrying the same call will not succeed.

A 409 account_not_connected names why in account_status and account_status_reason (the values of the number’s status and status_reason) and, when known, since:

{
  "status": 409,
  "title": "Conflict",
  "detail": "This number is not running because of a problem on our side, not anything you need to fix; try again later.",
  "reason": "account_not_connected",
  "retry_after_seconds": 60,
  "account_status": "not_running",
  "account_status_reason": "stopped",
  "since": "2026-10-10T19:38:03Z"
}

Without retry_after_seconds, waiting will not bring the number back: its owner has to act, and detail says how.

Each endpoint is gated by your plan exactly as its MCP twin is: GET /v1/messages needs what wa_list_messages needs, and so on.

What’s available

The REST API grows toward full parity with the MCP server — the same workspace and the same key. Everything not yet on REST is available today through MCP, and each new endpoint appears in the OpenAPI spec the moment it ships.