Pular para o conteúdo

Platform API (agencies and SaaS)

Este conteúdo não está disponível em sua língua ainda.

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.

  1. 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.
  2. 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.

Terminal window
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).

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 '{ "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": true the link is also emailed to the client’s contact email.
  • Follow progress with GET /clients/{id}: connect_link.status goes sent → opened → connected, and whatsapp.connected becomes true. 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.

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.

  1. Add the script to your page:

    <script src="https://app.wabot.shop/sdk/wabot-connect.js"></script>
  2. 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 }'
  3. 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 digits
    onError: ({ 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 (from origin, or from return_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_url with ?wabot_status=connected&wabot_client_id=466 when they finish. Other values of wabot_status: cancelled, expired, revoked, used. Pass redirectIfBlocked: false to stop this.
  • Treat the pop-up result as a hint for your page. Confirm with the client.whatsapp.connected webhook or GET /clients/{id} before relying on it.
  • A page sent with Cross-Origin-Opener-Policy: same-origin can’t hear from pop-ups. Use same-origin-allow-popups on that page, or rely on return_url.
Terminal window
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=1 to 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.

Every client account has its own messaging API credentials:

Terminal window
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.

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.
Terminal window
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 events to get all of them.
  • The url must be https on 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.

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.

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);
}
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" }.