Docs

Quickstart

Four steps from nothing to a sent message. Each is covered in detail further down.

1. Create an account at wuapi.dev. You start on the Free plan, with no card: 1 number, 2,000 messages and 0.5 GB of proxy traffic a month, with sending and webhooks included. Upgrade under Billing to connect more numbers.
2. Every organization starts with a default API key, shown on the Overview. Copy it, or create another under API keys, and store it as WUAPI_API_KEY.
3. Connect an account: open Accounts, choose Connect account, pick the country and city the number exits from, and scan the QR code with WhatsApp on the phone (Settings, Linked devices, Link a device), or link with a pairing code instead. Copy the account ID when it reports ready.
4. Send a message with curl, or with the TypeScript SDK after npm install @wuapidev/sdk.

curl https://api.wuapi.dev/v1/messages \
  -H "Authorization: Bearer wu_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-4417-shipped" \
  -d '{
    "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
    "to": "+584241112233",
    "type": "text",
    "text": "Your order has shipped."
  }'

The response is 202 with the message in queued status. It moves to sent when WhatsApp accepts it, then delivered and read as receipts arrive. Register a webhook endpoint to be told about each change instead of polling. The Idempotency-Key header makes the send safe to retry: the same key within 24 hours returns the first response instead of sending twice.

Authentication

Every request goes to https://api.wuapi.dev and carries an API key as a bearer token. Keys start with wu_live_.

curl https://api.wuapi.dev/v1/me \
  -H "Authorization: Bearer wu_live_..."

{
  "object": "auth_context",
  "organization": {
    "object": "organization",
    "id": "w82t6y1u5i9o3p7a2s6d0f4g8h2j6k1l",
    "name": "Acme"
  },
  "apiKey": {
    "object": "api_key",
    "id": "j48c2d5e8f1g4h7i0k3l6m9n2p5q8r1s",
    "name": "Production",
    "projectId": null,
    "keyPrefix": "wu_live_ab12",
    "last4": "9f3c",
    "createdAt": "2026-09-20T09:00:00.000Z",
    "lastUsedAt": "2026-09-24T14:00:00.000Z",
    "revokedAt": null
  },
  "project": null
}

GET /v1/me returns the organization, the key the request was made with (apiKey.projectId is set for a project key) and project, the project the request is scoped to, or null. Requests are checked against a SHA-256 hash of the key. The API returns a full key only when it creates one; the dashboard can show it again to the organization's owner, from an AES-256-GCM encrypted copy. Revoke a key and it stops working on the next request.

Keep keys on your server. An organization key can send from every connected account in the organization. A project key reaches only its project: see Projects.

Conventions

The whole API follows the same rules. Learn them once.

Resources and lists

Every response body is a resource or a list. A resource is returned as is, never wrapped, and its object field names its type: account, message, group, channel, project, invitation, webhook_endpoint, and so on. Every list has the same shape:

{
  "object": "list",
  "items": [
    {
      "object": "account",
      "id": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
      "...": "..."
    }
  ],
  "nextCursor": "eyJvIjo1MH0"
}

Lists take ?limit (1 to 100, default 50) and ?cursor. Pass nextCursor back as cursor until it is null. Lists read live from WhatsApp (groups, channels, blocklist, bots) page the same way. Creating returns 201 with the resource, updating 200, deleting 204. Sends are queued and return 202.

Names and values

1. Fields are camelCase. Enum values are lowercase snake_case: qr_ready, pairing_code.
2. A resource's own id is id; a reference to another is <resource>Id: accountId, projectId, contactId, replyToMessageId.
3. Timestamps are ISO 8601 strings in UTC and end in At: createdAt, sentAt, expiresAt.
4. Durations and sizes carry the unit: durationSeconds, queueTimeoutMinutes, proxyBytes. Money is integer cents in …Cents, next to currency.
5. Counts end in Count, URLs in Url, and a name WhatsApp reported is profileName.

WhatsApp identities

A message's chatId is the contact for a direct chat, the group id, the channel id, or stories, and chatType says which: direct, group, channel or story. Wherever you pass a chat or a contact (to, {chatId}, {contactId}, contactIds), any format in the table works, and a number may also be plain digits.

WhatsApp usernames

A WhatsApp user can pick a username (@lina.morales) and hide their number. A chat they start from their username reaches you as lid:<digits>, never as a number, and their messages carry username (lowercase, without the @) next to profileName when WhatsApp shared it. contacts/lookup and contacts/check return it as username too, and contact.updated fires when it becomes known or changes. Reply with the lid: id, or with to: "@lina.morales", which works for a contact this account already has a chat with. WhatsApp does not let a linked device look up any other username (nor take the 4-digit username key a first message by username needs), so an unknown one answers 400 username_not_supported, and fields that take contact ids refuse usernames the same way.

Errors

Every error is {code, message, details?}, with the same code for the same situation everywhere. Branch on code. The full list is in Errors.

Headers

Coding agents

Two ways to give a coding agent what it needs to write wuapi code. The Markdown is a one-off paste into any agent. The skills are installed once, and the agent loads the one a task needs.

The docs as one Markdown file

https://wuapi.dev/llms-full.txt holds every section of these docs, every endpoint of openapi.json with its error codes, and every webhook event with its payload. It is rebuilt on every deploy. /llms.txt is a short index of it. Copy it from the home page or the dashboard Overview, which put a short preamble in front telling the agent what it is reading.

Skills

npx skills add wuapidev/wuapi

The skills live in the public repository wuapidev/wuapi, one SKILL.md per task, for agents that read skills, such as Claude Code. Each one is a workflow plus a reference, with TypeScript examples that use the real SDK and curl where it helps. wuapi-rules is meant to be loaded always; the others load when relevant.

Every skill is checked against the code before it ships: the webhook events it names exist, the paths it names are in openapi.json, and its TypeScript examples compile against the SDK.

To let an AI client act on your account instead of writing code for it, connect the MCP server: wuapi.dev/docs/mcp.

MCP server

The wuapi MCP server gives an AI client that speaks the Model Context Protocol, such as Claude, Cursor or VS Code, 51 tools over your wuapi account: send a message, show the QR code that links a number, read a conversation, add people to a group, set up a webhook, invite a customer. Each tool call is one request to the REST API with your API key, so the key's scope, the limit of 600 requests per minute per key and the dashboard Logs apply as for any other client.

Connect a client

Create a key under API keys in the dashboard. A project key limits the server to one project. Then add the server to your client:

# Local: runs on your machine
claude mcp add wuapi --env WUAPI_API_KEY=wu_live_... -- npx -y @wuapidev/mcp

# Hosted: nothing to install
claude mcp add --transport http wuapi https://wuapi.dev/api/mcp --header "Authorization: Bearer $WUAPI_API_KEY"

The dashboard's MCP server screen (/app/mcp) builds these for you from one of your keys, with read-only and a project as options, one-click install links for Cursor and VS Code and a connection test. Claude Desktop reads claude_desktop_config.json (Settings, Developer, Edit Config). Cursor reads ~/.cursor/mcp.json, or .cursor/mcp.json in a project. VS Code reads .vscode/mcp.json and asks for the key once, so it stays out of the file. Any other client that starts a local command works with the stdio server and WUAPI_API_KEY in its environment; any client that sends a custom header works with the hosted one. Clients that reach remote servers only through OAuth, as some chat apps do, cannot use the hosted endpoint yet.

Configuration

Tools

Every tool declares a JSON schema for its input and returns the API's own object as structured content, without nulls. Tools that read carry readOnlyHint. Tools that delete, revoke, cancel or leave carry destructiveHint and take confirm: true, which the model has to set on purpose and your client shows you before the call: delete_message, cancel_message, remove_group_participants, reset_group_invite_link, leave_group, delete_webhook, cancel_invitation. Sends take an optional idempotencyKey, so a retried call does not send twice. get_account_qr_code returns the QR code as an image the client can show.

Projects, invitations and usage need an organization key. Listing chats, sending a test webhook event and reading the request log have no public endpoint, so they are not tools; they are in the dashboard.

Resources and prompts

Resources a client can attach to the conversation: https://wuapi.dev/openapi.json, https://wuapi.dev/llms-full.txt, https://wuapi.dev/llms.txt and wuapi://webhook-events. Prompts, which Claude Code lists as slash commands: send_message (to, message), setup_webhook (url, events) and invite_customer (customer, externalId, email).

Examples

Security

