Conecta el WhatsApp de tus clientes a Chatwoot sin abrir ZapClaw

En resumen: con una clave de administración, tu CRM o sistema de agencia hace toda la configuración por API. Tu cliente solo hace clic en Conectar WhatsApp en tu sistema, entra con Facebook y escanea un código QR en la app WhatsApp Business. El número queda listo en su bandeja de entrada de Chatwoot, y la app sigue funcionando en el teléfono.

Lo que hace tu cliente

1. Hace clic en Conectar WhatsApp en tu sistema.
2. Entra con Facebook en la página de conexión de ZapClaw, que muestra el nombre de tu agencia.
3. Escanea el código QR en la app WhatsApp Business.
4. Vuelve a tu sistema, donde el número ya está en Chatwoot.

Una vez por cuenta

En el panel de ZapClaw, el dueño define cómo aparece la agencia ante los clientes, acepta los términos de agencia y crea una clave de administración con Conectar y configurar clientes. Todo lo que sigue usa esa clave.

Las llamadas, en orden

1. Crear el cliente

Envía tu propio id como externalId: repetir la llamada con el mismo id devuelve el mismo cliente, con 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. Crear la clave de API del cliente

Esta clave zc_live_ es la que usa Chatwoot para enviar. Se devuelve una sola vez: guárdala.

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. Crear el enlace de conexión

Indica el número que tu cliente va a conectar y, si registraste una, la dirección de retorno. Abre la url tal como llegó, desde tu botón Conectar WhatsApp, o envíasela a tu 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 cuándo se conectó el número

Tu webhook de eventos de la cuenta recibe client_link.used con el número, firmado en el encabezado X-ZapClaw-Signature (sha256= y el HMAC-SHA256 del cuerpo sin procesar). El id es el id de la entrega: deduplica por él. Sin webhook, consulta el enlace hasta que su status sea 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. Leer el número

La respuesta trae el Phone Number ID y el WABA ID (wabaId) que necesita la bandeja de entrada de Chatwoot.

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

6. Apuntar el webhook a Chatwoot

El modo Chatwoot envía el payload de la propia Meta a tu Chatwoot, firmado. La respuesta trae el secreto de firma una vez; vuelve a leerlo después con 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. Crear la bandeja de entrada en Chatwoot

ZapClaw te da la solicitud de la bandeja de entrada con todos los campos completos menos la clave del cliente. Tu sistema la envía a Chatwoot con tu propio token de Chatwoot, que ZapClaw nunca pide.

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

Cuando algo sale mal

• Se conectó otro número. El enlace acepta solo el número indicado; la página lo avisa y no se conecta nada.
• El enlace venció. Un enlace dura 7 días. Extiéndelo o crea otro.
• NUMBER_IN_ANOTHER_CLIENT. El número ya pertenece a otro de tus clientes: muévelo o elige el cliente correcto.
• Chatwoot responde 401. El app_secret de la bandeja de entrada debe ser el secreto de firma; mira cómo corregir el 401.