API reference

Authentication

Every request carries an API key as a bearer token. The key decides the workspace, so there is no workspace parameter to get wrong.

Create a key in the app under Developers → API keys. The full value is shown once at creation and can never be read again — store it in your secret manager.

A new key can use the whole API. You can narrow it to specific scopes when an integration should reach less than that; a request outside its scopes is refused with 403. Keys are workspace-bound either way: they cannot read or write another workspace, and an X-Workspace-Id header is ignored on this API.

Revoking a key is permanent — it starts failing with 401 immediately and cannot be restored. To rotate, create the replacement first, switch your systems over, then revoke the old one.

Send keys only from your server. A key in browser or mobile code is a leaked key.

Idempotency

Optional, and worth sending: an Idempotency-Key makes a retry safe. Without one a request simply runs.

Networks time out after the message was already queued. Retrying then sends it twice — and your customer sees it twice. An Idempotency-Key removes that risk: repeat the same key and body and you get the stored response back with Idempotency-Replayed: true, nothing is sent again.

Use a value your own system can regenerate for the same intent, such as the order you are notifying about — order-4472-shipped, not a fresh random string. That is what makes the retry match.

Reusing a key with a different body is refused with 409: it means two different messages were about to share one identity. Keys are scoped to the API key, method and path, and must be 8 to 255 characters of A-Z, a-z, 0-9, dot, underscore, colon or hyphen.

Errors

Errors are JSON with a human-readable message. Validation failures also carry a field-keyed errors object.

Send Accept: application/json on every request so failures come back as JSON rather than an HTML error page.

Messages are safe to show to your own operators. They never contain bearer values, request bodies or engine internals.

Retrieve the workspace

Returns the workspace the key belongs to. Useful as a health check right after you create a key.

List contacts

Paginated contacts for the workspace, newest activity first.

Create or update a contact

Upserts by phone number. Sending a message to a new number creates the contact for you, so call this only when you want to set a name, consent or metadata.

Consent is preserved unless you send it explicitly. Set opted_in only when you hold a real opt-in for that number — it is what unlocks campaigns, and it is recorded in the workspace consent ledger with this API key as the source.

Upload media

Uploads a file, scans it for malware and stores it — in one call. The returned id is ready to attach to a message. Only needed when you send the same file more than once; otherwise attach it straight to the send.

Send the file as multipart/form-data under the field name file. The response returns only once the file is scanned and retained, so a 201 means the media is safe to send.

An infected or unsupported file is refused and never stored. Media you upload is retained for the period your plan allows and then deleted.

Send a message

Queues one WhatsApp message. Address it by phone number or contact id, and send text, a file, or both.

Give a recipient phone number and the contact is created for you — no separate call. Send contact_id instead when your system already stores our ids. Send one or the other, never both.

Attach a file directly as file and it is uploaded and scanned inline — one call, nothing to wire up first. Send the same file to many people instead by uploading it once through POST /media and passing media.attachments[].media_id, up to 10 of them.

A message needs at least one of body, file or media.attachments.

A 202 means the message is queued and handed to the number you chose. It is not proof of delivery: delivery and read state arrive later through webhooks.

Sends are paced per number to protect these session-based numbers from spam detection — a queued message is released within your workspace sending policy (per-number hourly/daily cap and a small random gap), so on a busy number or large batch it can leave a little after this call. Configure it in your workspace settings.

This endpoint is for messages your relationship justifies — order updates, replies, receipts. It sends to contacts whose consent is still unknown, but it will never reach a contact who opted out or is on the suppression list. Marketing to a list is what campaigns are for, and those require a recorded opt-in.

Message log

Paginated log of every message the workspace sent or received, newest first, with delivery outcome and timeline.

List groups

The WhatsApp groups your connected numbers belong to, largest first.

Groups are joined, renamed and left on the phone, so this list is a mirror of what your numbers report — there is nothing here to create or delete. Call POST /groups/sync to re-read it.

participant_count is a count and nothing more. Group members never contacted your workspace and never consented to being on file here, so their numbers are counted when the list is read and then discarded. There is no endpoint that returns them because there is no table that holds them.

can_send tells you whether this number may post. It is false for an announcement group where your number is not an admin — WhatsApp would drop such a message without reporting an error.

Refresh groups from the phone

Re-reads every connected number's group list from its phone and replaces the stored mirror.

This runs across every connected number, because the API deliberately exposes no connection ids. Each number is attempted on its own, so one being offline does not cost you the others — the numbers array reports each outcome.

A group your number has left is removed, not left behind as a row that has quietly stopped being true. Messages already sent to it go with it.

The call is a refresh, so running it twice is the same as running it once. It needs no Idempotency-Key.

Message a group

Posts one text message into a group. Every member receives it.

Use the id from GET /groups. Text only — attachments to a group are not offered.

It costs one message from the same plan allowance as any other send, however many members are in the group.

A 202 means the message was queued and handed to the number. Its status ends at sent: WhatsApp acknowledges a group message once but then returns a receipt per member, so there is no honest delivered or read state for a group and none is reported.

The send is refused with 422 when the group only lets admins post and your number is not one, and when the number the group belongs to is not connected. Both are refused before anything is queued, because WhatsApp would otherwise accept the message and drop it silently.

It carries its own scope, groups:send, rather than riding on messages:write. One call here reaches every member of a group, none of whom opted in to anything with you — that is a different power from messaging one customer.