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. Use Webhooks or Streams 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-skills

The skills live in the public repository wuapidev/wuapi-skills, 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, 87 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 Grok, ChatGPT and Claude.ai do, use the next section.

Connect with OAuth

Chat apps that add remote MCP servers as connectors sign in with OAuth instead of a header. Give them the hosted URL, https://wuapi.dev/api/mcp. Most find the rest on their own: the server's 401 points to its metadata, the app registers itself and opens a wuapi page in your browser. Sign in, pick the organization (all of it or one project) and approve. The app gets an API key named MCP · <app>, listed on API keys. Revoke it there to disconnect the app.

If the app asks for the OAuth settings itself, as Grok's custom connector does, fill them in like this:

The consent page shows where the approval goes (the app's address). Approve only a connection you just started. An OAuth key has the full access of an organization or project key: read-only mode is not available through OAuth yet, so use a header client with Wuapi-Read-Only if you need it. The key does not expire. If you revoke it, the app asks you to connect again.

Configuration

Tools

Every tool declares a JSON schema for its input and returns the API's own object as structured content, without nulls. Together they reach every operation of the REST API except the two that return a secret. Tools that read carry readOnlyHint. Tools that delete, revoke, reset, block 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, delete_chat, remove_group_participants, reset_group_invite_link, leave_group, delete_webhook, delete_incoming_webhook, cancel_invitation, resend_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.

Resources with many small operations are one tool with an action argument, so the list stays short enough for a model to pick from. The tool's description lists its actions and each field says which actions use it. Only the destructive actions need confirm: true: unlink_account (logout, delete), manage_labels (delete), manage_block_list (block), manage_profile (delete_picture, reset_contact_link), manage_group_settings (delete_picture), manage_stories (delete), manage_project (delete, revoke_key). In read-only mode a tool that mixes reads and writes keeps only its reading actions. To post to a channel, use send_text or send_media with to set to the channel id.

Projects, invitations, branding and usage need an organization key. Creating a project API key and rotating a webhook endpoint's signing secret are not tools: both return a secret exactly once, and tool results never carry secrets. Do them in the dashboard or with the SDK. Sending a test webhook event and reading the request log have no public endpoint, so they are not tools either; 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) invite_customer (customer, externalId, email) and use_streams (project, language).

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 or rotates a signing secret.
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.

CLI

The @wuapidev/cli command line logs in from the browser, links a number, runs your app with the key, sends a message, sets up the MCP server, watches your events live with Streams and calls every SDK method from a terminal or a script. It needs Node 20 or later and nothing installed: npx @wuapidev/cli runs the latest version.

npx @wuapidev/cli login
npx @wuapidev/cli link --phone +584241112233
npx @wuapidev/cli send +584241112233 "Hi from the terminal"
npx @wuapidev/cli run -- npm run dev

Log in

npx @wuapidev/cli login shows a code like BCDF-GHJK and opens https://wuapi.dev/app/cli in your browser (sign in first if you aren't). Check that the page shows the same code, pick the organization and whether the key reaches all of it or one project, and approve. The terminal gets a new API key named CLI · <device name> and stores it in ~/.config/wuapi/credentials.json, readable only by you. The key is listed under API keys like any other and you revoke it there. A code lasts 10 minutes and works once.

1. --env also writes WUAPI_API_KEY into .env in the current folder. That puts the key in a project file: it is for people, not for agents. wuapi run gives your app the key without it.
2. --no-browser prints the link instead of opening it, for a remote shell. Open it on any device where you're signed in.
3. --start prints the code and the link and exits; --finish waits for the approval and saves the key. An agent uses the pair to hand you the link, and the CLI keeps the key: the agent never sees it. Run both in the same folder; each folder keeps its own pending login, so two agent sessions in different folders do not collide.

Profiles

Each login is a profile: one organization, or one project of it, with its own key. Log in again to add another. wuapi profiles lists them and marks the current one, wuapi switch <name> changes it, and --profile <name> (or WUAPI_PROFILE) picks one for a single command. wuapi logout [<name>] [--all] removes a profile, the current one by default, from the file. The key keeps working until you revoke it under API keys.

Commands

Every command takes --json and then prints only JSON on stdout, errors included, so scripts and agents can parse it. --project <id> (or WUAPI_PROJECT) acts inside one project with an organization key.

Which key it uses

The first one found: --api-key, then the WUAPI_API_KEY environment variable, then WUAPI_API_KEY in .env in the current folder, then the profile named by --profile or WUAPI_PROFILE, then the current profile. wuapi whoami says which one won.

The key never goes in a command's output. The approval page shows the code and the device name the terminal sent; approve only a login you started 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 every plan, an account that has not linked within 15 minutes stops its session (link_timeout); reconnect it for a new QR code.

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 every plan, link_timeout (not linked within 15 minutes; reconnect for a new QR code) does not either. On the Free plan there is one more: 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. Troubleshooting connections, under Reference, explains each reason, the lines in the account's connection log and what to do.

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 and included in the account price, with no per-GB charge, up to a fair use of 5 GB per billable account a month, pooled across the organization at the most accounts billable that month. Subscriptions started before October 18, 2026 keep metered billing: 0.5 GB included per account, then $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 traffic can pause for three reasons. When the organization's traffic reaches the fair use, it pauses until the month ends (UTC). While an invoice is unpaid, it pauses until the invoice is paid. On legacy metered billing, each organization also has a monthly cap on proxy overage ($50 unless an owner or admin changes it in Billing; $0 allows none), and at the cap it pauses until the cap is raised or the month ends. 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 proxy_fair_use_reached, 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 thirteen shapes, chosen by type. Each type requires its own field; the fields in the first table work with every type.

A buttons message takes no replyToMessageId, replyToStoryId, mentions, mentionAll, forwarded or disappearingSeconds: those fields belong to a WhatsApp content message, and a native-flow message carries none of them.

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"
    }
  }'

