Conecte o WhatsApp dos seus clientes ao Chatwoot sem abrir o ZapClaw

Em resumo: com uma chave de administração, o seu CRM ou sistema de agência faz toda a configuração pela API. O seu cliente só clica em Conectar WhatsApp no seu sistema, entra com o Facebook e lê um QR code no app WhatsApp Business. O número fica pronto na caixa de entrada do Chatwoot, e o app continua funcionando no celular.

O que o seu cliente faz

1. Clica em Conectar WhatsApp no seu sistema.
2. Entra com o Facebook na página de conexão do ZapClaw, que mostra o nome da sua agência.
3. Lê o QR code no app WhatsApp Business.
4. Volta para o seu sistema, onde o número já está no Chatwoot.

Uma vez por conta

No painel do ZapClaw, o dono define como a agência aparece para os clientes, aceita os termos de agência e cria uma chave de administração com Conectar e configurar clientes. Tudo daqui para baixo usa essa chave.

As chamadas, em ordem

1. Criar o cliente

Mande o seu id como externalId: repetir a chamada com o mesmo id devolve o mesmo cliente, com 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. Criar a chave de API do cliente

Esta chave zc_live_ é a que o Chatwoot usa para enviar. Ela volta uma vez só: guarde.

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. Criar o link de conexão

Informe o número que o seu cliente vai conectar e, se você cadastrou um, o endereço de retorno. Abra a url exatamente como veio, no seu botão Conectar WhatsApp, ou envie para o cliente.

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. Saber quando o número conectou

O seu webhook de eventos da conta recebe client_link.used com o número, assinado no cabeçalho X-ZapClaw-Signature (sha256= e o HMAC-SHA256 do corpo bruto). O id é o id da entrega: deduplique por ele. Sem webhook, consulte o link até o status ficar 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. Ler o número

A resposta traz o Phone Number ID e o WABA ID (wabaId) que a caixa de entrada do Chatwoot precisa.

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

6. Apontar o webhook para o Chatwoot

O modo Chatwoot envia o payload da própria Meta para o seu Chatwoot, assinado. A resposta traz o segredo de assinatura uma vez; leia de novo depois com 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. Criar a caixa de entrada no Chatwoot

O ZapClaw entrega a requisição da caixa de entrada com todos os campos preenchidos, menos a chave do cliente. O seu sistema envia para o Chatwoot com o seu próprio token do Chatwoot, que o ZapClaw nunca pede.

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": {...}}}

Quando algo dá errado

• Conectaram outro número. O link aceita só o número informado; a página avisa e nada é conectado.
• O link expirou. Um link vale 7 dias. Prorrogue ou crie outro.
• NUMBER_IN_ANOTHER_CLIENT. O número já pertence a outro cliente seu: mova o número ou escolha o cliente certo.
• O Chatwoot responde 401. O app_secret da caixa de entrada precisa ser o segredo de assinatura; veja como corrigir o 401.