1. The key stays in your client's configuration or header. The server never logs it, never returns it and never puts it in an error. The hosted endpoint stores nothing: it checks the key with GET /v1/me when a client connects, then passes it to the API on each call.
2. Tool results carry no secrets. A webhook endpoint's signing secret is returned by the API only when the endpoint is created; create_webhook drops it and tells you to reveal it in the dashboard. No tool creates API keys.
3. Narrow what the model can do: a project key reaches one project, and read-only mode removes every tool that writes.
4. Media URLs are downloaded by the API, which refuses private and internal addresses; the MCP server fetches nothing on a tool's behalf.
5. Every argument is checked against the tool's schema before any request. A base URL that is not https is refused, so the key never travels in clear text.
6. A model can be steered by what it reads, including inbound messages. Keep your client's confirmation prompts on for tools that send or delete.

The source is the npm package @wuapidev/mcp (MIT), built on the TypeScript SDK. It also exports createWuapiMcpServer and a stateless HTTP handler, createWuapiMcpHttpHandler from @wuapidev/mcp/http, to host it yourself.

Accounts and QR linking

An account is one WhatsApp number linked to wuapi as a linked device, the same way WhatsApp Web links to a phone. Link it by scanning a QR code, or by typing a pairing code on the phone (next section).

curl -X POST https://api.wuapi.dev/v1/accounts \
  -H "Authorization: Bearer wu_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Support line","proxyLocation":{"country":"VE","city":"caracas"}}'

proxyLocation is required: where the account's residential proxy exits (see the next heading). The call returns 201 with the account in initializing. Poll GET /v1/accounts/{accountId}, or listen for account.qr_code_issued, until status is qr_ready: qrCodeUrl then holds a PNG data URL you can put straight into an <img>. The QR code rotates while it waits; always show the latest one. An organization on the Free plan (no paid subscription, no card) connects 1 account and uses it fully: sends, webhooks, groups and every other call. A second one answers 402 upgrade_required until the organization upgrades in Billing. On Free, an account that has not linked within 15 minutes stops its session (link_timeout).

Choose where the number exits

Every account connects through a residential proxy with a sticky exit in the place you choose, so a number keeps a consistent network identity. Pick it from GET /v1/proxy-locations and pass its country and city as proxyLocation when you create the account. Filter with ?country= (an ISO 3166-1 alpha-2 code), or search with ?q=: it matches the city name, the city code, the country name and the ISO code, ignores case and accents, and puts exact and prefix matches first, so q=bogo finds Bogotá and q=sao finds São Paulo. Browse the whole list, no key needed, at wuapi.dev/proxy-locations. Choose where the number's owner actually is. A missing proxyLocation answers 400 invalid_request; a pair that is not in the list answers 400 unsupported_proxy_location. The account shows it back as proxyLocation.

The city is preferred by default: if no residential IP is free in that city when the number needs a new exit, it may get an exit in another city of the same country instead of staying offline, and it stays on that exit while the exit is healthy. Set proxyLocation.strictCity: true to require the exact city instead; the number may then stay offline longer while no IP is free there. The country is always exact. Change either later with PATCH /v1/accounts/{accountId} and proxyLocation ({country, city}, {strictCity}, or both): like any location change, the number gets a new exit IP and reconnects, and WhatsApp may ask the phone to confirm the link again. A connected number changes location at most once every 10 minutes; earlier, the PATCH answers 429 rate_limited with Retry-After.

curl -X PATCH https://api.wuapi.dev/v1/accounts/{accountId} \
  -H "Authorization: Bearer wu_live_..." \
  -H "Content-Type: application/json" \
  -d '{"proxyLocation":{"strictCity":true}}'

curl https://api.wuapi.dev/v1/proxy-locations?q=bogo \
  -H "Authorization: Bearer wu_live_..."

Status

These disconnectReason values do not reconnect automatically: logged_out (the device was removed from the phone), connection_replaced, temporary_ban and client_outdated. On the Free plan there are two more: link_timeout (not linked within 15 minutes; reconnect for a new QR code) and free_limit_reached (the month's Free limit was reached; the device stays linked and the account reconnects on its own when the month ends, UTC, or when the organization upgrades, with no new QR code). While proxy traffic is paused for an unpaid invoice or the monthly proxy spend cap, running accounts show proxy_paused and reconnect on their own when the pause lifts. After qr_timeout or logged_out, call POST /v1/accounts/{accountId}/reconnect to get a fresh QR code.

reconnecting is true while an account that was ready is reconnecting on its own (status disconnected, initializing or authenticating) within the offline tolerance (currently 3 minutes): messages you send meanwhile wait for it. It is false when the account is ready, when it is down for a reason it does not recover from, and once the tolerance runs out.

Other operations

Proxy traffic is metered per account. Each billable account includes 0.5 GB a month, pooled across the organization; past that it is billed at $0.99 per GB, on the next invoice or sooner, each time the overage not yet invoiced reaches $10.

An organization without a paid subscription is on the Free plan: 1 number, 2,000 messages and 0.5 GB of proxy traffic a month, no card. Messages count sent and received together, and the month is the calendar month in UTC. When either limit is reached the organization's accounts pause (status: disconnected, disconnectReason: free_limit_reached, the device stays linked), and sends, new accounts and reconnects answer 402 free_limit_reached. They reconnect on their own when the month ends, or at once when the organization upgrades in Billing. A count lands once WhatsApp accepts a send, so a burst sent right at the limit can pass it by a few messages.

Proxy spending has two stops. Each organization has a monthly cap on proxy overage ($50 unless an owner or admin changes it in Billing; $0 allows none): at the cap, proxy traffic pauses until the cap is raised or the month ends (UTC). While an invoice is unpaid, it pauses until the invoice is paid. During a pause every running account shows status: disconnected with disconnectReason: proxy_paused (the device stays linked, and account.disconnected fires), sends, stories, new accounts and reconnects answer 402 payment_required or 402 proxy_spend_cap_reached, and messages already queued wait up to 24 hours for the pause to lift, then fail with that code. When it lifts, the accounts reconnect on their own with no new QR code and what waited is sent.

Linking with a pairing code

When the person linking cannot scan a QR code, for example because wuapi runs on the same phone they would scan with, link with an 8-character code instead. On the phone: Settings, Linked devices, Link a device, Link with phone number instead, then type the code.

curl -X POST https://api.wuapi.dev/v1/accounts \
  -H "Authorization: Bearer wu_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Support line","proxyLocation":{"country":"VE","city":"caracas"},"pairingPhone":"+584121234567"}'

phone is the number being linked, in E.164 or digits. With pairingPhone on create, wuapi requests the code once the session is up and exposes it as pairingCode (and pairingCodeExpiresAt) on the account instead of qrCodeUrl, and fires account.pairing_code_issued. POST .../pairing-code returns 201 with the code directly. A code lives about 160 seconds, WhatsApp's own lifetime for it; ask for a new one after it expires. Asking for a code on an account that is already ready answers 409 already_linked.

Sending messages

POST /v1/messages sends one message from one account to a contact, a group or a channel. The account must be ready. An account that dropped from ready for a reconnect less than the offline tolerance ago (currently 3 minutes) still takes the message: it waits for the account and is sent once the account is back, or fails with account_offline if the account is not back within the tolerance or goes down for good.

The body is one of twelve shapes, chosen by type. Each type requires its own field; the fields in the first table work with every type.

Send an Idempotency-Key header with every send you might retry. The same key within 24 hours returns the original response, with Idempotent-Replayed: true, instead of a second message.

curl https://api.wuapi.dev/v1/messages \
  -H "Authorization: Bearer wu_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
    "to": "+584241112233",
    "type": "image",
    "text": "Invoice attached",
    "media": {
      "url": "https://example.com/invoice.png",
      "mimeType": "image/png"
    }
  }'

{
  "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
  "to": "+584241112233",
  "type": "location",
  "location": {
    "latitude": 10.4806,
    "longitude": -66.9036,
    "name": "Office"
  }
}

Polls, calendar events and the other types

{
  "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
  "to": "120363041234567890@g.us",
  "type": "poll",
  "poll": {
    "name": "Team dinner?",
    "options": [
      "Thursday",
      "Friday"
    ],
    "selectableCount": 1
  }
}

