Build on whasp

claude mcp add --transport http --scope user \
  whasp https://api.whasp.ai/mcp \
  --header "Authorization: Bearer $WHASP_API_KEY"

{
  "mcpServers": {
    "whasp": {
      "url": "https://api.whasp.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${env:WHASP_API_KEY}"
      }
    }
  }
}

[mcp_servers.whasp]
url = "https://api.whasp.ai/mcp"
bearer_token_env_var = "WHASP_API_KEY"

{
  "mcpServers": {
    "whasp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.whasp.ai/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer wsk_..."
      }
    }
  }
}

{
  "mcpServers": {
    "whasp": {
      "type": "http",
      "url": "https://api.whasp.ai/mcp",
      "headers": {
        "Authorization": "Bearer wsk_..."
      }
    }
  }
}

{
  "mcpServers": {
    "whasp": {
      "type": "http",
      "url": "https://api.whasp.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${WHASP_API_KEY}"
      }
    }
  }
}

codex mcp add whasp --url https://api.whasp.ai/mcp --bearer-token-env-var WHASP_API_KEY

curl -s https://api.whasp.ai/mcp \
  -H "Authorization: Bearer $WHASP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Add an MCP server named "whasp": streamable HTTP at https://api.whasp.ai/mcp, header "Authorization: Bearer <the value of WHASP_API_KEY>". Keep the key in the environment, not in a file I commit. Then call list_numbers and show me the result.

Base URL https://api.whasp.ai/v1 (also served as https://whasp.ai/v1, the dashboard’s origin). JSON in, JSON out. Times are ISO 8601 (UTC), money is integer cents (USD), phone numbers are E.164 (+15555550100). MCP at https://api.whasp.ai/mcp (see MCP).

Auth

Authorization: Bearer wsk_.... Keys are created and revoked in the dashboard, shown once, at most 10 active. A key carries scopes, all of them unless chosen: numbers:read (numbers, chats, message status), numbers:manage (buy, change, cancel), messages:send. The dashboard calls the same routes with its session cookie, which may do everything.

Errors

{ "error": { "code": "chat_not_open", "message": "+15555550111 has not written to any of your numbers yet." } }

Numbers

Each number is a real personal WhatsApp account on its own Android cloud phone, with its own US mobile number and its own IP. $49 per 30 days, taken from the prepaid balance; renews by itself while the balance covers it (3 days of grace when it does not).

Number object

{
  "id": "num_3fK9xQ2LmP8rT1vZ0aBc",
  "number": "+15555550100",
  "wa_link": "https://wa.me/15555550100",
  "label": "support-1",
  "status": "active",
  "health": "healthy",
  "health_reason": null,
  "online": true,
  "profile": { "name": "Ava", "about": "Your AI friend", "photo_url": "https://...", "synced": true },
  "stats": { "active_chats_30d": 64, "new_chats_24h": 3, "outbound_24h": 412 },
  "limits": { "active_chats_30d": 100, "new_chats_24h": 40, "outbound_24h": 1500 },
  "paid_until": "2026-11-17T19:00:00.000Z",
  "auto_renew": true,
  "replaced_by": null,
  "created_at": "2026-10-18T19:00:00.000Z"
}

• id: stable from the moment you buy. number and wa_link are null while the number is being set up and has no phone number yet.
• status: provisioning (being set up for you, about 30 min), active, retired.
• health: healthy, at_risk (WhatsApp warning, temporary ban, or a limit above 80%), critical (banned, logged out, phone offline over 10 min, the phone’s network down, sends failing). health_reason says why in plain words. While the phone’s network is down, or once the phone is flagged offline, new sends get 409 number_unavailable; queued ones wait up to 10 minutes and go out once it is back, or fail with message.failed.
• replaced_by: after a ban, the number that took over.

{number} in a path is the E.164 or the id.

Messages

End users always write first. A number can answer anyone who wrote to it; it cannot open a chat cold (409 chat_not_open), because that is what gets personal numbers banned. This holds for every number, a replacement after a ban included.

whasp’s servers keep no message content. We send and receive; your system keeps the history. The text and file of a message you send stay on our servers only while it waits in the queue or is being sent. An inbound message’s content reaches you once, in message.received, and is not stored; its file is deleted after 24 hours. A webhook event keeps its body only until it is delivered or given up. Message objects carry ids, status and times, never content, and there is no endpoint to read a conversation back. WhatsApp itself, like on any phone, keeps the chats on the number’s phone while the number lives; the phone and everything on it are wiped when the number ends.