Image quality. An image is uploaded through the number's proxy, so wuapi sends it the way the WhatsApp apps send a photo: smaller, with no visible difference in a chat. The account's imageQuality sets it for every image, and media.quality on a send overrides it for that image.

1. standard (the default): the longest side is brought down to 1600 px and the image is sent as a JPEG at quality 80. A 12 MP phone photo of 3 to 5 MB goes out at 150 to 400 KB.
2. hd: up to 4096 px at quality 90, like the HD switch in the apps.
3. original: the file is not re-encoded. Only its metadata (Exif, GPS, embedded thumbnails) is removed; the pixels are the same.
4. Only image messages and image stories. A document is delivered as the file it is, so send a photo as a document when the recipient needs the exact file. Stickers, video and audio are never changed.
5. An image that is already small is left alone, and so is one that would not come out at least 10% smaller. A PNG with transparency stays a PNG, and a flat one (a logo, a screenshot with few colors) too. The color profile and the orientation are kept.
6. Change the account's with PATCH /v1/accounts/{accountId} {"imageQuality": "hd"} or in the dashboard. It applies to the images sent from then on.

{
  "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,
  "footer": null,
  "buttons": null,
  "button": null,
  "mentions": [],
  "forwarded": false,
  "forwardedManyTimes": false,
  "viewOnce": false,
  "starred": false,
  "replyToMessageId": null,
  "replyToStoryId": 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. A buttons message is a native-flow message: WhatsApp draws up to 10 buttons under the body. A quick reply is disabled in the sender's own view of the message (WhatsApp does not let you answer yourself) and enabled for everyone else; a link button opens its URL.
3. 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.
4. 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, proxy_fair_use_reached 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 or list messages to send: those are features of the official WhatsApp Business Platform. Buttons are not: a native-flow message (type: "buttons") renders from a linked number, and a tap comes back as a message of type button.

Sending a file you have

media.url needs the file at a public URL. For a file you have instead (a local file, a pasted image, a recorded voice note), upload it and send it by its id: media: {uploadId}. Nothing is downloaded from outside when it is sent, because wuapi already stores the file.

import { readFile } from "node:fs/promises"

const upload = await wuapi.uploads.upload(await readFile("photo.jpg"), { mimeType: "image/jpeg" })
await wuapi.messages.send({ accountId, to: "+584241112233", type: "image", media: { uploadId: upload.id }, text: "From my camera roll" })

curl -X POST https://api.wuapi.dev/v1/uploads \
  -H "Authorization: Bearer wu_live_..." \
  -H "Content-Type: application/json" \
  -d '{"mimeType":"audio/ogg; codecs=opus","base64":"T2dnUwACAAAAAAAAAAB3aGF0c2FwcA=="}'

1. The TypeScript SDK's uploads.upload(file) takes a Blob, File, Buffer, ArrayBuffer or stream and picks the way: one request for a small file, the upload URL for a larger one. It returns the ready upload.
2. A ready upload can be sent any number of times for 24 hours (expiresAt), to any account the key reaches: upload once, send to many chats. After that it answers 404; upload the file again.
3. The upload belongs to your organization, and to the project when the request is scoped to one. Another organization or project gets 404 not_found for its id, on reads and on sends.
4. Every step can be repeated. POST /v1/uploads with the same Idempotency-Key answers the same upload and the same uploadUrl. Completing a ready upload with the same storageId answers it again. A send repeated with the same Idempotency-Key returns the first message; it never fails because the upload was already used.
5. The message's media.size is the stored file's size at once, and media.url is the stored file: it works until the message is deleted, like a received file's. An uploaded image is sent at the account's imageQuality, or at media.quality, exactly as one from a URL: once it is sent, media.size, media.width and media.height are those of the image as it went out, and media.url is still the file you uploaded.
6. A sent message keeps its file after the upload expires. An upload that was never sent is deleted with its file when it expires. A pending upload expires after 1 hour.
7. The file posted to uploadUrl must be exactly the declared size: another size answers 400 on complete, the file is deleted and the upload stays pending. Over 100 MB answers 413 media_too_large.
8. Limits: 60 uploads per minute and 5 GB per day per organization, then 429 rate_limited with Retry-After. Uploading is not billed; sending the file is proxy traffic like any other media.
9. A voice note is an Ogg/Opus file sent with type: "voice", as from a URL: nothing is transcoded.

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.

Forwarding a message

POST /v1/messages/{messageId}/forward forwards a message wuapi stores (one the number received, one sent through the API, or one sent from the phone) to other chats of the same account, the way WhatsApp does it. You name the chats and nothing else: no content and no file. The recipients see the original content with the Forwarded label.

curl -X POST https://api.wuapi.dev/v1/messages/j97d2k1x8p3m4q5w6e7r8t9y0u1i2o3p/forward \
  -H "Authorization: Bearer wu_live_..." \
  -H "Content-Type: application/json" \
  -d '{"to":["+584241112233","120363041234567890@g.us"]}'

1. The answer has one message per chat, in the order of to. From there each is a message like any other: its own id, forwarded: true, the same events (message.sent, message.delivered, message.read, message.failed), the same pacing, queue timeout and offline tolerance as a send, and it counts as one sent message.
2. The request is all or nothing: when it is refused, nothing is queued. What can go wrong for one chat afterwards (the recipient has no WhatsApp, the account stays offline) is that message's own failed status.
3. What is forwarded: text (with its link preview when wuapi stored one), images, videos, GIFs, audio, voice notes (they stay voice notes), documents, stickers, locations and contact cards. Captions are kept.
4. What is not: polls, calendar events, reactions, view-once messages, deleted messages and outbound messages that never reached WhatsApp (queued or failed). They answer 400 not_forwardable with details.reason.
5. Stories: a story the account posted is a message, so it forwards to chats like any other. A contact's story does not (details.reason: story): WhatsApp has no forward for someone else's story. Reply to it with replyToStoryId instead.
6. Nothing of the original's context travels: no reply quote, no mentions, no disappearing timer.

Media is not uploaded again

A forwarded file is the same file on WhatsApp's servers: the new message names it, as the WhatsApp app does, so nothing is downloaded from WhatsApp and nothing is uploaded to it, whatever the file's size. That holds while WhatsApp still serves the original file. When it no longer does, wuapi uploads the copy it stores; when it never stored one, it first fetches the file from WhatsApp through the number's proxy. Only when neither WhatsApp nor wuapi has the file is the forward refused, with 410 media_expired.

The forwarded message's media is the source's. When wuapi stores the file, both messages point at that one file (media.url is the same, downloaded: true): it is not copied, and it stays until every message that points at it is deleted. When the source was sent with your own media.url, the forward shows that URL. When the file is still only on WhatsApp, the forward is downloaded: false too, with its own GET /v1/messages/{messageId}/media.

Forwarded many times

WhatsApp counts how many times a message was forwarded along its way. Every message carries forwardedManyTimes: true once it went through five forwards, which is when WhatsApp shows the double arrow and Forwarded many times. Forwarding adds one to the count. A message that is forwardedManyTimes can be forwarded to one chat per request, as in the app: more answers 400 invalid_request with details.maxChats: 1.

forwarded: true on POST /v1/messages is a different thing: it labels a new message, with content you supply, as forwarded. Use it when the content is yours and should read as forwarded; use /forward to pass on a message you have.

Received media

Images, videos, audio, documents and stickers a number receives are downloaded on demand: wuapi keeps what WhatsApp needs to fetch the file, and downloads it through the number's proxy only when someone asks for it. A busy group does not spend proxy traffic on files nobody opens, and a file is not lost when the proxy is having a bad moment as it arrives.

Until it is downloaded, the message's media has downloaded: false and media.url is https://api.wuapi.dev/v1/messages/{messageId}/media. That URL needs your API key. The first request downloads the file once and answers 302 to it; every later request, and media.url on the message from then on, points at the stored file, which needs no key. media.downloaded: true means url is the file itself, as for every file stored before on-demand media. Requests for the same file at the same time share one download.

curl -L -o photo.jpg https://api.wuapi.dev/v1/messages/j97d2k1x8p3m4q5w6e7r8t9y0u1i2o3p/media \
  -H "Authorization: Bearer wu_live_..."

1. mediaAutoDownload on the account says what is downloaded as soon as it arrives: none (nothing, the default for new accounts), all (everything, what accounts created before on-demand media keep), or {maxBytes, types} with types from image, video, audio, document, sticker. Change it with PATCH /v1/accounts/{accountId} or in the dashboard. It applies to messages received from then on.
2. While media.downloaded is false, fetching media.url needs the API key (Authorization: Bearer). No-code tools that download a URL without headers must add the key, or call GET /v1/messages/{messageId}/media?redirect=false and use the url it returns, which needs none.
3. Files over 12 MB are never downloaded up front, whatever mediaAutoDownload says: they are fetched on request only. A file larger than wuapi can download answers 413 media_too_large.
4. When a file mediaAutoDownload wants up front does not come through as the message arrives (a dropped connection, a bad proxy exit), wuapi retries in the background for about an hour. When it stores the file, message.media_downloaded fires with the message, media.downloaded true.
5. WhatsApp keeps a file for a limited time, about two weeks. A file nobody asked for in that time answers 410 media_expired.
6. A first download needs the account ready: while it reconnects the answer is 409 account_not_ready with Retry-After. A download that fails on the way (a dropped connection, a slow proxy exit) answers 503 media_download_failed with Retry-After; retrying usually works.
7. With Accept: application/json alone (the SDKs send it) or ?redirect=false, the answer is {object: "media", messageId, url, mimeType, filename, size} instead of the redirect.
8. media.size is the file's size in bytes, known before any download. media.width and media.height (pixels) and media.durationSeconds are null for received files for now: they are set only on an image sent through the API, once it is sent. Size a preview after downloading the file.
9. A GIF on WhatsApp is a short video: it arrives as type: "video" with media.gifPlayback: true, and a video sent with media.gifPlayback reads the same. Play it looped and muted, with no controls.
10. A file sent from the phone itself (source: phone) is handled like a received one.
11. A download is proxy traffic, metered like any other. The Inbox loads images as they scroll into view and other files on click.

Chats

GET /v1/accounts/{accountId}/chats lists an account's chats, the one with the newest message first: every conversation with a contact, a group or a channel that wuapi stored a message of. GET /v1/accounts/{accountId}/chats/{chatId} returns one. The account does not need to be connected for either.

curl https://api.wuapi.dev/v1/accounts/k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr/chats?unread=true&limit=20 \
  -H "Authorization: Bearer wu_live_..."

unread, unreadCount, pinned, archived and muted are null until wuapi has observed them. It learns them from changes as they happen (through the API, on the phone or on another device), not from the sync after linking, so a chat nobody has archived or pinned since the number was linked answers null, not false. archived=false and unread=false include those chats.

Actions

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, and the chat's state in GET .../chats follows at once.

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

A story is a WhatsApp Status: a text, image, video or voice post that lasts 24 hours. An account can post stories, read the ones its contacts post, tell a contact it saw theirs, reply and react to them, and see who viewed its own.

Post a story

Queued and paced like a send and stored as a message with chatId stories and chatType story. That message's id is also the story's id.

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.

story.viewed fires once per contact and story, story.reacted when a contact reacts. Viewers are what WhatsApp reports through read receipts: a contact with read receipts off is not listed, and with the account's own readReceipts privacy set to none, nobody is.

Contacts' stories

Once stories are turned on for an account, the stories its contacts post are stored for 24 hours from the time they were posted, apart from messages: they are not counted as received messages, they are in no chat and they never appear in GET /v1/messages. story.received fires when one arrives and story.deleted when its author deletes it early.

curl https://api.wuapi.dev/v1/accounts/k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr/stories?unviewed=true \
  -H "Authorization: Bearer wu_live_..."

1. A story's file is never downloaded when it arrives. media.downloaded is false and media.url is the media endpoint, which downloads the file through the number's proxy the first time it is asked for and keeps it until the story expires.
2. Viewing is explicit. Listing stories, reading one and downloading its file send nothing to WhatsApp. Only POST .../view puts the account on the story's viewer list, and wuapi never calls it on its own. Call it when a person actually opens the story.
3. WhatsApp ties story views to read receipts. With the account's readReceipts privacy set to none, a view is recorded for the account's own devices only, the author is not told, and the answer has authorNotified false.
4. A story the account opened on its phone shows viewedAt too, with authorNotified null.
5. A reaction goes to the story's author alone. That needs the account's own story privacy to be "My contacts" or "My contacts except" without excluding the author; otherwise the call answers 400 not_supported and nothing is sent.
6. A message that replies to a story carries replyToStoryId: your own replies, and a contact's reply to a story the account posted.
7. story_group.muted says the account muted that contact's stories on its phone. Muting and unmuting through the API is not supported.
8. Limits: 5,000 contacts' stories per account and 100 per contact at a time.

Contacts' stories are being turned on account by account. Until they are on for an account, GET .../stories answers an empty list and story.received does not fire; posting works either way.

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"]}'

The contact list is the address book of the linked phone, as WhatsApp synced it to wuapi: every contact the phone has a saved name or a business name for. It arrives when the number is linked (allow up to a few minutes) and follows every contact added, renamed or deleted on the phone after that. People the account only chatted with, without saving them, are not in it: they are in GET /chats. Each contact has savedName, profileName, phone (null when WhatsApp hides the number and only lid is known), and the username and pictureId wuapi has seen so far. about and deviceCount are null in the list: a lookup asks WhatsApp for those, and leaves savedName and profileName null.

curl https://api.wuapi.dev/v1/accounts/k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr/contacts?q=maria&limit=20 \
  -H "Authorization: Bearer wu_live_..."

Save contacts on the phone

PATCH /contacts/{contactId} with {savedName} saves a contact on the linked phone, as if it were saved there: it shows in WhatsApp and in the phone's own Contacts app, about a minute after WhatsApp takes it. firstName (the short name the phone shows) defaults to the first word of savedName. Any number with WhatsApp can be saved, not only the ones already in the address book; a lid:<digits> contact needs its number known. The change is queued and answered 202: the contact already carries the new savedName, and phoneSync says where the save stands: pending (queued, or waiting for an account that is reconnecting), synced (WhatsApp took it) or failed, with error.code not_on_whatsapp (the number has no WhatsApp), account_offline (the account went down for good, or stayed offline past its tolerance, before the change was sent) or save_failed. contact.updated fires with the whole contact when it is synced or failed. Saving the same name again changes nothing, so a retry is safe; send Idempotency-Key to get the first answer back. Removing a contact (savedName: null) is not supported: 400 not_supported. POST /contacts/batch queues up to 500 at once.

curl -X PATCH https://api.wuapi.dev/v1/accounts/k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr/contacts/%2B584241112233 \
  -H "Authorization: Bearer wu_live_..." \
  -H "Content-Type: application/json" \
  -d '{"savedName":"Maria Gonzalez"}'

Contact auto-save saves the contacts of new chats on its own. Turn it on with PATCH /v1/accounts/{accountId} and contactAutoSave: {enabled: true}. trigger is first_inbound (the contact's first message in a new direct chat, the default) or any_chat (any new direct chat, whoever writes first). nameTemplate is the saved name, with {profileName} (the contact's WhatsApp name) and {phone} (E.164); when it needs a profile name the contact has not set, fallbackName is used (default {phone}). Only direct chats with a number count, never groups, channels or stories. A contact the phone already holds a name for is never renamed, and a contact is auto-saved at most once: renamed or deleted on the phone later, it is not written again. Auto-saves go out a few minutes apart, at most dailyLimit (200) per account and UTC day; the rest wait for the next day. POST /contacts/auto-save/backfill queues the contacts of the chats the account already has, with the same rules.

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, and so does the outcome of a save on the phone (phoneSync). 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}'