{
  "object": "message",
  "id": "j97d2k1x8p3m4q5w6e7r8t9y0u1i2o3p",
  "projectId": null,
  "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
  "chatId": "+584241112233",
  "chatType": "direct",
  "direction": "outbound",
  "source": "api",
  "from": "+584121234567",
  "to": "+584241112233",
  "profileName": null,
  "username": null,
  "type": "text",
  "text": "Your order has shipped.",
  "media": null,
  "location": null,
  "contact": null,
  "contacts": null,
  "poll": null,
  "calendarEvent": null,
  "mentions": [],
  "forwarded": false,
  "viewOnce": false,
  "starred": false,
  "replyToMessageId": null,
  "status": "queued",
  "error": null,
  "metadata": {
    "orderId": "4417"
  },
  "sentAt": null,
  "editedAt": null,
  "deletedAt": null,
  "createdAt": "2026-09-24T14:02:11.000Z",
  "updatedAt": "2026-09-24T14:02:11.000Z"
}

1. type: "voice" sends an audio as a voice note. We do not transcode: send ogg/opus.
2. calendarEvent.callType (audio or video) marks the event as a scheduled WhatsApp call. The call link itself is created by WhatsApp on the phone, so joinUrl stays null on events you send.
3. A poll's votes arrive as poll.voted webhooks, and the stored poll keeps the tally in poll.options[].voteCount.

The send returns 202 with the message queued. Each number sends one message at a time, in the order they reach its queue; an account that turned its pacing on holds a burst in the queue and sends it at that pace (see Sending safely). A message ends failed with error.code not_on_whatsapp when the recipient has no WhatsApp, rate_limited when, with a pacing cap on, it waited in the queue past the account's pacing.queueTimeoutMinutes (an hour by default) without a free slot, account_offline when the account stayed offline past the offline tolerance (or went down for good) while the message waited, payment_required or proxy_spend_cap_reached when it was queued before proxy traffic paused and the pause lasted more than 24 hours, cancelled when you deleted it before it was sent, or send_failed for other errors. A connection that drops while a message is being sent does not fail it: the message waits for the account and is sent again with the same WhatsApp message id, so it is never delivered twice.

media.url must be a public http or https URL that answers with the file itself: our servers download it once, following up to 5 redirects, within 60 seconds and up to 100 MB, as wuapi-media-fetcher/1.0 (+https://wuapi.dev). Private and internal addresses are refused, and hosts with hotlink protection or bot filters may refuse the download. A download that fails ends the message failed with send_failed and a message that names the host and its answer, for example fetch media from upload.wikimedia.org: HTTP 403. When a site refuses, host the file on storage you control.

There are no message templates, buttons or list messages to send. Those are features of the official WhatsApp Business Platform.

Reading, editing and deleting

curl -X PATCH https://api.wuapi.dev/v1/messages/j97d2k1x8p3m4q5w6e7r8t9y0u1i2o3p \
  -H "Authorization: Bearer wu_live_..." \
  -H "Content-Type: application/json" \
  -d '{"text":"Your order ships tomorrow, not today."}'

Edits and poll votes are messages in WhatsApp's eyes, so they go through the same pacing as a send. Vote options are checked against the stored poll: an unknown name, a repeated one, or more than selectableCount answers 400. Deletions and edits made by the other side arrive as message.deleted and message.edited; the stored row is kept, with deletedAt or editedAt set.

Delete for me is not available. WhatsApp's libraries only read that change; they cannot write it. Delete for everyone works.

Chats

Chat state is synced across the phone and every linked device, so these changes show up on the phone too. {chatId} is a contact, a group id or a channel id. Each action returns 204.

curl -X POST https://api.wuapi.dev/v1/accounts/k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr/chats/+584241112233/mute \
  -H "Authorization: Bearer wu_live_..." \
  -H "Content-Type: application/json" \
  -d '{"durationSeconds":28800}'

Changes made on the phone arrive as chat.updated, and a contact typing arrives as chat.presence_updated. Changes replayed by the full sync right after linking are not sent: that would be thousands of events describing the past.

Stories

Post a story (a WhatsApp Status) from an account. It is queued and paced like a send and stored as a message with chatId stories and chatType story.

curl -X POST https://api.wuapi.dev/v1/accounts/k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr/stories \
  -H "Authorization: Bearer wu_live_..." \
  -H "Content-Type: application/json" \
  -d '{"type":"text","text":"Closed today for inventory.","backgroundColor":"#1F2937","font":1}'

type is text, image or video. backgroundColor is #RRGGBB and font one of 0, 1, 2, 6, 7, 8, 9 or 10, WhatsApp's own values. Idempotency-Key works as on a send. Returns 202 with the message. Who sees the story follows the account's story privacy: read it with GET .../privacy/stories.

Posting only. Your contacts' stories are not received.

Contacts

curl -X POST https://api.wuapi.dev/v1/accounts/k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr/contacts/check \
  -H "Authorization: Bearer wu_live_..." \
  -H "Content-Type: application/json" \
  -d '{"phones":["+584241112233","+584141234567"]}'

Checking a number, looking up contacts and resolving a link only read, so they keep working for a suspended project. Changes to a contact's about text, username and picture arrive as contact.updated and contact.picture_updated. username is the contact's WhatsApp username when this account knows it; a check never asks WhatsApp for it, a lookup does.

Profile and privacy

curl -X PATCH https://api.wuapi.dev/v1/accounts/k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr/privacy \
  -H "Authorization: Bearer wu_live_..." \
  -H "Content-Type: application/json" \
  -d '{"readReceipts":"none"}'

Each setting is one change on WhatsApp, so a PATCH with several settings takes a moment longer than one with a single setting.

Groups

Group operations run live against WhatsApp through the account, so the account must be ready. Group IDs end in @g.us; use one as to to send to the group.

curl -X POST https://api.wuapi.dev/v1/accounts/k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr/groups/120363041234567890@g.us/participants/add \
  -H "Authorization: Bearer wu_live_..." \
  -H "Content-Type: application/json" \
  -d '{"contactIds":["+584241112233"]}'

When a contact cannot be added directly because of their privacy settings, the result carries an inviteCode you can send them instead. Membership and setting changes arrive as group.updated, join requests as group.join_requested and group.join_request_revoked.

Communities

A community is a group that holds other groups, its subgroups. Create one with community: true on the groups endpoint; participants may then be empty. It comes back with community: true.

curl -X POST https://api.wuapi.dev/v1/accounts/k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr/groups \
  -H "Authorization: Bearer wu_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Riverside projects","community":true}'

Channels

WhatsApp channels are one-way broadcasts. Channel IDs end in @newsletter. Read, follow and react with any account; post to a channel the account administers with POST /v1/messages and to set to the channel id.

curl -X POST https://api.wuapi.dev/v1/messages \
  -H "Authorization: Bearer wu_live_..." \
  -H "Content-Type: application/json" \
  -d '{"accountId":"k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr","to":"120363198765432109@newsletter","type":"text","text":"Doors open at 8."}'

New posts in followed channels arrive as channel.message_received and new view and reaction counts as channel.message_updated; neither is stored. Follow, unfollow and mute changes arrive as channel.updated.

Calls

wuapi does not answer or place calls. It tells you about them and can turn them down. An incoming call fires call.received; when it ends, call.ended. Both carry a call object.

curl -X PATCH https://api.wuapi.dev/v1/accounts/k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr \
  -H "Authorization: Bearer wu_live_..." \
  -H "Content-Type: application/json" \
  -d '{"rejectCalls":true,"rejectCallsMessage":"We do not take calls on this number. Write to us here."}'

With rejectCalls: true every incoming call is rejected as it rings, and rejectCallsMessage, up to 1,000 characters, is sent to the caller. The reply goes through the account's pacing and is skipped for group calls. To reject one call yourself, pass the id and from of the call in call.received.

Labels

Labels exist only on WhatsApp Business. On a number linked from the consumer app these routes answer 400 not_supported.

curl -X PUT https://api.wuapi.dev/v1/accounts/k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr/labels/3 \
  -H "Authorization: Bearer wu_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Paid","color":5}'

There is no endpoint that lists labels. After linking, WhatsApp sends the existing labels, and every later change, as label.updated events: keep your own copy from those.

History sync

Right after a number links, WhatsApp sends the linked device part of the chat history, the same way WhatsApp Web fills in old chats. History import is off by default: an account stores only the messages sent and received after it links. Turn it on per account with historySync: "recent" on POST /v1/accounts (or PATCH before the number links, or the checkbox in the dashboard). wuapi then stores that history as messages with source history, so GET /v1/messages?accountId=...&chatId=... returns old conversations as well as new ones.

curl -X POST https://api.wuapi.dev/v1/accounts \
  -H "Authorization: Bearer wu_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Support line","proxyLocation":{"country":"VE","city":"caracas"},"historySync":"recent"}'

