Connect your clients' WhatsApp to Chatwoot without opening ZapClaw

In short: with an admin key, your CRM or agency system does the whole setup by API. Your client only clicks Connect WhatsApp in your system, logs in to Facebook and scans a QR code in the WhatsApp Business app. The number is then ready in their Chatwoot inbox, and the app keeps working on the phone.

What your client does

1. Clicks Connect WhatsApp in your system.
2. Logs in to Facebook on the ZapClaw connect page, which shows your agency's name.
3. Scans the QR code in the WhatsApp Business app.
4. Goes back to your system, where the number is already in Chatwoot.

Once per account

In the ZapClaw dashboard, the owner sets how the agency appears to clients, agrees to the agency terms and creates an admin key with Connect and set up clients. Everything below runs with that key.

The calls, in order

1. Create the client

Send your own id as externalId: a retry with the same id gives back the same client, with created: false.

curl -X POST https://api.zapclaw.app/api/v1/admin/clients \
  -H "X-API-Key: $ZAPCLAW_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Adventure Works Cycling", "externalId": "crm-8841"}'

2. Create the client's API key

This zc_live_ key is the one Chatwoot sends with. It comes back once: store it.

curl -X POST https://api.zapclaw.app/api/v1/admin/clients/$CLIENT_ID/keys \
  -H "X-API-Key: $ZAPCLAW_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Chatwoot"}'
# 201 {"apiKey": {...}, "key": "zc_live_..."}   shown once

3. Create the connect link

Give the number your client will connect and, if you registered one, the address to go back to. Open the url as it is from your Connect WhatsApp button or send it to your client.

curl -X POST https://api.zapclaw.app/api/v1/admin/clients/$CLIENT_ID/links \
  -H "X-API-Key: $ZAPCLAW_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expectedNumber": {"callingCode": "1", "nationalNumber": "4155550142"},
       "clientDisplayName": "Adventure Works Cycling", "language": "en",
       "returnUrl": "https://app.example-crm.com/whatsapp/connected"}'
# 201 {"link": {"id": "...", "status": "waiting"}, "url": "https://app.zapclaw.app/connect?lang=en#zcl_..."}

4. Know when the number connected

Your account events webhook gets client_link.used with the number, signed in the X-ZapClaw-Signature header (sha256= and the HMAC-SHA256 of the raw body). id is the delivery id: deduplicate on it. Without a webhook, read the link until its status is connected.

POST https://your-system.example.com/zapclaw/events
X-ZapClaw-Signature: sha256=...
{"event": "client_link.used",
 "id": "0c9e8d42-6f3b-4e43-8a0a-5d1c2a7b9e10",
 "createdAt": "2026-11-12T14:03:22.000Z",
 "organizationId": "2f5a6b3c-9d1e-4b7a-8c24-1e0f7a3d5c66",
 "data": {
   "clientId": "5b0f6f0e-3d57-4a39-9b43-0c6d9f1a7e21",
   "clientExternalId": "crm-8841",
   "linkId": "a7d3c1f2-4b6e-4c0a-9f55-2e8b1d7c3a90",
   "reference": "A7D3C1F2",
   "number": {"id": "e1c4b8a0-7d2f-4a5b-9c3e-6f0a1b2c3d4e", "phoneNumberId": "964283400112599",
              "wabaId": "980198427658004", "displayPhoneNumber": "+1 415 555 0142"}}}

5. Read the number

The answer has the Phone Number ID and the WABA ID (wabaId) the Chatwoot inbox needs.

curl https://api.zapclaw.app/api/v1/admin/clients/$CLIENT_ID/numbers \
  -H "X-API-Key: $ZAPCLAW_ADMIN_KEY"

6. Point the webhook at Chatwoot

Chatwoot mode sends Meta's own payload to your Chatwoot, signed. The answer carries the signing secret once; read it again later with webhooks:secret.

curl -X PUT https://api.zapclaw.app/api/v1/admin/clients/$CLIENT_ID/webhooks/chatwoot \
  -H "X-API-Key: $ZAPCLAW_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://chat.example-crm.com"}'
# 200 {"webhook": {...}, "secret": "whsec_..."}

7. Create the Chatwoot inbox

ZapClaw hands you the inbox request with every field filled in but the client key. Your system posts it to Chatwoot with your own Chatwoot token, which ZapClaw never asks for.

curl "https://api.zapclaw.app/api/v1/admin/clients/$CLIENT_ID/numbers/$NUMBER_ID/chatwoot-inbox?chatwootAccountId=3" \
  -H "X-API-Key: $ZAPCLAW_ADMIN_KEY"
# 200 {"request": {"method": "POST", "path": "/api/v1/accounts/3/inboxes", "body": {...}}}

When something goes wrong

• A different number was connected. The link takes only the number you gave; the page says so and nothing is connected.
• The link expired. A link lasts 7 days. Extend it or create a new one.
• NUMBER_IN_ANOTHER_CLIENT. The number already belongs to another of your clients: move it or pick the right client.
• Chatwoot answers 401. The inbox app_secret must be the signing secret; see the 401 fix.