Every group says where it belongs: communityId is the id of its community (null when it is in none, and on the community itself) and default is true for the community's announcement group. Both come with GET /groups, so one list is enough to show an account's groups by community. communityId on POST /groups cannot be combined with community: true: 400 invalid_request. It answers 400 not_supported, with nothing created, for an account that cannot create groups inside a community yet.

A group linked to a community or unlinked from it arrives as group.updated, with subgroups_linked or subgroups_unlinked in changes, the subgroups' ids in linked or unlinked and the community in communityId.

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.

Message retention

wuapi keeps each stored message for a limited time, then deletes the oldest automatically: 7 days on the Free plan and 30 days on a paid subscription. GET /v1/messages, GET /v1/chats and the Inbox return only messages still inside that window; once a message ages out it is gone and cannot be fetched again (WhatsApp does not re-send old messages). Plan for this: if your agent needs a lasting record, keep messages on your side as the message.received and message.sent webhooks deliver them.

1. The window covers every stored message, including conversations pulled in by history sync.
2. The extended-retention add-on raises it to 90, 180 or 365 days, chosen by the account owner in the dashboard (Billing → Add-ons). It needs a paid subscription.
3. Deletion is automatic and permanent. There is no endpoint to restore a deleted message, and the window is set from Billing, not the API.
4. Only the stored message is pruned. Usage counters, and anything you have already received over webhooks, are unaffected.