1. WhatsApp sends history once, right after linking. Changing historySync applies to the next link: a number that is already linked gets no history, not even after a reconnect.
2. With historySync none nothing is stored and history.synced never fires. Contact names and live messages work the same either way.
3. Invitations take historySync too; the account the invitee links gets it. It is none unless you set it.
4. History arrives in pushes of at most 500 messages. Each push fires one history.synced with counts, never one webhook per message.
5. Historical messages carry no media: type says what it was and media is null.
6. Messages already stored are skipped and counted in duplicateCount.
7. History does not count toward sentMessageCount or receivedMessageCount in usage.
8. How much history WhatsApp sends is decided by WhatsApp and the phone. There is no endpoint to ask for more.

Sticker packs, orders and bots

curl https://api.wuapi.dev/v1/accounts/k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr/orders/ORDER_ID?token=ORDER_TOKEN \
  -H "Authorization: Bearer wu_live_..."

Webhooks

Create up to five HTTPS webhook endpoints per organization, plus five per project, in the dashboard or with POST /v1/webhook-endpoints {url, events, projectId?}. The response includes the signing secret; it is shown once. POST /v1/webhook-endpoints/{webhookEndpointId}/rotate-secret issues a new one and returns it.

const endpoint = await wuapi.webhookEndpoints.create({
  url: "https://example.com/webhooks/wuapi",
  events: ["message.received", "message.failed", "account.disconnected"],
})
console.log(endpoint.secret) // whsec_..., returned only on creation and rotation

{
  "id": "evt_3f9a1c2b7d4e5f60a1b2c3d4",
  "object": "event",
  "type": "message.received",
  "createdAt": "2026-09-24T14:02:11.000Z",
  "organizationId": "w82t6y1u5i9o3p7a2s6d0f4g8h2j6k1l",
  "projectId": null,
  "data": {
    "object": {
      "object": "message",
      "id": "j97d2k1x8p3m4q5w6e7r8t9y0u1i2o3p",
      "...": "..."
    }
  }
}

Every event shares that envelope. data.object is the resource in the same shape the REST API returns it, so the code that reads a message from GET /v1/messages/{messageId} also reads it from message.received. message.edited and invitation.status_changed add data.previousAttributes with the values before the change. projectId is the project the event belongs to, or null. An organization endpoint receives every project's events; an endpoint created for a project receives only that project's. The catalog is in Events.

Delivery

We POST the JSON payload with a 10 second timeout, without following redirects. Any 2xx is a success. Anything else is retried after 30 seconds, 2 minutes, 10 minutes, 1 hour and 6 hours: six attempts in total. The dashboard (Logs, Webhooks) keeps every delivery for 30 days with each attempt's status, latency and the start of a non-2xx response body; from there you can resend a delivery (a new delivery with the same id) or send a webhook.test event to an endpoint. Requests carry Wuapi-Event-Id and Wuapi-Event-Type headers. Deliveries can arrive more than once and out of order: handle events idempotently using id.

Linked accounts drop their connection and reconnect by themselves every few minutes, usually within a few seconds. Those blips are not events: account.disconnected fires only when the account is still not ready after the reconnect grace (currently 20 seconds), and a reconnect inside it fires neither that nor account.connected: every account.connected after a drop answers an account.disconnected you received. A drop the account does not recover from on its own (logged_out, for example) fires at once. The account in an account.disconnected for a drop it is still recovering from carries reconnecting: true. Sends made during a blip wait for the account.

To alert on your side, key off these two events: on account.disconnected, alert right away when disconnectReason is one the session does not recover from (logged_out, connection_replaced, temporary_ban, or status failed or qr_ready); otherwise start a timer for as long as you can live with the number offline, and cancel it on account.connected for the same account. You do not need that to hear about it yourself: the dashboard's notifications (Settings, Notifications) email the owner and admins, show in the bell and can post to a Slack incoming webhook when a number stays offline past a threshold you choose (10 minutes by default), needs to be linked again, or a webhook endpoint keeps failing. Those never go through your webhook endpoints.

Verifying the signature

Each request carries Wuapi-Signature: t=<unix seconds>,v1=<hex>, where v1 is the HMAC-SHA256 of <t>.<raw body> keyed with the endpoint secret. Compute it over the raw body, compare in constant time, and reject timestamps older than a few minutes.

import { verifyWebhook, WebhookVerificationError } from "@wuapidev/sdk"

export async function POST(request: Request) {
  const rawBody = await request.text()
  try {
    const event = await verifyWebhook(
      rawBody,
      request.headers.get("wuapi-signature"),
      process.env.WUAPI_WEBHOOK_SECRET!,
    )
    switch (event.type) {
      case "message.received":
        console.log(event.data.object.from, event.data.object.text)
        break
      case "account.disconnected":
        console.log(event.data.object.id, event.data.object.disconnectReason)
        break
    }
    return new Response(null, { status: 204 })
  } catch (err) {
    if (err instanceof WebhookVerificationError) return new Response("invalid signature", { status: 400 })
    throw err
  }
}

Events

Every event type, with the data it carries. data.object names its type in its own object field: a resource such as account or message, or an object that only events carry, such as poll_vote or call. Contacts are E.164 numbers, or lid: ids when WhatsApp hides the number.

{
  "object": {
    "object": "account",
    "id": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
    "projectId": null,
    "name": "Support line",
    "status": "qr_ready",
    "reconnecting": false,
    "phone": null,
    "profileName": null,
    "proxyLocation": {
      "country": "VE",
      "city": "caracas",
      "strictCity": false
    },
    "qrCodeUrl": "data:image/png;base64,iVBORw0KGgo...",
    "pairingCode": null,
    "pairingCodeExpiresAt": null,
    "billable": false,
    "disconnectReason": null,
    "lastError": null,
    "rejectCalls": false,
    "rejectCallsMessage": null,
    "pacing": {
      "messagesPerMinute": 0,
      "firstContactPerMinute": 0,
      "typing": {
        "enabled": false,
        "minMs": 800,
        "maxMs": 6000,
        "charsPerSecond": 25
      },
      "queueTimeoutMinutes": 60,
      "custom": false
    },
    "metadata": {},
    "linkedAt": null,
    "lastConnectedAt": null,
    "createdAt": "2026-09-20T09:10:02.000Z",
    "updatedAt": "2026-09-24T14:02:11.000Z"
  }
}

{
  "object": {
    "object": "account",
    "id": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
    "projectId": null,
    "name": "Support line",
    "status": "qr_ready",
    "reconnecting": false,
    "phone": null,
    "profileName": null,
    "proxyLocation": {
      "country": "VE",
      "city": "caracas",
      "strictCity": false
    },
    "qrCodeUrl": null,
    "pairingCode": "WZYX-4K2Q",
    "pairingCodeExpiresAt": "2026-09-24T14:04:51.000Z",
    "billable": false,
    "disconnectReason": null,
    "lastError": null,
    "rejectCalls": false,
    "rejectCallsMessage": null,
    "pacing": {
      "messagesPerMinute": 0,
      "firstContactPerMinute": 0,
      "typing": {
        "enabled": false,
        "minMs": 800,
        "maxMs": 6000,
        "charsPerSecond": 25
      },
      "queueTimeoutMinutes": 60,
      "custom": false
    },
    "metadata": {},
    "linkedAt": null,
    "lastConnectedAt": null,
    "createdAt": "2026-09-20T09:10:02.000Z",
    "updatedAt": "2026-09-24T14:02:11.000Z"
  }
}

{
  "object": {
    "object": "account",
    "id": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
    "projectId": null,
    "name": "Support line",
    "status": "ready",
    "reconnecting": false,
    "phone": "+584121234567",
    "profileName": "Acme Support",
    "proxyLocation": {
      "country": "VE",
      "city": "caracas",
      "strictCity": false
    },
    "qrCodeUrl": null,
    "pairingCode": null,
    "pairingCodeExpiresAt": null,
    "billable": true,
    "disconnectReason": null,
    "lastError": null,
    "rejectCalls": false,
    "rejectCallsMessage": null,
    "pacing": {
      "messagesPerMinute": 0,
      "firstContactPerMinute": 0,
      "typing": {
        "enabled": false,
        "minMs": 800,
        "maxMs": 6000,
        "charsPerSecond": 25
      },
      "queueTimeoutMinutes": 60,
      "custom": false
    },
    "metadata": {},
    "linkedAt": "2026-09-20T09:12:40.000Z",
    "lastConnectedAt": "2026-09-24T14:02:11.000Z",
    "createdAt": "2026-09-20T09:10:02.000Z",
    "updatedAt": "2026-09-24T14:02:11.000Z"
  }
}