Message object

{
  "id": "msg_3fK9xQ2LmP8rT1vZ0aBc_8fK2...",
  "number": "+15555550100",
  "chat": "+15555550111",
  "direction": "outbound",
  "status": "sent",
  "error": null,
  "created_at": "2026-10-18T19:01:00.000Z",
  "sent_at": "2026-10-18T19:01:02.000Z"
}

Outbound status: queued, sent, failed. Inbound: received. Ids are opaque.

Inbound content, only in message.received: the Message object plus text and media, and when present location, contacts, reply_to, sender_name. media is { "url", "mime", "filename", "size" }: a signed link valid 24 hours, the file deleted after 24 hours, so copy it if you need it (a file over 30 MB arrives without it, media null; pictures, audio and MP4 open in the browser, other files download). location is { "latitude", "longitude", "name", "address", "live" }, contacts vCards as strings, reply_to { "id", "text" } (the quoted message: id null when we do not know it), and sender_name the name they gave themselves on WhatsApp.

Chat object: { "phone", "name", "opted_out", "last_message_at", "last_inbound_at", "first_inbound_at" }; name is the end user’s WhatsApp name, null until we know it.

Opt-out. An inbound message that is exactly STOP, UNSUBSCRIBE, OPTOUT, CANCEL, END or QUIT (case sensitive), or any spelling of opt out, opts the chat out: sends to it get 403 chat_opted_out, and messages to it still in the queue are not sent either: they fail with message.failed, error chat_opted_out. One send with "override_optout": true goes through anyway (for “You are unsubscribed, write any time”), also when it was already queued. The block lifts as soon as the end user writes again. Polite requests (“please stop”) are yours to catch.

Not supported (WhatsApp on a phone, driven like a person): typing indicators, read receipts, outbound reactions, replying to a specific message, groups, status, voice notes (an audio file arrives as a file).

MCP

POST https://api.whasp.ai/mcp, Streamable HTTP, Authorization: Bearer wsk_.... The same API as tools, with the same answers and errors as REST (an error is the REST error body, as a tool error). A key sees only the tools its scopes allow.

Webhook

One HTTPS endpoint per account, set in the dashboard (these routes take the session only, so a leaked key cannot redirect your events).

Delivery. POST with the event as JSON body, signed per Standard Webhooks (the official standardwebhooks libraries verify it): headers webhook-id (the event id), webhook-timestamp (unix seconds) and webhook-signature: v1,<base64 HMAC-SHA256 of "<id>.<timestamp>.<raw body>">, keyed with the secret (whsec_ and a base64 key); for 24 hours after a rotation the header carries a signature with each secret, space-separated. Any 2xx within 10 s is a success. Otherwise we retry with backoff (30 s, 2 min, 10 min, 30 min, 1 h, 2 h, 4 h, 8 h, 8 h: about a day) up to 10 attempts, then mark it failed. Without a webhook URL an event is only listed, as no_endpoint, and never sent. Order is not guaranteed and an event can arrive twice: dedupe on id. Every event about a message or a number is recorded with the change it tells, or retried until it is, under the same id. Reject signatures older than 5 minutes.

Envelope

{ "id": "evt_...", "type": "message.received", "created_at": "2026-10-18T19:00:00.000Z", "data": { } }

Bans and lost phones. When WhatsApp bans a number for good, or fleet reports that its ready phone was lost, we retire it and move you to a ready number at no cost, same label and profile, same paid_until and auto_renew (it takes over the old number’s subscription). The new number starts empty: no chats move, and like any number it cannot write first (409 chat_not_open). Your own logic moves your end users, for example by sending them the new number’s wa_link in your app or by email; each chat opens when they write to it. Once they do, sends without from go out from the new number. When no number is ready we set one up for you (about 30 minutes, then number.replaced); meanwhile the banned number shows retired with the subscription’s real auto_renew, and DELETE on it cancels the renewal.

A lost phone is detected by the five-minute health check and retires with reason its phone was lost. It uses the same replacement and subscription described above. An expired number rental alone remains a warning: it does not replace a working WhatsApp account.

Account and billing

Lists (/webhook/deliveries, /billing/orders, /billing/ledger, chats) are newest first, take limit (1 to 100, default 50) and before, and return next_before (null on the last page). For the next page pass the next_before of the previous one as before, as it is: it is opaque.

Sign in (dashboard)

On https://whasp.ai/auth, cookie-based, no API key.

Limits