✓ Connected. Your WhatsApp is linked and ready.
Add webhook
Send a test message
No templates yet.
No contacts yet.
No broadcast lists yet. Create one to get started.
Nothing sent yet.
No recipients yet.
No per-number detail was recorded for this send.
Your API key
This shows your key's prefix and status only — the full value can't be retrieved after it's issued. Regenerate to get a brand-new key, revealed once.
Base URL
All endpoints below are relative to this address.
—
Authentication
Send both headers on every request. Keep your API key on your server — never in browser or mobile code.
—
YOUR_API_KEY
Your API key is issued by the platform operator. It is never shown here — ask them if you need it again.
A missing, unknown or mismatched key returns 401 UNAUTHORIZED. Admin keys are rejected here.
Quick start
Session
Your WhatsApp connection. Call connect, then poll status until it reports connected.
/api/v1/session/connect
Starts the session. Returns { status: "qr", qr } or { status: "connected" }./api/v1/session/status
Returns { status: "connected" | "qr" | "disconnected", qr? }. qr is a base64 data URL, present only while pending./api/v1/session/disconnect
Returns { status: "disconnected" }.Messages
/api/v1/messages/send
Body { to, type, ... }, where to is always required and an omitted type means text. Returns { messageId }.{
"to": "+237 690-000-000",
"message": "Your code is *123456*"
}
Numbers are normalised automatically, so spaces, dashes and a leading 00 are all fine. An unparseable number returns 422 UNPROCESSABLE. WhatsApp markdown is supported: *bold*, _italic_.
Add a type to send anything else. Every type keeps the same endpoint and the same to field:
text
The default when no type is given.image · video · audio · document · sticker
Send a media URL or an inline upload, never both. Captions apply to image, video and document; a file name applies to document. Uploads are capped at 5 MB.location
Latitude and longitude are required; address and description are optional.contact
Both the contact name and the contact number are required.{ "to": "…", "type": "text", "message": "Your code is *123456*" }
{ "to": "…", "type": "image", "url": "https://example.com/photo.jpg",
"caption": "Optional" }
{ "to": "…", "type": "document", "base64": "JVBERi0…", "mimetype": "application/pdf",
"filename": "invoice.pdf" }
{ "to": "…", "type": "location", "latitude": 4.0511, "longitude": 9.7679,
"address": "Douala, Cameroon" }
{ "to": "…", "type": "contact", "contactName": "Ada", "contactNumber": "+237690000001" }
A message missing the fields its type needs returns 422 UNPROCESSABLE naming what is missing.
Webhooks
Receive WhatsApp events on your own endpoint.
/api/v1/webhooks/api/v1/webhooks
Body { url, events[], secret? }. url and at least one event are required./api/v1/webhooks/:id
Returns 204.Events: message.received, message.sent, message.ack, message.revoked, session.status, session.authenticated, session.disconnected, group.join, group.leave, group.update.
Broadcasts
Reusable recipient lists you can send to repeatedly.
/api/v1/broadcasts
Lists with recipientCount, lastJobAt, lastJobStatus./api/v1/broadcasts
Body { name, recipients[], fromTags? }. fromTags names contacts by tag; every contact carrying any of them is added alongside recipients. Returns 201./api/v1/broadcasts/:id
Full list including every recipient, plus names — a phone-to-name map covering the recipients that have one./api/v1/broadcasts/:id
Body { name?, recipients? }./api/v1/broadcasts/:id
Returns 204./api/v1/broadcasts/:id/recipients
Body { phones[], name?, fromTags? }. Duplicates are removed automatically. The optional name labels the contact, and applies only when phones holds exactly one number. fromTags works as on create above./api/v1/contacts/:phone
Body { name?, tags? }. Sets the display name and/or tags for a number across every list this agency owns; an empty name clears it. URL-encode + as %2B./api/v1/contacts
Query search, tag, limit, offset. Returns { items, total }./api/v1/contacts
Body { phone, name?, tags? }. 409 if the number is already a contact./api/v1/contacts/tags
Every tag this agency uses, with its contact count./api/v1/contacts/:phone/lists
The broadcast lists this number is on./api/v1/contacts/:phone
Deletes the contact and removes the number from every list. Returns { removedFromLists }./api/v1/contacts/bulk
Body { contacts: [{ phone, name?, tags? }] }. Rejected whole if any number is invalid./api/v1/contacts/whatsapp
Your saved WhatsApp contacts, unwritten: { total, preview }. Needs a connected session, else 409./api/v1/contacts/whatsapp
Imports them: { total, added, updated }. Fills blank names, never replaces a name or tags you have set./api/v1/broadcasts/:id/recipients/:phone
URL-encode + as %2B./api/v1/broadcasts/:id/subscribe
Body { phone }. 201 when added, 200 when already subscribed./api/v1/broadcasts/:id/unsubscribe
Body { phone }. Idempotent — always 200./api/v1/broadcasts/:id/send
Body { message }. Returns 202 with a job./api/v1/broadcasts/jobs
Every send this agency has made, newest first, each with its list name and its sent/failed counts. A send whose process died reports interrupted./api/v1/broadcasts/jobs/:jobId
Summary of one send: list name, message, counts, status and timing./api/v1/broadcasts/jobs/:jobId/recipients
One page of per-recipient detail — status, attempt count, message id or failure reason, and time. Filter with status and search, page with limit and offset./api/v1/broadcasts/:id/jobs
Send history for the list./api/v1/broadcasts/:id/jobs/:jobId
Live progress: sent, failed, progressPct, etaSeconds.Messages are paced several seconds apart, spaced unevenly on purpose, and the interval is set by the platform operator — so a send takes hours, not minutes. GET /api/v1/broadcasts/pacing reports the current figures. Poll the job endpoint for progress rather than waiting on the send call.
Errors
Every failure returns the same shape:
{ "error": { "code": "UNAUTHORIZED", "message": "..." } }
| Status | Code | Meaning |
|---|---|---|
| 400 | BAD_REQUEST | Malformed request |
| 401 | UNAUTHORIZED | Missing, unknown or mismatched credentials |
| 404 | NOT_FOUND | No such list or webhook |
| 409 | SESSION_UNAUTHENTICATED | WhatsApp not linked yet — scan the QR first |
| 422 | UNPROCESSABLE | Invalid body or phone number |
| 502 | SEND_FAILED | The WhatsApp gateway is unreachable |
| 503 | CAPACITY | Server at capacity — retry shortly |
| 500 | INTERNAL | Unexpected server error |