{
  "object": {
    "object": "account",
    "id": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
    "projectId": null,
    "name": "Support line",
    "status": "disconnected",
    "reconnecting": false,
    "phone": "+584121234567",
    "profileName": "Acme Support",
    "proxyLocation": {
      "country": "VE",
      "city": "caracas",
      "strictCity": false
    },
    "qrCodeUrl": null,
    "pairingCode": null,
    "pairingCodeExpiresAt": null,
    "billable": false,
    "disconnectReason": "logged_out",
    "lastError": null,
    "rejectCalls": false,
    "rejectCallsMessage": null,
    "pacing": {
      "messagesPerMinute": 0,
      "firstContactPerMinute": 0,
      "typing": {
        "enabled": false,
        "minMs": 800,
        "maxMs": 6000,
        "charsPerSecond": 25
      },
      "queueTimeoutMinutes": 60,
      "custom": false
    },
    "metadata": {},
    "linkedAt": "2026-09-20T09:12:40.000Z",
    "lastConnectedAt": "2026-09-24T14:02:11.000Z",
    "createdAt": "2026-09-20T09:10:02.000Z",
    "updatedAt": "2026-09-24T14:02:11.000Z"
  }
}

{
  "object": {
    "object": "account",
    "id": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
    "projectId": null,
    "name": "Support line",
    "status": "failed",
    "reconnecting": false,
    "phone": "+584121234567",
    "profileName": "Acme Support",
    "proxyLocation": {
      "country": "VE",
      "city": "caracas",
      "strictCity": false
    },
    "qrCodeUrl": null,
    "pairingCode": null,
    "pairingCodeExpiresAt": null,
    "billable": true,
    "disconnectReason": "connect_failed",
    "lastError": null,
    "rejectCalls": false,
    "rejectCallsMessage": null,
    "pacing": {
      "messagesPerMinute": 0,
      "firstContactPerMinute": 0,
      "typing": {
        "enabled": false,
        "minMs": 800,
        "maxMs": 6000,
        "charsPerSecond": 25
      },
      "queueTimeoutMinutes": 60,
      "custom": false
    },
    "metadata": {},
    "linkedAt": "2026-09-20T09:12:40.000Z",
    "lastConnectedAt": "2026-09-24T14:02:11.000Z",
    "createdAt": "2026-09-20T09:10:02.000Z",
    "updatedAt": "2026-09-24T14:02:11.000Z"
  }
}

{
  "object": {
    "object": "message",
    "id": "j97d2k1x8p3m4q5w6e7r8t9y0u1i2o3p",
    "projectId": null,
    "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
    "chatId": "+584241112233",
    "chatType": "direct",
    "direction": "inbound",
    "source": "contact",
    "from": "+584241112233",
    "to": "+584121234567",
    "profileName": "Maria",
    "username": "maria.gomez",
    "type": "text",
    "text": "Is my order on the way?",
    "media": null,
    "location": null,
    "contact": null,
    "contacts": null,
    "poll": null,
    "calendarEvent": null,
    "mentions": [],
    "forwarded": false,
    "viewOnce": false,
    "starred": false,
    "replyToMessageId": null,
    "status": "received",
    "error": null,
    "metadata": {},
    "sentAt": "2026-09-24T14:02:10.000Z",
    "editedAt": null,
    "deletedAt": null,
    "createdAt": "2026-09-24T14:02:11.000Z",
    "updatedAt": "2026-09-24T14:02:11.000Z"
  }
}

{
  "object": {
    "object": "message",
    "id": "j97d2k1x8p3m4q5w6e7r8t9y0u1i2o3p",
    "projectId": null,
    "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
    "chatId": "+584241112233",
    "chatType": "direct",
    "direction": "outbound",
    "source": "api",
    "from": "+584121234567",
    "to": "+584241112233",
    "profileName": null,
    "username": null,
    "type": "text",
    "text": "Your order has shipped.",
    "media": null,
    "location": null,
    "contact": null,
    "contacts": null,
    "poll": null,
    "calendarEvent": null,
    "mentions": [],
    "forwarded": false,
    "viewOnce": false,
    "starred": false,
    "replyToMessageId": null,
    "status": "sent",
    "error": null,
    "metadata": {},
    "sentAt": "2026-09-24T14:02:12.000Z",
    "editedAt": null,
    "deletedAt": null,
    "createdAt": "2026-09-24T14:02:11.000Z",
    "updatedAt": "2026-09-24T14:02:11.000Z"
  }
}

{
  "object": {
    "object": "message",
    "id": "j97d2k1x8p3m4q5w6e7r8t9y0u1i2o3p",
    "projectId": null,
    "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
    "chatId": "+584241112233",
    "chatType": "direct",
    "direction": "outbound",
    "source": "api",
    "from": "+584121234567",
    "to": "+584241112233",
    "profileName": null,
    "username": null,
    "type": "text",
    "text": "Your order has shipped.",
    "media": null,
    "location": null,
    "contact": null,
    "contacts": null,
    "poll": null,
    "calendarEvent": null,
    "mentions": [],
    "forwarded": false,
    "viewOnce": false,
    "starred": false,
    "replyToMessageId": null,
    "status": "delivered",
    "error": null,
    "metadata": {},
    "sentAt": "2026-09-24T14:02:12.000Z",
    "editedAt": null,
    "deletedAt": null,
    "createdAt": "2026-09-24T14:02:11.000Z",
    "updatedAt": "2026-09-24T14:02:11.000Z"
  }
}

{
  "object": {
    "object": "message",
    "id": "j97d2k1x8p3m4q5w6e7r8t9y0u1i2o3p",
    "projectId": null,
    "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
    "chatId": "+584241112233",
    "chatType": "direct",
    "direction": "outbound",
    "source": "api",
    "from": "+584121234567",
    "to": "+584241112233",
    "profileName": null,
    "username": null,
    "type": "text",
    "text": "Your order has shipped.",
    "media": null,
    "location": null,
    "contact": null,
    "contacts": null,
    "poll": null,
    "calendarEvent": null,
    "mentions": [],
    "forwarded": false,
    "viewOnce": false,
    "starred": false,
    "replyToMessageId": null,
    "status": "read",
    "error": null,
    "metadata": {},
    "sentAt": "2026-09-24T14:02:12.000Z",
    "editedAt": null,
    "deletedAt": null,
    "createdAt": "2026-09-24T14:02:11.000Z",
    "updatedAt": "2026-09-24T14:02:11.000Z"
  }
}

{
  "object": {
    "object": "message",
    "id": "j97d2k1x8p3m4q5w6e7r8t9y0u1i2o3p",
    "projectId": null,
    "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
    "chatId": "+584241112233",
    "chatType": "direct",
    "direction": "outbound",
    "source": "api",
    "from": "+584121234567",
    "to": "+584241112233",
    "profileName": null,
    "username": null,
    "type": "text",
    "text": "Your order has shipped.",
    "media": null,
    "location": null,
    "contact": null,
    "contacts": null,
    "poll": null,
    "calendarEvent": null,
    "mentions": [],
    "forwarded": false,
    "viewOnce": false,
    "starred": false,
    "replyToMessageId": null,
    "status": "failed",
    "error": {
      "code": "not_on_whatsapp",
      "message": "The recipient is not on WhatsApp."
    },
    "metadata": {},
    "sentAt": null,
    "editedAt": null,
    "deletedAt": null,
    "createdAt": "2026-09-24T14:02:11.000Z",
    "updatedAt": "2026-09-24T14:02:11.000Z"
  }
}

{
  "object": {
    "object": "message",
    "id": "j97d2k1x8p3m4q5w6e7r8t9y0u1i2o3p",
    "projectId": null,
    "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
    "chatId": "+584241112233",
    "chatType": "direct",
    "direction": "inbound",
    "source": "contact",
    "from": "+584241112233",
    "to": "+584121234567",
    "profileName": "Maria",
    "username": null,
    "type": "text",
    "text": "Is my order on the way? It is #4417.",
    "media": null,
    "location": null,
    "contact": null,
    "contacts": null,
    "poll": null,
    "calendarEvent": null,
    "mentions": [],
    "forwarded": false,
    "viewOnce": false,
    "starred": false,
    "replyToMessageId": null,
    "status": "received",
    "error": null,
    "metadata": {},
    "sentAt": "2026-09-24T14:02:10.000Z",
    "editedAt": "2026-09-24T14:05:02.000Z",
    "deletedAt": null,
    "createdAt": "2026-09-24T14:02:11.000Z",
    "updatedAt": "2026-09-24T14:02:11.000Z"
  },
  "previousAttributes": {
    "text": "Is my order on the way?"
  }
}

