API reference

Everything you need to send and receive WhatsApp messages from your own software. One base URL, one API key, plain JSON. The interactive reference below is generated from this server's OpenAPI spec, so it always matches what's deployed.

Getting started

Three things, in order:

The response is 202 Accepted with the message object. Sends are queued and paced (see Sending speed); the message's status moves through queued → sent → delivered → read, and you can watch it via webhooks or the Logs page.

Authentication

Every request carries your key in the Authorization header:

Authorization: Bearer sk_live_…

Keys belong to the account, not to a number — one key can drive every number you connect. Create one key per integration (one for Sheets, one for n8n, one for your CRM) so revoking one never breaks the others. There is no rate limit on API calls themselves; the limits that matter are the per-number sending caps described under Sending speed.

Sending messages

One endpoint sends everything: POST /v1/phones/{id}/messages. The body has to (a phone number with country code, in any format, or a group JID) and content, whose kind chooses the type.

Idempotency. Send an Idempotency-Key header (any unique string, e.g. your order id) and a retried request returns the original result instead of sending twice. Use this from anything that might retry — Sheets scripts, queue workers, flaky networks.

Quoting. Add "replyTo": "<waMessageId>" to quote an earlier message (yours or theirs) so the bubble shows the reply context.

Content types

Buttons & lists

Interactive messages let a recipient answer with a tap. The id you give each button comes back verbatim in the message.received webhook as data.reply.id — route on that, never on the label text, so translations and wording changes don't break your flow.

Sending speed & warm-up

Bulk-sending from a fresh number is how numbers get banned. PulseApi paces every number automatically along a warm-up ladder: a small daily cap and a gap between messages on day one, opening up over a month of normal use. Messages beyond today's cap simply wait in the queue and go out tomorrow — nothing is dropped.

A number that has been on WhatsApp for years is not a day-zero risk. Toggle Established number on the Numbers page and it starts at the day-7 rung. GET /v1/phones/{id} returns the live figures under throughput, and GET /v1/phones/{id}/queue shows what's waiting and how long it will take.

Anti-ban: how numbers get banned

WhatsApp never publishes its rules, but years of operating numbers through unofficial APIs show the same handful of patterns behind almost every ban. Knowing them is most of the defence.

Rules of thumb

How Safe Mode works

Safe Mode is on by default for every number. It does four things, each aimed at a specific machine fingerprint:

Together with the warm-up ladder, this is the same behaviour you'd get from a careful human operator — just applied to every message without anyone having to think about it. Everything is configurable per number on the Anti-Ban page, or via PATCH /v1/phones/{id} with safeMode, quietHours and pacing.

Proxies per number

Every WhatsApp number linked through PulseApi connects from your server's IP. One number from one IP looks like a normal linked device. Ten numbers from the same IP look like a farm — and when one gets flagged, its neighbours tend to follow. A proxy gives each number its own exit address, ideally in the same country as the SIM.

Set it per number on the Anti-Ban page or with PATCH /v1/phones/{id} and "proxyUrl": "http://user:pass@host:port" (also socks5://). The number reconnects through the proxy immediately; pass null to go direct again. Credentials are stored on your server and never shown back in full. POST /v1/phones/{id}/proxy-test checks a URL without saving it.

Webhooks

Register a URL on the Webhooks page (or POST /v1/webhooks) and choose events. Each event is a JSON POST to your URL. Respond with any 2xx within 10 seconds; anything else is retried with backoff, and you can see and re-send every delivery on the Logs page.

Verifying signatures

Every delivery carries x-pulseapi-signature: t=<unix seconds>,v1=<hex>, where the hex is HMAC-SHA256 of "<t>.<raw body>" with your endpoint's secret (shown once when you create it). Verify it before trusting a payload, and reject timestamps older than five minutes to defeat replays.

Apps Script can't read request headers, so for Google Sheets use a secret in the URL instead (?key=…) — the Sheets template does this for you.

Errors

Errors are JSON with a stable code you can branch on and a human message:

{ "error": { "code": "unprocessable", "message": "Phone is disconnected. It must be connected before it can send.", "details": null } }

Google Sheets, n8n, Make

Google Sheets. The dashboard's Connect page has a ready template: paste one script, fill three cells, and a PulseApi menu appears in the sheet for sending texts, images and buttons to every row — with auto-replies on button taps.

n8n / Make / Zapier. Use an HTTP Request node with Header Auth (Authorization: Bearer …), or import the OpenAPI spec so every endpoint appears as a typed action. For inbound, point a Webhook trigger node's URL at PulseApi → Webhooks.

Postman. Download the collection, set the baseUrl and apiKey variables, and every request works.

Contacts & Google sync

PulseApi keeps an address book per account. Fill it three ways: import a CSV (any file with a header row — Google Contacts, Outlook and Excel exports all work; columns are matched by name in any order), sync Google Contacts (read-only OAuth; nothing is written back to Google), or add by hand. Numbers are normalised to digits with a country code so duplicates collapse.

From the Contacts page you can search, tag, bulk-check who is on WhatsApp through one of your numbers (remembered per contact), send a quick message, and export everything back to CSV. The same data is on the API under /v1/contacts.

Enabling Google sync (operator, once)

Refresh tokens are stored encrypted at rest. Disconnecting removes the token; synced contacts stay.

Migrating from Maytapi

PulseApi answers Maytapi's sendMessage call exactly as Maytapi does, so software already written against Maytapi moves over by changing its base URL and three credential values. No code change, no new SDK.

The call

POST {base}/api/{product_id}/{phone_id}/sendMessage
x-maytapi-key: sk_live_…
content-type: application/json

{"to_number": "919830000001", "type": "text", "message": "Hello 👋"}

Media is the same shape as Maytapi's: type media, message either an http(s) URL or an inline data:image/jpeg;base64,… URI (also PDF, PNG, MP4), text as the caption and filename as the name the recipient sees. Inline files up to 32 MB are stored on the server and sent from there, so the queue never carries the base64. Numbers are bare digits with the country code, exactly as Maytapi takes them.

The answer

HTTP 200
{"success": true, "data": {"chatId": "919830000001@c.us", "msgId": "msg_…", "phoneId": 10001}}

200 means the message is queued and paced like every other PulseApi message; the WhatsApp delivery status arrives on webhooks and in Logs. Anything that could not be queued is a non-200 with {"success": false, "message": "…"}, so a caller that only checks the status code and one that only reads success both see the same thing. A number that is briefly reconnecting still accepts messages (they wait for the session); one that has been logged out returns 422 until it is scanned again.

What is and is not covered

Covered: text, media (URL or inline), location ("lat,lng" in message). Not covered on this endpoint: polls, buttons, lists, contacts, and Maytapi's status, QR, contact and group endpoints — use the native API for those; it has all of them and more. Inbound messages are the native webhooks (message.received carries the receiving phone, the sender's bare number, text, timestamp and a fromMe flag), which is what a reply-matching integration needs.

Several sending identities

Maytapi installations often send from more than one number on purpose — an office number for staff, a public one for customers. In PulseApi that is one account with several numbers, each with its own phone_id. Create one API key per identity (named "staff", "client", …) so each can be revoked alone; every key on the account works with every number, so the fallback chain in your software keeps working unchanged.

Running both during the switch

The same WhatsApp number can be linked to Maytapi and PulseApi at once (each is one linked device, out of four). Sending works independently. Inbound messages, however, arrive at both, so keep only one side's webhook wired to any auto-reply until Maytapi is unlinked.

FAQ