Integrate your systems with WSC

Your system calls the WSC API to act (send, create, query); WSC calls your system back through webhooks when something happens. Each key belongs to one account and only does what its scopes allow.

• HTTPS only, JSON in and out (UTF-8).
• Every response comes in an envelope: data on success, error on failure.
• Phone numbers always in E.164 format, with + and the country code.

https://crm.walbby.com/api/v1

A key can only do what its scopes allow, whoever created it. Grant the minimum each integration needs.

Every response has one of two shapes. Branch your code on error.code, which is stable; error.message is for people and may change.

// 2xx{ "data": { … } } // 4xx / 5xx{  "error": {    "code": "forbidden",    "message": "This API key is missing the 'inbox.reply' scope"  }}

Resources from another account always answer 404, never 403: the API does not reveal what exists outside your account.

Every list pages the same way: by an opaque cursor, which stays stable while new records arrive.

• limit sets the page size: 50 by default, 100 at most.
• Pass meta.next_cursor back as cursor exactly as you received it, without decoding it.
• next_cursor: null means you reached the last page.

GET /api/v1/contacts?limit=50→ { "data": [ … ], "meta": { "next_cursor": "eyJ…" } } GET /api/v1/contacts?limit=50&cursor=eyJ…→ { "data": [ … ], "meta": { "next_cursor": null } }   // last page

All the operations of the public API and the scope each one needs.

Send to a phone number, not to an internal id. WSC finds or creates the contact and the conversation, sends the message and returns the ids.

• to must have + and the country code. Spaces, dashes and parentheses are accepted; a number without + is refused, because it could go to the wrong country.
• type: text (default), template, image, video, document or audio. For media, text becomes the caption.
• channel_id chooses the number that sends (see GET /api/v1/channels); without it, the account's main number is used.
• On the official API, outside the 24-hour window since the customer's last message, WhatsApp only delivers approved templates.

curl -X POST https://crm.walbby.com/api/v1/messages \  -H "Authorization: Bearer wacrm_live_xxx" \  -H "Content-Type: application/json" \  -d '{ "to": "+5511999990000", "type": "text", "text": "Olá! Seu pedido saiu para entrega 🚚" }'

{  "to": "+5511999990000",  "type": "template",  "template": {    "name": "order_update",    "language": "pt_BR",    "params": ["A123"]  },  "channel_id": "<id from GET /api/v1/channels>"}

{  "to": "+5511999990000",  "type": "document",  "media_url": "https://example.com/boleto-1042.pdf",  "filename": "boleto-1042.pdf",  "text": "Segue o seu boleto"}

// 201 Created{  "data": {    "message_id": "5f0c…",    "whatsapp_message_id": "wamid.HBgM…",    "conversation_id": "e2a9…",    "channel_id": "71d3…",    "contact_id": "9c44…",    "contact_created": true  }}

Official API and Wpp Web numbers

In GET /api/v1/channels, provider is meta_cloud for numbers on the official API and wpp_web for Wpp Web numbers. What changes between them:

Errors specific to sending

Keep your base in sync and read the history of any customer.

• POST /contacts is find-or-create by phone: 201 when it creates, 200 with the existing contact when the phone is already there.
• tags takes tag names; the ones that do not exist yet are created. In PATCH, tags replaces the contact's tags.
• The same customer writing to two of your numbers has two conversations, each with its channel_id.

curl -X POST https://crm.walbby.com/api/v1/contacts \  -H "Authorization: Bearer wacrm_live_xxx" \  -H "Content-Type: application/json" \  -d '{ "phone": "+5511999990000", "name": "Mariana Costa", "tags": ["lead", "site"] }' # 201 → new contact · 200 → that phone already existed (same contact back)

Send an approved template to up to 1,000 recipients per call. The call returns at once and sending continues in the background.

• Invalid phone numbers are dropped and counted in rejected; if none is valid, the answer is 400.
• params per recipient fill the template variables in order.
• Follow progress with GET /api/v1/broadcasts/:id: delivered and read keep growing as WhatsApp confirms.

curl -X POST https://crm.walbby.com/api/v1/broadcasts \  -H "Authorization: Bearer wacrm_live_xxx" \  -H "Content-Type: application/json" \  -d '{        "name": "Promo outubro",        "template_name": "promo_outubro",        "template_language": "pt_BR",        "recipients": [          { "to": "+5511999990000", "params": ["Mariana"] },          { "to": "+5511988887777" }        ]      }' # 202 → { "data": { "broadcast_id": "…", "status": "sending",#                   "total_recipients": 2, "accepted": 2, "rejected": 0 } }

Issue charges from your ERP or gateway and let WSC handle the reminders on WhatsApp. When your system confirms payment, mark it paid and the reminders stop.

• Identify the customer by contact_id or by phone (the contact is created if needed).
• Idempotent by external_id: sending the same one again returns the existing invoice with created: false, never a second charge.
• /pay and /cancel can be retried safely: they answer already_paid or already_canceled.
• Canceling a paid invoice answers 409 conflict.