{
  "object": {
    "object": "message",
    "id": "j97d2k1x8p3m4q5w6e7r8t9y0u1i2o3p",
    "projectId": null,
    "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
    "chatId": "+584241112233",
    "chatType": "direct",
    "direction": "outbound",
    "source": "api",
    "from": "+584121234567",
    "to": "+584241112233",
    "profileName": null,
    "username": null,
    "type": "text",
    "text": null,
    "media": null,
    "location": null,
    "contact": null,
    "contacts": null,
    "poll": null,
    "calendarEvent": null,
    "mentions": [],
    "forwarded": false,
    "viewOnce": false,
    "starred": false,
    "replyToMessageId": null,
    "status": "read",
    "error": null,
    "metadata": {},
    "sentAt": null,
    "editedAt": null,
    "deletedAt": "2026-09-24T14:06:40.000Z",
    "createdAt": "2026-09-24T14:02:11.000Z",
    "updatedAt": "2026-09-24T14:02:11.000Z"
  }
}

{
  "object": {
    "object": "poll_vote",
    "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
    "chatId": "120363041234567890@g.us",
    "messageId": "j97d2k1x8p3m4q5w6e7r8t9y0u1i2o3p",
    "voterId": "+584241112233",
    "options": [
      "Friday"
    ],
    "votedAt": "2026-09-24T14:07:12.000Z",
    "poll": {
      "object": "message",
      "id": "j97d2k1x8p3m4q5w6e7r8t9y0u1i2o3p",
      "projectId": null,
      "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
      "chatId": "120363041234567890@g.us",
      "chatType": "group",
      "direction": "outbound",
      "source": "api",
      "from": "+584121234567",
      "to": "120363041234567890@g.us",
      "profileName": null,
      "username": null,
      "type": "poll",
      "text": null,
      "media": null,
      "location": null,
      "contact": null,
      "contacts": null,
      "poll": {
        "name": "Team dinner?",
        "options": [
          {
            "name": "Thursday",
            "voteCount": 1
          },
          {
            "name": "Friday",
            "voteCount": 3
          }
        ],
        "selectableCount": 1,
        "voterCount": 4
      },
      "calendarEvent": null,
      "mentions": [],
      "forwarded": false,
      "viewOnce": false,
      "starred": false,
      "replyToMessageId": null,
      "status": "read",
      "error": null,
      "metadata": {},
      "sentAt": null,
      "editedAt": null,
      "deletedAt": null,
      "createdAt": "2026-09-24T14:02:11.000Z",
      "updatedAt": "2026-09-24T14:02:11.000Z"
    }
  }
}

{
  "object": {
    "object": "group",
    "id": "120363041234567890@g.us",
    "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
    "name": "Night shift",
    "description": "Handover notes and schedules.",
    "ownerId": "+584121234567",
    "community": false,
    "locked": false,
    "announce": false,
    "participants": [
      {
        "contactId": "+584121234567",
        "name": "Acme Support",
        "role": "owner"
      },
      {
        "contactId": "+584241112233",
        "name": "Maria",
        "role": "member"
      }
    ],
    "createdAt": "2026-09-01T12:00:00.000Z"
  }
}

{
  "object": {
    "object": "group_change",
    "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
    "groupId": "120363041234567890@g.us",
    "actorId": "+584241112233",
    "added": [
      "+584141234567"
    ],
    "removed": [],
    "promoted": [],
    "demoted": [],
    "name": null,
    "description": null,
    "locked": null,
    "announce": null,
    "changes": [
      "participants_added"
    ],
    "changedAt": "2026-09-24T14:07:12.000Z"
  }
}

{
  "object": {
    "object": "group_join_request",
    "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
    "groupId": "120363041234567890@g.us",
    "contactId": "+584241112233",
    "requestedAt": "2026-09-24T14:07:12.000Z"
  }
}

{
  "object": {
    "object": "group_join_request",
    "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
    "groupId": "120363041234567890@g.us",
    "contactId": "+584241112233",
    "requestedAt": "2026-09-24T14:07:12.000Z"
  }
}

{
  "object": {
    "object": "chat_change",
    "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
    "chatId": "+584241112233",
    "change": "mute",
    "value": true,
    "messageId": null,
    "mutedUntil": "2026-09-25T14:00:00.000Z"
  }
}

{
  "object": {
    "object": "chat_presence",
    "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
    "chatId": "+584241112233",
    "contactId": "+584241112233",
    "state": "typing"
  }
}

{
  "object": {
    "object": "contact_presence",
    "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
    "contactId": "+584241112233",
    "online": false,
    "lastSeenAt": "2026-09-24T14:05:00.000Z"
  }
}

{
  "object": {
    "object": "picture_change",
    "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
    "chatId": "+584241112233",
    "pictureId": "1790258832",
    "removed": false,
    "changedBy": null,
    "changedAt": "2026-09-24T14:07:12.000Z"
  }
}

{
  "object": {
    "object": "contact",
    "id": "+584241112233",
    "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
    "lid": null,
    "username": null,
    "about": "At the office until 6",
    "pictureId": null,
    "businessName": null,
    "deviceCount": null
  }
}

{
  "object": {
    "object": "blocklist_change",
    "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
    "changes": [
      {
        "contactId": "+584241112233",
        "action": "block",
        "phone": "+584241112233",
        "lid": "lid:201843727138927"
      }
    ],
    "refetch": false
  }
}

{
  "object": {
    "object": "label_change",
    "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
    "kind": "chat",
    "labelId": "3",
    "name": null,
    "color": null,
    "deleted": false,
    "chatId": "+584241112233",
    "messageId": null,
    "labeled": true
  }
}

{
  "object": {
    "object": "call",
    "id": "4B2F9A0C1D3E5F7A",
    "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
    "from": "+584241112233",
    "video": false,
    "groupId": null,
    "endReason": null,
    "startedAt": "2026-09-24T14:10:00.000Z",
    "endedAt": null
  }
}

{
  "object": {
    "object": "call",
    "id": "4B2F9A0C1D3E5F7A",
    "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
    "from": "+584241112233",
    "video": false,
    "groupId": null,
    "endReason": "rejected",
    "startedAt": null,
    "endedAt": "2026-09-24T14:11:30.000Z"
  }
}

{
  "object": {
    "object": "channel_message",
    "id": "118",
    "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
    "channelId": "120363198765432109@newsletter",
    "type": "text",
    "text": "Doors open at 8.",
    "viewCount": null,
    "reactions": {},
    "sentAt": "2026-09-24T14:07:12.000Z"
  }
}

{
  "object": {
    "object": "channel_message",
    "id": "118",
    "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
    "channelId": "120363198765432109@newsletter",
    "type": "text",
    "text": null,
    "viewCount": 412,
    "reactions": {
      "👍": 31
    },
    "sentAt": "2026-09-24T14:07:12.000Z"
  }
}

{
  "object": {
    "object": "channel_change",
    "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
    "channelId": "120363198765432109@newsletter",
    "change": "muted",
    "name": null,
    "role": null
  }
}

{
  "object": {
    "object": "history_sync",
    "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
    "chunk": 1,
    "syncType": "recent",
    "progress": 42,
    "part": 1,
    "conversationCount": 18,
    "messageCount": 500,
    "duplicateCount": 0
  }
}

{
  "object": {
    "object": "project",
    "id": "m17c4e9t2n5a8x0d3f6h9j2k5l8p1q4r",
    "name": "Acme Dental",
    "externalId": "cus_4417",
    "metadata": {},
    "status": "active",
    "maxAccounts": 3,
    "accountCount": 0,
    "createdAt": "2026-09-24T14:00:00.000Z",
    "updatedAt": "2026-09-24T14:00:00.000Z"
  }
}

{
  "object": {
    "object": "project",
    "id": "m17c4e9t2n5a8x0d3f6h9j2k5l8p1q4r",
    "name": "Acme Dental",
    "externalId": "cus_4417",
    "metadata": {},
    "status": "suspended",
    "maxAccounts": 3,
    "accountCount": 2,
    "createdAt": "2026-09-24T14:00:00.000Z",
    "updatedAt": "2026-09-24T14:02:11.000Z"
  }
}

