Platform API (agencies and SaaS)
The platform API is for agencies and software companies that run WhatsApp for many businesses. Each of your customers is a client account under your login, with its own WhatsApp number, plan and wallet. From your own software you can create those clients, send each one a connect link, follow their status and get each client’s own API credentials for sending messages.
Before you start
Section titled “Before you start”- Switch on client management: click your profile picture, choose Edit Profile, open Account type, pick the agency or SaaS option and click Save. See Account types.
- Open Clients and click API keys, then Make key. Copy the key straight away: it is shown only once. You can have five active keys; delete one to stop it working.
| Base URL | https://app.wabot.shop/platform/v1 |
| Authentication | Authorization: Bearer wbp_… |
| Rate limit | 120 requests per minute per key |
A key acts as your login: it only reaches your own client accounts, and stops working when you delete it or switch client management off. Keep it on your server, never in a browser or app.
Create a client
Section titled “Create a client”curl -X POST https://app.wabot.shop/platform/v1/clients \ -H "Authorization: Bearer $WABOT_PLATFORM_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Lumiere Cafe", "country": "Brazil", "external_id": "cust-42", "contact": { "name": "Ana Souza", "email": "ana@example.com" } }'{ "success": true, "client": { "id": 466, "external_id": "cust-42", "name": "Lumiere Cafe", "ready": false }}| Field | ||
|---|---|---|
name |
required | The client’s business name. |
country |
required | Country name, as in the app. It sets the client’s plans and prices. |
currency |
optional | Three letters, e.g. BRL. Defaults to your own account’s. |
timezone |
optional | e.g. America/Sao_Paulo. Defaults to your own account’s. |
business_type |
optional | Defaults to other. |
external_id |
optional | Your own id for this customer: letters, digits and . _ : @ -, up to 100 characters, unique among your clients. |
contact |
optional | name, email, phone of the client’s contact. With an email, connect and payment links can be emailed to them. |
The client’s account is set up in the background: ready turns true after about a minute (see Read clients).
Get the client’s number connected
Section titled “Get the client’s number connected”curl -X POST https://app.wabot.shop/platform/v1/clients/466/connect-link \ -H "Authorization: Bearer $WABOT_PLATFORM_KEY" \ -H "Content-Type: application/json" \ -d '{ "send_email": false }'{ "success": true, "url": "https://app.wabot.shop/connect/Xw9…", "emailed": false, "link": { "id": 12, "status": "sent", "expires_at": "2026-11-23T10:00:00.000Z" }}Send url to your customer. They open it, log in with Facebook, choose their business and connect their number. They don’t need a Wabot login. The URL is returned only in this response.
- A link works for 7 days and connects one number. Making a new link cancels the previous one.
- With
"send_email": truethe link is also emailed to the client’s contact email. - Follow progress with
GET /clients/{id}:connect_link.statusgoessent→opened→connected, andwhatsapp.connectedbecomestrue. Or use webhooks.
| Field | ||
|---|---|---|
send_email |
optional | true to email the link to the client’s contact. |
return_url |
optional | Where the page sends your customer back when they finish (https; http only on localhost). See Connect from your own pages. |
origin |
optional | Your page’s origin, e.g. https://app.example.com, when you open the link in a pop-up. Defaults to the origin of return_url. |
expires_in_minutes |
optional | How long the link works: 10 to 10080 minutes. Defaults to 7 days. |
Connect from your own pages
Section titled “Connect from your own pages”Let your customers connect their number without leaving your product: your page opens the connect page in a pop-up and hears back when it’s done.
-
Add the script to your page:
<script src="https://app.wabot.shop/sdk/wabot-connect.js"></script> -
On your server, make the link with your page’s address. A short lifetime suits a pop-up:
Terminal window curl -X POST https://app.wabot.shop/platform/v1/clients/466/connect-link \-H "Authorization: Bearer $WABOT_PLATFORM_KEY" \-H "Content-Type: application/json" \-d '{ "return_url": "https://app.example.com/settings/whatsapp", "expires_in_minutes": 30 }' -
When your customer clicks your button, open it:
connectButton.addEventListener("click", () => {WabotConnect.open(// Ask your server for the link. The pop-up opens straight away, so browsers don't block it.() => fetch("/api/whatsapp/connect-link", { method: "POST" }).then((r) => r.json()).then((d) => d.url),{onConnected: ({ clientId, numbers }) => showConnected(numbers), // e.g. ["4321"]: last digitsonError: ({ code }) => showProblem(code), // "expired", "revoked", "used" or "no_link"onClose: () => {}, // closed before connecting},);});
You can also pass the URL itself: WabotConnect.open(url, { … }).
- The page sends the result only to the link’s
origin(fromorigin, or fromreturn_url), and the script only accepts messages from the connect page. Neither holds your platform key. - If the browser blocks the pop-up, the connect page opens in the same tab instead, and sends your customer back to
return_urlwith?wabot_status=connected&wabot_client_id=466when they finish. Other values ofwabot_status:cancelled,expired,revoked,used. PassredirectIfBlocked: falseto stop this. - Treat the pop-up result as a hint for your page. Confirm with the
client.whatsapp.connectedwebhook orGET /clients/{id}before relying on it. - A page sent with
Cross-Origin-Opener-Policy: same-origincan’t hear from pop-ups. Usesame-origin-allow-popupson that page, or rely onreturn_url.
List and read clients
Section titled “List and read clients”curl "https://app.wabot.shop/platform/v1/clients?external_id=cust-42" \ -H "Authorization: Bearer $WABOT_PLATFORM_KEY"GET /clients: all your clients. Filter with?external_id=. The list is cached for a minute; add?fresh=1to skip that.GET /clients/{id}: one client, always fresh.
Each client:
{ "id": 466, "external_id": "cust-42", "name": "Lumiere Cafe", "country": "Brazil", "ready": true, "whatsapp": { "connected": true, "numbers": [{ "phone_number": "+55 11 98765-4321", "verified_name": "Lumiere Cafe", "quality": "high", "messaging_limit": "TIER_1K" }] }, "plan": { "name": "Free", "free": true, "end_date": null }, "wallet_balance": 2.5, "messages_30d": { "sent": 0, "received": 3 }, "connect_link": { "status": "connected", "connected_at": "2026-11-16T10:20:00.000Z" }, "attention": []}attention lists what needs a look: not_connected, quality_low, plan_ending, plan_ended, wallet_empty.
Send messages as a client
Section titled “Send messages as a client”Every client account has its own messaging API credentials:
curl https://app.wabot.shop/platform/v1/clients/466/credentials \ -H "Authorization: Bearer $WABOT_PLATFORM_KEY"{ "success": true, "client_id": "466-…", "client_secret": "…" }Use them exactly as on Authentication: get a token from /v1/authenticate, then call the API reference endpoints (send template and session messages, templates, contacts, conversations) for that client.
Webhooks
Section titled “Webhooks”Instead of checking GET /clients/{id}, let Wabot tell your server when something happens to a client.
| Event | Sent when |
|---|---|
client.ready |
The client account is set up (about a minute after you create it). |
client.connect_link.opened |
The client opens a connect link for the first time. |
client.whatsapp.connected |
A WhatsApp number connects to the client account. |
webhook.test |
You ask for a test delivery. |
Add an endpoint
Section titled “Add an endpoint”curl -X POST https://app.wabot.shop/platform/v1/webhooks \ -H "Authorization: Bearer $WABOT_PLATFORM_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/wabot/webhooks", "events": ["client.whatsapp.connected"] }'{ "success": true, "id": 3, "url": "https://example.com/wabot/webhooks", "events": ["client.whatsapp.connected"], "secret": "whsec_…"}- Leave out
eventsto get all of them. - The
urlmust behttpson a public server. Addresses on private networks are refused. - Store
secret: it is returned only in this response and signs every delivery. You can have three endpoints; to change the secret, delete the endpoint and add it again.
GET /webhooks |
Your endpoints (without secrets). |
DELETE /webhooks/{id} |
Stop sending to an endpoint. |
POST /webhooks/{id}/test |
Send webhook.test now. The answer says whether it arrived: { "delivered": true, "status_code": 200 }. |
GET /webhooks/{id}/deliveries |
The last 50 deliveries: event, try number, status code, error. |
What we send
Section titled “What we send”A POST with a JSON body:
{ "id": "evt_6f1c2b9e0d4a7c3e5b8f1a2d", "type": "client.whatsapp.connected", "created_at": "2026-11-16T10:20:00.000Z", "data": { "client": { "id": 466, "external_id": "cust-42", "name": "Lumiere Cafe" }, "numbers": [{ "phone_number": "+55 11 98765-4321", "verified_name": "Lumiere Cafe", "business_app": true }] }}data.client is in every event. client.whatsapp.connected adds numbers; client.connect_link.opened adds connect_link (id, expires_at).
Headers: X-Wabot-Event (the type), X-Wabot-Event-Id (the id) and X-Wabot-Signature.
Answer with any 2xx status within 10 seconds. Anything else, a redirect or no answer counts as a failure: we try again after 1 minute and after 10 minutes, with the same event id. Use the id to ignore repeats.
Check the signature
Section titled “Check the signature”X-Wabot-Signature looks like t=1795342800,v1=5d41…. v1 is the HMAC-SHA256, in hex, of the timestamp, a dot and the raw request body, with your endpoint’s secret as the key.
import crypto from "node:crypto";
// rawBody: the request body exactly as received (a string), not re-serialised JSON.function isFromWabot(rawBody, header, secret) { const parts = Object.fromEntries(header.split(",").map((p) => p.split("="))); const t = Number(parts.t); if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false; // older than 5 minutes const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex"); const given = Buffer.from(parts.v1 || "", "hex"); return given.length === 32 && crypto.timingSafeEqual(Buffer.from(expected, "hex"), given);}Errors
Section titled “Errors”| Status | code |
Meaning |
|---|---|---|
| 401 | INVALID_KEY |
No key, or a deleted or unknown key. |
| 403 | PARTNER_MODE_OFF |
Client management is switched off for your login. |
| 404 | CLIENT_NOT_FOUND |
Not one of your clients. |
| 404 | WEBHOOK_NOT_FOUND |
Not one of your webhook endpoints. |
| 409 | NO_OWN_ACCOUNT |
Set up your own business account in the app first. |
| 409 | TOO_MANY_UNCONNECTED_CLIENTS |
Ten clients have no number yet: get some connected first. |
| 409 | EXTERNAL_ID_TAKEN |
Another of your clients has this external_id. |
| 409 | TOO_MANY_WEBHOOKS |
You have three endpoints: delete one first. |
| 422 | INVALID_CLIENT, INVALID_LINK |
Missing or invalid fields, listed in fields. |
| 422 | INVALID_URL, INVALID_EVENTS |
The webhook url is not a public https address, or none of the events exist. |
| 429 | TOO_MANY_REQUESTS, TOO_MANY_CLIENTS, TOO_MANY_LINKS |
Slow down, or try again tomorrow. |
Errors look like { "success": false, "error": "CLIENT_NOT_FOUND", "code": "CLIENT_NOT_FOUND", "message": "Client not found" }.