Favorite stickers

The account's favorite stickers are the star tab of WhatsApp's sticker picker. WhatsApp keeps that list in sync between the phone and its linked devices, so wuapi has it too: a client can show the same stickers the person sees on their phone, favorite a new one and remove one, and the phone follows.

curl https://api.wuapi.dev/v1/accounts/k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr/stickers/favorites?limit=50 \
  -H "Authorization: Bearer wu_live_..."

1. wuapi reads the list from WhatsApp once after a number is linked, a minute or two after the account is ready, and after that applies every change the phone or another linked device makes, as it happens. Until that first read the list is empty. A number that was linked before this existed gets its list the same way, without relinking.
2. sticker.favorites_updated fires when the list changes: reason added with the sticker, removed with its stickerId, or synced with counts when the whole list was read again. One event per change and one for a whole sync, never one per sticker.
3. A favorite is a reference to a file on WhatsApp. media.downloaded is false and media.url is the endpoint above until someone asks for the file; then wuapi stores it, media.url is the file itself and downloaded is true. The first fetch needs the account ready and counts toward the account's 60 first downloads per minute, shared with message media: fetch what a picker shows, not the whole list at once.
4. animated and emojis are null until wuapi has the file, because WhatsApp's list does not carry them: the file does. lottie: true marks a vector sticker (application/was), which needs a Lottie player to draw.
5. WhatsApp does not keep files forever. A favorite whose file is gone answers 410 media_expired and its media.url becomes null. Favoriting it again from a message or a file gives it a new one.
6. Adding and removing write to WhatsApp, so the account must be ready, and the change shows on the phone. Both can be repeated: a sticker that is a favorite already answers the same favorite and sends nothing, Idempotency-Key replays the first answer, and removing a removed favorite answers 204. At most 30 changes per minute per account.
7. To favorite a file of your own, upload a WebP (mimeType: image/webp, at most 2 MB; WhatsApp shows stickers at 512x512) and pass its uploadId. wuapi uploads it to WhatsApp from the number, which is proxy traffic like sending it.
8. Favorite stickers are being turned on account by account. For an account that does not have them yet, the list is empty, sticker.favorites_updated does not fire, and POST and DELETE answer 400 not_supported.
9. WhatsApp has no synced list of recent stickers: each app builds its own from the stickers it sent. A client can do the same from the sticker messages it sends.

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