{
  "object": {
    "object": "project",
    "id": "m17c4e9t2n5a8x0d3f6h9j2k5l8p1q4r",
    "name": "Acme Dental",
    "externalId": "cus_4417",
    "metadata": {},
    "status": "active",
    "maxAccounts": 3,
    "accountCount": 0,
    "createdAt": "2026-09-24T14:00:00.000Z",
    "updatedAt": "2026-09-24T14:02:11.000Z"
  }
}

{
  "object": {
    "object": "invitation",
    "id": "n28d5f0u3o6b9y1e4g7i0k3m6o9r2s5t",
    "projectId": "m17c4e9t2n5a8x0d3f6h9j2k5l8p1q4r",
    "status": "completed",
    "url": null,
    "inviteeName": "Maria Perez",
    "inviteeEmail": "maria@example.com",
    "inviteePhone": null,
    "suggestedCountry": "MX",
    "proxyLocation": {
      "country": "MX",
      "city": "mexicocity",
      "strictCity": false
    },
    "methods": [
      "qr_code",
      "pairing_code"
    ],
    "accountName": "Front desk",
    "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
    "failureReason": null,
    "returnUrl": "https://app.example.com/whatsapp/done",
    "metadata": {
      "store": "cdmx-2"
    },
    "emailSentAt": "2026-09-24T14:00:00.000Z",
    "expiresAt": "2026-10-01T14:00:00.000Z",
    "viewedAt": "2026-09-24T14:01:02.000Z",
    "startedAt": "2026-09-24T14:01:30.000Z",
    "completedAt": "2026-09-24T14:03:10.000Z",
    "createdAt": "2026-09-24T14:00:00.000Z",
    "updatedAt": "2026-09-24T14:03:10.000Z"
  },
  "previousAttributes": {
    "status": "in_progress"
  }
}

{
  "object": {
    "object": "webhook_endpoint",
    "id": "n97p31n8b5c7z2y4u6ebt5gr1ew3qa8s",
    "projectId": null,
    "url": "https://example.com/webhooks/wuapi",
    "events": [
      "message.received"
    ],
    "active": true,
    "createdAt": "2026-09-24T14:00:00.000Z",
    "updatedAt": "2026-09-24T14:00:00.000Z"
  }
}

Projects

Three levels. Your organization pays: it holds the subscription, the branding and the organization keys. A project is one of your customers, or an environment: it has its own accounts, API keys, webhook endpoints, limits and usage, isolated from every other project. An account is a linked WhatsApp number with a name, like Sales or Support. You rebill your customers from the per-project usage we report.

In the dashboard, the switcher at the top of the sidebar picks a project and an account inside it. Every screen then shows that scope: accounts, messages, keys, webhooks and usage. Billing and branding stay with the organization.

curl -X POST https://api.wuapi.dev/v1/projects \
  -H "Authorization: Bearer wu_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme Dental","externalId":"cus_4417","maxAccounts":3}'

Who can reach what

1. A resource outside the scope answers 404 not_found, never 403, so one project cannot confirm another project's IDs exist.
2. Accounts, messages, webhook endpoints and invitations created in a project scope belong to that project for good. With an organization key, POST /v1/accounts, POST /v1/webhook-endpoints and POST /v1/invitations take an optional projectId.
3. Lists are filtered by scope. With an organization key they accept ?projectId= with a project id, ext:<externalId>, or none for unassigned resources only.
4. Project keys cannot manage projects, branding, usage or organization keys: 403 forbidden. The header does not change what those organization routes return.
5. Project keys start with wu_live_ like any key, and each has its own 600 requests per minute.

Endpoints

Suspension and limits

PATCH a project to status: suspended when a customer stops paying. Its numbers stay linked and every read keeps working, but every send and every write answers 403 project_suspended, whichever key makes it. Inbound keeps being stored and delivered, so nothing is lost while you sort it out. Set status: active to resume.

Usage for rebilling

curl https://api.wuapi.dev/v1/usage/by-project?month=2026-09 \
  -H "Authorization: Bearer wu_live_..."

accountCount and billableAccountCount are current counts; month selects the month of proxyBytes, sentMessageCount and receivedMessageCount. sentMessageCount counts API sends WhatsApp accepted plus messages sent from the phone; receivedMessageCount counts contacts' messages. History imports count for neither. GET /v1/usage is the organization's bill for the current month in cents. We bill the organization, counting all its connected accounts together through graduated bands, each at its own price: $6 for your first number, $4.50 for every one after, and $3.50 from the 51st. Proxy: proxyBytes is every byte used this month, includedProxyBytes the pool (0.5 GB per account, at the most accounts billable this month), billableProxyBytes what is past it, and proxyFeeCents bills only that, at $0.99 per GB. Traffic used on the Free plan (or during a legacy free trial) is never billable, including in the month you upgrade. We never bill a project.

Invitations

An invitation is a page you send to someone else, your customer, a store manager or a sales rep, so they link their own WhatsApp into one of your projects. They need no account, dashboard or API key. Create one, send them url (or let us email it), and the number arrives as an account in the project.

curl -X POST https://api.wuapi.dev/v1/invitations \
  -H "Authorization: Bearer wu_live_..." \
  -H "Content-Type: application/json" \
  -d '{"projectId":"ext:cus_4417","inviteeName":"Maria Perez","inviteeEmail":"maria@example.com","accountName":"Front desk","suggestedCountry":"MX","returnUrl":"https://app.example.com/whatsapp/done","metadata":{"store":"cdmx-2"}}'

Creating an invitation checks what creating an account checks: 402 upgrade_required on the Free plan once its 1 account is taken, 403 project_suspended, 403 project_limit_reached and, on a legacy free trial, 403 trial_account_limit. They are checked again when the invitee starts, because that is when the account is created. url is returned only by create and resend: the token in it is stored hashed.

What the invitee sees

1. Welcome: your name, logo and color from branding, who it is for, what they need (the phone with WhatsApp, about two minutes) and what happens: the number becomes a linked device, their chats stay on the phone, and they can unlink it from WhatsApp, Linked devices.
2. Location: the country and city the number is from, the country preselected from suggestedCountry. It sets the account's proxy exit before its session starts. Skipped when you set proxyLocation, or when they come back to an invitation that already has an account.
3. Link: a live QR code that refreshes on its own, or their phone number and an 8-character pairing code to type in WhatsApp, Linked devices, Link with phone number instead. A new code can be requested every 15 seconds.
4. Done: the linked number and its WhatsApp name, and a link back to returnUrl when you set one.
5. A cancelled, expired or already used invitation shows a neutral page that names the state and tells them to ask you for a new one.

The page lives at wuapi.dev/invite/.... It is noindex, drops the referrer, has no analytics, and works on a 375 px screen. It shows nothing about your other projects, accounts or invitations.

Statuses

Endpoints

Every real status change fires invitation.status_changed, with the invitation in data.object and the status before in data.previousAttributes.status, to organization endpoints and to the project's endpoints. expired has no event, because nothing changes when time passes.

Email

With inviteeEmail set, the invitee gets one plain email in your name: "{displayName} invited you to connect WhatsApp", a button and the expiry, with your logo and color. It carries no wuapi mark while hideWuapiBranding is on and the White label add-on is active. When email is not enabled, the invitation is still created and emailSentAt is null: send the url yourself.

Branding

curl -X PATCH https://api.wuapi.dev/v1/branding \
  -H "Authorization: Bearer wu_live_..." \
  -H "Content-Type: application/json" \
  -d '{"displayName":"Acme Cloud","logoUrl":"https://acme.example/logo.png","accentColor":"#2563EB"}'

GET and PATCH /v1/branding, organization keys only. Until it is set, GET returns the object with displayName null. displayName (up to 60 characters) is required the first time. logoUrl and supportUrl are HTTPS; accentColor is #RRGGBB; all three take null to clear. A logo uploaded in the dashboard (PNG, JPEG, SVG or WebP, up to 512 KB) wins over logoUrl, and setting logoUrl replaces it. The page title and favicon never carry our brand. Without an accent color the page uses ours, or a neutral one when our branding is hidden.

White label

curl -X PATCH https://api.wuapi.dev/v1/branding \
  -H "Authorization: Bearer wu_live_..." \
  -H "Content-Type: application/json" \
  -d '{"hideWuapiBranding":true}'