curl -X POST https://crm.walbby.com/api/v1/invoices \  -H "Authorization: Bearer wacrm_live_xxx" \  -H "Content-Type: application/json" \  -d '{        "phone": "+5511999990000",        "description": "Mensalidade outubro",        "amount": 150,        "due_date": "2026-10-30",        "payment_url": "https://pay.example.com/erp-42",        "external_id": "erp-42"      }' # Mark it paid when your gateway confirms:curl -X POST https://crm.walbby.com/api/v1/invoices/<id>/pay \  -H "Authorization: Bearer wacrm_live_xxx" \  -H "Content-Type: application/json" \  -d '{ "method": "pix", "external_id": "pix-e2e-889" }'

Instead of polling the API, register a URL and WSC will POST to it every time something happens in the account.

Registering an endpoint

curl -X POST https://crm.walbby.com/api/v1/webhooks \  -H "Authorization: Bearer wacrm_live_xxx" \  -H "Content-Type: application/json" \  -d '{ "url": "https://example.com/hooks/wsc", "events": ["message.received", "invoice.paid"] }' # 201 → { "data": { "id": "…", "url": "…", "events": [ … ], "secret": "whsec_…" } }# The secret is shown only in this response. Store it.

What arrives

Every delivery has the same envelope; data changes by event. The id identifies the event and is the same on every retry: use it to discard duplicates.

POST https://example.com/hooks/wscX-Wacrm-Event: message.receivedX-Wacrm-Webhook-Id: 3e7b…X-Wacrm-Signature: t=1760270400,v1=5d41402abc4b2a76b9719d911017c592… {  "id": "8f3c…",  "event": "message.received",  "occurred_at": "2026-10-12T12:00:00.000Z",  "account_id": "8b1f…",  "data": {    "conversation_id": "e2a9…",    "contact_id": "9c44…",    "whatsapp_message_id": "wamid.HBgM…",    "content_type": "text",    "text": "Oi! Ainda tem o modelo azul?"  }}

Verifying the signature

X-Wacrm-Signature carries t (a timestamp) and v1 (an HMAC-SHA256). Recompute the HMAC over t.raw body with the endpoint's secret, compare in constant time, and refuse old timestamps.

import crypto from 'node:crypto';import express from 'express'; const app = express();const SECRET = process.env.WSC_WEBHOOK_SECRET; // whsec_… // Keep the raw body: the signature covers the exact bytes received.app.post('/hooks/wsc', express.raw({ type: 'application/json' }), (req, res) => {  const header = req.get('X-Wacrm-Signature') ?? '';  const [, t, v1] = header.match(/t=(\d+),v1=([0-9a-f]+)/) ?? [];  if (!t || Math.abs(Date.now() / 1000 - Number(t)) > 300) {    return res.sendStatus(400); // missing or too old: possible replay  }   const expected = crypto    .createHmac('sha256', SECRET)    .update(`${t}.${req.body}`)    .digest('hex');  const valid =    expected.length === v1.length &&    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));  if (!valid) return res.sendStatus(401);   const event = JSON.parse(req.body);  // Answer fast, dedupe on event.id, do the work in the background.  res.sendStatus(200);});

import hashlib, hmac, time def verify(header: str, raw_body: bytes, secret: str, tolerance: int = 300) -> bool:    parts = dict(p.split("=", 1) for p in header.split(","))    t, v1 = parts.get("t", "0"), parts.get("v1", "")    if abs(time.time() - int(t)) > tolerance:        return False  # too old: possible replay    expected = hmac.new(        secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256    ).hexdigest()    return hmac.compare_digest(expected, v1)

Retries

• Answer any 2xx within 10 seconds. Another status, a timeout or a redirect counts as a failure, and the event is tried again: 11 attempts over about 15 hours.
• Delivery is at least once and order is not guaranteed: dedupe on id.
• Each attempt is signed again with a new timestamp, so a retry stays inside your tolerance window.
• Every delivery and its attempts show in Settings → API → Webhooks, where a failed event can be resent. An endpoint that keeps failing is paused until you reactivate it.

WSC has a Model Context Protocol server: plug it into Claude, Cursor or any MCP client and ask about your CRM in plain language.

• It uses the public API, with your key and its scopes: the assistant can never do more than the key allows.
• Read-only by default. Sending messages and changing data have to be switched on explicitly.
• Broadcasts need a second switch and an explicit confirmation on each send.

{  "mcpServers": {    "WSC": {      "command": "node",      "args": ["/path/to/wsc-mcp/dist/index.js"],      "env": {        "WACRM_BASE_URL": "https://crm.walbby.com",        "WACRM_API_KEY": "wacrm_live_xxx"      }    }  }}

What WSC guarantees and what we recommend on your side.

• Keys are stored only as a hash: nobody, not even Walbby, can see a key again after it is created.
• Each key acts on a single account; resources from other accounts answer 404.
• Revocation takes effect on the next request. Revoked keys stay listed as an audit trail.
• Webhooks only go to https:// public addresses; internal and private addresses are refused.
• The webhook secret is shown once and every delivery is signed with a timestamp against replay.
• Keep keys on the server, never in the browser or an app, and use one key per integration.