Changed on 2026-10-15: every contact has phoneSync (null unless a name was saved on the phone through wuapi), and contact.updated also fires when such a save is synced or failed, with the whole contact. See Contacts.

Changed on 2026-09-30: received media is on demand for accounts created from that day (mediaAutoDownload none). In message.received, media.downloaded is false and media.url is GET /v1/messages/{messageId}/media, which needs your API key: send Authorization: Bearer when you download it, or call it with ?redirect=false and use the keyless url it returns. Accounts created before keep mediaAutoDownload all and the old behavior. New event: message.media_downloaded. See Received media.

No public HTTPS endpoint? Use Streams: the same events over one connection your code opens (/docs#streams).

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

Incoming webhooks go the other way: a secret URL that sends a WhatsApp message from one of your numbers to one fixed contact or group, for a script, CI or a monitoring tool that cannot hold an API key. Create them in the dashboard (Integrations, Incoming webhooks, or a chat's menu in the Inbox) or with POST /v1/incoming-webhooks {accountId, name, to}. POST a JSON {"text": "..."} (content works too, with an optional https imageUrl) or a plain text body to the returned url, with no API key. It answers 202 once the message is queued, and the normal outbox applies: pacing, plan limits, and waiting for a reconnect. Repeat the Idempotency-Key header to retry safely (200 with Idempotent-Replayed: true). A hook sends up to 60 messages per minute, an organization can have 50, and PATCH /v1/incoming-webhooks/{incomingWebhookId} with rotateUrl: true replaces a leaked URL.

curl -X POST https://api.wuapi.dev/v1/incoming-webhooks \
  -H "Authorization: Bearer wu_live_..." \
  -H "Content-Type: application/json" \
  -d '{"accountId":"k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr","name":"Deploys","to":"+584121234567"}'

{
  "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. What each disconnectReason means and what to do about it is in Troubleshooting connections.

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
  }
}

Streams

Streams deliver the same events as Webhooks over one HTTPS request that your code keeps open: GET https://stream.wuapi.dev/v1/events/stream. Each event is a Server-Sent Events frame whose data is the webhook envelope, unchanged. Use Streams when your code has no public HTTPS endpoint: local development, a desktop or CLI app, a worker behind NAT, an agent. They are included in the Free plan.

Webhooks or Streams

Do not poll for events. Polling with 2 requests every 4 seconds is 43,200 requests a day against the limit of 600 requests a minute per API key, and an event still arrives up to 4 seconds late. A stream connection costs one connect attempt.

Connect

Send the key in the Authorization: Bearer header. A key in the URL is refused with 401 and never logged. Wuapi-Project scopes an organization key to one project, as on every other route; a project key sees its own project. A stream starts from the moment it opens: events from before it are read through REST.

With an SDK the client is one call: events.stream in @wuapidev/sdk (TypeScript) and in the wuapi crate (Rust), from version 0.13. It opens the stream, reconnects with the last id, waits the retry and Retry-After times, deduplicates, and tells you about a reset. It stops only for what waiting cannot fix, such as a refused key. In any other language the rest of this section is the whole client, and the Node.js tab is one written by hand.

import { StreamError } from "@wuapidev/sdk"

const stream = wuapi.events.stream(
  { types: ["message.received", "message.read"] },
  {
    onStatus: (status) => {
      // The cursor was too old: read what you missed through REST (GET /v1/messages). The stream goes on live.
      if (status.type === "reset") console.warn("resync:", status.reason)
      if (status.type === "reconnecting") console.warn("stream " + status.reason + ", back in " + status.delayMs + " ms")
    },
  },
)

try {
  for await (const event of stream) {
    console.log(event.type, event.data.object.id) // typed by the filter
    // stream.lastEventId is the cursor: pass it as lastEventId to resume after a restart
  }
} catch (err) {
  // Only what waiting cannot fix ends the loop: a bad key, a suspended organization, a wrong filter.
  if (err instanceof StreamError) console.error(err.kind, err.message)
  else throw err
}

Frames

Every stream starts with retry: 3000. An event is a frame with id (an opaque cursor: keep it as a string), event (the type) and data (the envelope, one JSON line). A line that starts with a colon is a heartbeat, sent every 15 seconds when nothing else is. It can carry an id too, so a filtered stream still holds a fresh cursor.

Reconnect and resume

Keep the last id. After a disconnect, wait the retry time and reconnect with Last-Event-ID set to it; a client that cannot set that header can pass ?cursor=<id>. Within 28 minutes wuapi replays what you missed, then goes live. Delivery is at-least-once: a replay can repeat an event, so deduplicate on the evt_ id in data, as you do with Webhooks. The server can close a stream at any time, for a deploy or after a long run, and says how long to wait with retry: reconnect with the last id and nothing is lost.

A cursor older than 28 minutes can get a frame event: reset with data: {"reason": "cursor_expired"} and no replay: wuapi keeps events 30 minutes, but it refuses a resume that close to the end of that time, and one past it always gets the frame. A cursor wuapi never issued (cursor_unknown) or one from a period when nothing was kept (not_logged) gets it too. Read what you missed through REST, then carry on: the stream continues live right after the frame.

Filters

The types and accounts query parameters limit a stream to those event types and accounts: up to 50 values each, repeated or comma separated, as in ?types=message.received,message.sent&accounts=<accountId>. Presence events (chat.presence_updated, contact.presence_updated) are not sent on Streams, so naming one in types answers 400, as does webhook.test or a type that does not exist.

Limits

Errors before the stream opens

Nothing is streamed and the body is the usual {code, message, details?}:

A web app

A browser's native EventSource cannot set the Authorization header, and the key must not go into a URL. A web app goes through its backend: the backend opens the stream with the key and passes the events on to the page. Never put the key in front-end code.

Streams keep events for 30 minutes, a connection can resume within 28, and presence events are never sent. For history, use REST. In a terminal, npx @wuapidev/cli events stream prints each event as one JSON line.

Events

Webhooks and Streams carry the same events, in the same envelope. 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,
    "footer": null,
    "buttons": null,
    "button": null,
    "mentions": [],
    "forwarded": false,
    "forwardedManyTimes": false,
    "viewOnce": false,
    "starred": false,
    "replyToMessageId": null,
    "replyToStoryId": 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,
    "footer": null,
    "buttons": null,
    "button": null,
    "mentions": [],
    "forwarded": false,
    "forwardedManyTimes": false,
    "viewOnce": false,
    "starred": false,
    "replyToMessageId": null,
    "replyToStoryId": 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,
    "footer": null,
    "buttons": null,
    "button": null,
    "mentions": [],
    "forwarded": false,
    "forwardedManyTimes": false,
    "viewOnce": false,
    "starred": false,
    "replyToMessageId": null,
    "replyToStoryId": 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,
    "footer": null,
    "buttons": null,
    "button": null,
    "mentions": [],
    "forwarded": false,
    "forwardedManyTimes": false,
    "viewOnce": false,
    "starred": false,
    "replyToMessageId": null,
    "replyToStoryId": 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,
    "footer": null,
    "buttons": null,
    "button": null,
    "mentions": [],
    "forwarded": false,
    "forwardedManyTimes": false,
    "viewOnce": false,
    "starred": false,
    "replyToMessageId": null,
    "replyToStoryId": 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,
    "footer": null,
    "buttons": null,
    "button": null,
    "mentions": [],
    "forwarded": false,
    "forwardedManyTimes": false,
    "viewOnce": false,
    "starred": false,
    "replyToMessageId": null,
    "replyToStoryId": 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,
    "footer": null,
    "buttons": null,
    "button": null,
    "mentions": [],
    "forwarded": false,
    "forwardedManyTimes": false,
    "viewOnce": false,
    "starred": false,
    "replyToMessageId": null,
    "replyToStoryId": 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": "message",
    "id": "j97d2k1x8p3m4q5w6e7r8t9y0u1i2o3p",
    "projectId": null,
    "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
    "chatId": "+584241112233",
    "chatType": "direct",
    "direction": "inbound",
    "source": "contact",
    "from": "+584241112233",
    "to": "+584121234567",
    "profileName": "Maria",
    "username": null,
    "type": "image",
    "text": null,
    "media": {
      "url": "https://files.wuapi.dev/api/storage/3f2a9c1e-5b7d-4e8a-9c0f-1a2b3c4d5e6f",
      "mimeType": "image/jpeg",
      "filename": null,
      "size": 184320,
      "width": null,
      "height": null,
      "durationSeconds": null,
      "gifPlayback": false,
      "downloaded": true
    },
    "location": null,
    "contact": null,
    "contacts": null,
    "poll": null,
    "calendarEvent": null,
    "footer": null,
    "buttons": null,
    "button": null,
    "mentions": [],
    "forwarded": false,
    "forwardedManyTimes": false,
    "viewOnce": false,
    "starred": false,
    "replyToMessageId": null,
    "replyToStoryId": 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": "story",
    "id": "s97fd2k4w8qc1n5x7v3b9yt6r0hjm2ea",
    "projectId": null,
    "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
    "contactId": "+584241112233",
    "own": false,
    "profileName": "Maria",
    "username": null,
    "type": "image",
    "text": "New menu this week",
    "backgroundColor": null,
    "font": null,
    "media": {
      "url": "https://api.wuapi.dev/v1/accounts/k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr/stories/s97fd2k4w8qc1n5x7v3b9yt6r0hjm2ea/media",
      "mimeType": "image/jpeg",
      "filename": null,
      "size": 184320,
      "width": 1080,
      "height": 1920,
      "durationSeconds": null,
      "downloaded": false
    },
    "status": "received",
    "viewedAt": null,
    "authorNotified": null,
    "reaction": null,
    "viewCount": null,
    "postedAt": "2026-09-24T14:02:11.000Z",
    "expiresAt": "2026-09-25T14:02:11.000Z",
    "deletedAt": null,
    "createdAt": "2026-09-24T14:02:11.000Z"
  }
}