hideWuapiBranding: true removes the Powered by wuapi footer from the page and the Sent by wuapi line from the email. It needs the White label add-on, $100/month on your usage subscription, added from Billing or Branding in the dashboard. Without it, true answers 402 addon_required with details: {addon: "white_label", priceCents: 10000}, and GET returns false, because the footer shows. Remove the add-on and the footer is back right away; add it again and your saved choice applies.

Errors

Errors share one shape: {code, message, details?}. The same situation answers the same code on every endpoint. Branch on code, not on message.

{
  "code": "invalid_request",
  "message": "`text` is required.",
  "details": {
    "field": "text"
  }
}

A send that was accepted and then fails is not an HTTP error: the message moves to failed with error: {code, message} (not_on_whatsapp, rate_limited, account_offline, payment_required, proxy_spend_cap_reached, cancelled or send_failed), and message.failed fires.

Rate limits and pacing

Each API key may make 600 requests per minute. Every response says where you stand with RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds until the window resets). Past the limit, requests return 429 with code rate_limited and a Retry-After header in seconds.

Separately, each number has a send queue. Messages leave it one at a time, and by default as fast as WhatsApp accepts them: the anti-ban protections (a per-minute cap, a first-contact cap and a typing indicator) are off until you turn them on for the account. See Sending safely for when to turn them on and the values we recommend. With a cap on, sends over the pace stay queued and go out as slots free up, for up to an hour; after that they fail with rate_limited. Queued messages are not guaranteed to leave in the order you sent them.

Edits, poll votes and the auto-reject reply to a call go through the same queue and pacing. Stories and channel posts count against the per-minute cap only, since they have no single recipient.

Set it per account

Every account returns its effective pacing, with custom: false while it runs on the defaults (every protection off). Change it with PATCH /v1/accounts/{accountId} and a pacing object. Fields you send merge over what is stored; 0 turns a cap off, null on a field resets it and pacing: null resets everything. The change applies from the next send, without reconnecting.

curl -X PATCH https://api.wuapi.dev/v1/accounts/k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr \
  -H "Authorization: Bearer wu_live_..." \
  -H "Content-Type: application/json" \
  -d '{"pacing":{"messagesPerMinute":20,"typing":{"enabled":true,"maxMs":4000},"queueTimeoutMinutes":120}}'

A value out of range answers 400 invalid_request with details: {field, min, max}, for example {"field": "pacing.messagesPerMinute", "min": 0, "max": 30}. A first-contact cap can't be higher than the per-minute cap while that one is on. The account page in the dashboard edits the same values.

Sending safely (anti-ban recommendations)

WhatsApp decides which numbers it restricts, and bursts of messages to people who don't know the number are one of the clearest signals it looks at. wuapi can pace each number to look like a person: a per-minute cap, a tighter cap for people who never wrote to it, and a typing indicator before each message. These protections are off by default, so a number sends as fast as WhatsApp accepts, one message at a time. You turn them on per account.

They are off by default because many numbers don't need them. An app that answers people who just wrote to it, or sends a login code the person asked for, would only be slowed down: a code that arrives a minute late is a failed login. A number that writes first to many people is a different case, and there we recommend turning them on.

What each protection does

Two things are always on and aren't protections you configure. Before a first message to someone, wuapi asks WhatsApp whether the number is on it, and a message to a number that isn't ends failed with not_on_whatsapp. And each number sends one message at a time, in order.

When to turn them on

1. Bulk sends: a campaign, an announcement, a list of any size.
2. Cold outreach: writing first to people who never wrote to the number.
3. Marketing and promotions, even to customers who opted in.
4. A new number, for its first weeks. Start slower than the recommended values and raise them as replies come in.
5. A number that was restricted before, from the day it comes back.

When you can leave them off

1. Transactional replies to people who wrote first: support, an AI agent answering a chat, order questions.
2. One-time codes and alerts the person is waiting for, where a delay breaks the flow.
3. Messages to your own number and to your team while you build and test.

If one number does both, turn the protections on: replies to people who wrote first skip the first-contact cap anyway, and only pay the per-minute cap and the typing time. Or keep the two kinds of traffic on different numbers.

Turn them on

With the API, send the recommended values in pacing. In the dashboard, open the account and choose Use recommended settings under Pacing, or turn each protection on by itself.

curl -X PATCH https://api.wuapi.dev/v1/accounts/k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr \
  -H "Authorization: Bearer wu_live_..." \
  -H "Content-Type: application/json" \
  -d '{"pacing":{"messagesPerMinute":12,"firstContactPerMinute":5,"typing":{"enabled":true,"minMs":800,"maxMs":6000,"charsPerSecond":25}}}'

Each protection can be set alone. 0 turns a cap off again, and pacing: null puts everything back to the defaults.

curl -X PATCH https://api.wuapi.dev/v1/accounts/k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr \
  -H "Authorization: Bearer wu_live_..." \
  -H "Content-Type: application/json" \
  -d '{"pacing":{"typing":{"enabled":true}}}'

No setting makes cold bulk messaging safe. The protections remove the most obvious signal, sending like a machine. WhatsApp also reads what you send and how people react to it.

Good practice

1. Only message people who expect it: they gave you their number and know why you're writing.
2. Warm up a new number. A few conversations a day at first, then more as people reply.
3. Don't send the same text to many people. Use their name, their order, their appointment.
4. Respect opt-outs. Make stopping easy, and stop the first time someone asks.
5. Keep the first message to a new contact plain: no links or attachments until they reply.
6. Set a name, a photo and an about line on the number before it sends anything.
7. Watch replies and blocks. When people stop answering a message, stop sending it.

More habits, a warm-up plan and what to do when WhatsApp restricts a number: wuapi.dev/guides/avoid-restrictions

What is not supported

The gaps we know of, each with its reason.

wuapi is not the WhatsApp Business Platform and is not affiliated with, endorsed or sponsored by WhatsApp. We cannot promise a number is never restricted: WhatsApp restricts numbers for what they send and how recipients react.

TypeScript SDK

The @wuapidev/sdk package on npm wraps the REST API with types for every request, response and event. It has no runtime dependencies and runs on Node 18+, Bun, Deno and edge runtimes.

npm install @wuapidev/sdk

import { Wuapi } from "@wuapidev/sdk"

const wuapi = new Wuapi({ apiKey: process.env.WUAPI_API_KEY })

// 1. Pick where the number exits, then create the account.
//    Requires an active subscription (402 otherwise).
const [location] = await wuapi.proxyLocations.list({ country: "CL" }).toArray(1)
const account = await wuapi.accounts.create({
  name: "Support line",
  proxyLocation: { country: location.country, city: location.city }, // e.g. CL / santiago
})

// 2. Wait for the QR code and show it to the phone owner.
//    On the phone: WhatsApp > Linked devices > Link a device.
const withQr = await wuapi.accounts.waitForQrCode(account.id)
console.log("Scan this QR code:", withQr.qrCodeUrl) // PNG data URL, e.g. <img src={qrCodeUrl} />

// 3. Wait until the phone finishes linking. The QR code rotates while it
//    waits; onQrCode is called with each new one.
const ready = await wuapi.accounts.waitUntilReady(account.id, {
  onQrCode: (qrCodeUrl) => console.log("New QR code:", qrCodeUrl),
})
console.log("Linked", ready.phone)

// 4. Send a message.
const message = await wuapi.messages.send({
  accountId: ready.id,
  to: "+584241112233",
  text: "Your order has shipped.",
})
console.log(message.id, message.status) // "queued"

apiKey falls back to the WUAPI_API_KEY environment variable. Methods return the resource itself: accounts.get(id) returns an account and messages.send() returns the message. Every method takes an optional last argument { idempotencyKey?, signal? }; idempotencyKey is sent as the Idempotency-Key header, and the SDK generates one for every POST when you do not pass it, so retries never send twice.

Lists

List methods return a paginator, including the lists read live from WhatsApp such as groups.list and channels.listMessages. Iterate it to walk every item across pages, or call .page() for one page. Batch results, such as contacts.check and groups.addParticipants, return an array.

for await (const message of wuapi.messages.list({ accountId, direction: "inbound" })) {
  console.log(message.from, message.text)
}

const { items, nextCursor } = await wuapi.messages.list({ limit: 20 }).page()
const next = await wuapi.messages.list({ limit: 20 }).page(nextCursor ?? undefined)

Errors and retries

Every non-2xx response throws a WuapiError with status, code, message, details and requestId. The client retries up to maxRetries times (default 2): 429 after Retry-After, and 5xx, network errors and timeouts for requests that are safe to repeat, which includes every POST carrying an idempotency key.