Platform API (agencies and SaaS)
Dieser Inhalt ist noch nicht in deiner Sprache verfügbar.
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" }.