{
  "object": {
    "object": "story",
    "id": "s97fd2k4w8qc1n5x7v3b9yt6r0hjm2ea",
    "projectId": null,
    "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
    "contactId": "+584241112233",
    "own": false,
    "profileName": "Maria",
    "username": null,
    "type": "image",
    "text": null,
    "backgroundColor": null,
    "font": null,
    "media": null,
    "status": "received",
    "viewedAt": null,
    "authorNotified": null,
    "reaction": null,
    "viewCount": null,
    "postedAt": "2026-09-24T14:02:11.000Z",
    "expiresAt": "2026-09-25T14:02:11.000Z",
    "deletedAt": "2026-09-24T15:10:00.000Z",
    "createdAt": "2026-09-24T14:02:11.000Z"
  }
}

{
  "object": {
    "object": "story_viewer",
    "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
    "storyId": "j97d2k1x8p3m4q5w6e7r8t9y0u1i2o3p",
    "contactId": "+584241112233",
    "viewedAt": "2026-09-24T14:20:05.000Z",
    "reaction": null,
    "reactedAt": null
  }
}

{
  "object": {
    "object": "story_viewer",
    "accountId": "k57a8m2x9d3f0q1wjh6ypc4n2d7s0vbr",
    "storyId": "j97d2k1x8p3m4q5w6e7r8t9y0u1i2o3p",
    "contactId": "+584241112233",
    "viewedAt": "2026-09-24T14:20:05.000Z",
    "reaction": "💚",
    "reactedAt": "2026-09-24T14:20:30.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,
      "footer": null,
      "buttons": null,
      "button": null,
      "mentions": [],
      "forwarded": false,
      "forwardedManyTimes": false,
      "viewOnce": false,
      "starred": false,
      "replyToMessageId": null,
      "replyToStoryId": 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,
    "communityId": null,
    "default": 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",
    "communityId": null,
    "actorId": "+584241112233",
    "added": [
      "+584141234567"
    ],
    "removed": [],
    "promoted": [],
    "demoted": [],
    "linked": [],
    "unlinked": [],
    "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"
  }
}