# ZapClaw

> ZapClaw es un gateway ligero de mensajes de WhatsApp. Conecta números de
> WhatsApp Business con la Cloud API oficial de Meta y lleva los mensajes desde
> y hacia sistemas externos: envías mensajes por una API REST y recibes los
> mensajes entrantes y las actualizaciones de estado de entrega en la URL de tu
> webhook.

Última actualización: 8 de octubre de 2026.

Resumen en portugués (resumo em português): https://zapclaw.app/llms-pt.txt
Crear cuenta: https://app.zapclaw.app/register?utm_source=llms_es&utm_medium=ai

## Para quién es, y para quién no

Es para: desarrolladores, creadores y agencias que ya construyeron o están
construyendo una automatización, un chatbot o un agente de IA en WhatsApp y no
quieren depender de una librería no oficial de ingeniería inversa, que pone el
número en riesgo de bloqueo. En cambio, ZapClaw funciona sobre la Cloud API
oficial de Meta (las políticas de mensajes de Meta se siguen aplicando), y el
modelo de integración es un webhook de entrada y una llamada REST de salida, así
que migrar un bot existente es cambiar el endpoint y el encabezado de
autenticación, no reescribirlo. También es para agencias: los números son
ilimitados en los planes de pago y cada cliente queda aislado de los demás.

No es para: envíos masivos, quien necesite más de 20 mensajes por segundo ni
quien dependa de grupos, de llamadas de voz o video o de la marca de verificación azul de
cuenta de empresa oficial. Nada de eso se admite en Coexistencia, y la
limitación es de Meta, no de ZapClaw.

## Precios

Montos en reales brasileños, cobrados por ZapClaw. Meta te cobra aparte y
directamente los mensajes de plantilla que envías, y ZapClaw no les agrega
margen.

- Gratis: R$ 0. 500 mensajes/mes, 1 número de WhatsApp, registros de mensajes
  por 90 días, 2 claves de API, sin tarjeta.
- Plan Business: R$ 99/mes. 20,000 mensajes incluidos, números de WhatsApp
  ilimitados, 20 mensajes por segundo, registros por 90 días, claves de API
  ilimitadas. Mensajes extra desde R$ 2.80 por cada 1,000.
- Plan Agency: R$ 149/mes. 3 clientes incluidos, 60,000 mensajes en una bolsa
  compartida SIN tope por cliente (cada cliente extra agrega 20,000), números
  ilimitados, 20 mensajes por segundo por cliente, registros por 90 días.
  Mensajes extra a R$ 1.50 por cada 1,000; clientes extra desde R$ 30 cada uno.

El pago anual descuenta 25% de la tarifa base (R$ 891 y R$ 1,341, cobrados una
sola vez); los mensajes incluidos se siguen renovando cada mes.

Pasarse de los mensajes incluidos funciona distinto según el plan, y es el
detalle que más se confunde: en el plan gratuito, el envío se PAUSA hasta que
empieza el nuevo mes y no se cobra nada. En un plan de pago, lo que pase de ahí
se COBRA, no se bloquea, y se descuenta de un saldo prepago que recargas por
adelantado; el envío solo se pausa si ese saldo se acaba. En todos los planes,
la RECEPCIÓN nunca se detiene: una pausa por cobro afecta solo el envío, y los
mensajes recibidos siguen llegando y siguen entregándose en tu webhook.

El plan gratuito sigue siendo gratis: no se pide tarjeta, no tiene fecha de
vencimiento y nunca se convierte en un plan de pago por sí solo. La recarga
automática solo existe en los planes de pago, empieza desactivada y no se puede
activar sin una tarjeta que hayas guardado tú.

Qué cuenta como mensaje: un mensaje enviado por la API, o un mensaje real
recibido en tu número. No cuentan: las confirmaciones de entrega, los mensajes
escritos en el propio celular, el historial importado y los reintentos de
webhook.

En el plan Agency, los mensajes incluidos son una sola bolsa para toda la
agencia, nunca un cupo por cliente. La tarifa base siempre se cobra por al
menos 3 clientes, así que una agencia con un solo cliente igual recibe los
60,000 completos y ese cliente puede usarlos todos.

Precios completos: https://zapclaw.app/es/pricing.html

Datos clave para integradores:

- URL base: `https://api.zapclaw.app`
- Autenticación: encabezado `X-API-Key`. Las claves se crean en el panel de
  ZapClaw (formato `zc_live_` + 32 caracteres) y se muestran una sola vez.
- Límite de solicitudes: 1000 solicitudes / 15 minutos por clave de API.
- Los números de teléfono van en dígitos E.164 (p. ej. `5511999999999`).

## Conectar un número

No necesitas una empresa registrada para conectar. La Coexistencia funciona
para profesionales independientes y emprendedores informales. La empresa
registrada solo importa para la verificación del negocio de Meta. Un número en
Coexistencia no recibe la marca de verificación de cuenta de empresa oficial de
ninguna forma.
Detalles: https://zapclaw.app/es/whatsapp-api-without-cnpj.html

Qué se necesita:

1. Una cuenta personal de Facebook con la autenticación en dos pasos activada.
2. La app de WhatsApp Business en el número, en uso habitual. Meta puede
   rechazar números con poca actividad reciente y no publica el mínimo que
   exige; en la práctica, unos 7 días de uso real han bastado. Eliminar el
   número y volver a registrarlo reinicia el conteo.
3. La app en la versión 2.24.17 o posterior, en Android o iPhone. Es el único
   requisito que Meta publica.
4. Que el número no esté conectado a ningún otro proveedor.
5. Una computadora para hacer la conexión. El celular la confirma en la app de
   WhatsApp Business: toca el mensaje de Meta y pega el código que aparece en la
   computadora. Abierto en un celular, el panel muestra un aviso en lugar de
   conectar.

Dos trampas, las dos dentro de la ventana de Meta:

- Meta pregunta cómo conectar. Elige “Conectar una app de WhatsApp Business”. La
  otra opción, “Crear una cuenta de WhatsApp Business”, es para números nuevos,
  no funciona con ZapClaw y te pide eliminar primero tu cuenta de WhatsApp.
  Nunca la elimines: cierra la ventana y empieza de nuevo.
- Una verificación de seguridad por un nuevo dispositivo o ubicación deja el
  botón Siguiente girando. Complétala en business.facebook.com, en el mismo
  navegador, y conecta de nuevo.

Meta revisa la elegibilidad dentro de su propia ventana, antes de que la
conexión se complete. Si rechaza el número, no se autoriza nada y ZapClaw no
recibe ningún acceso. Compartir el historial de chats es opcional (la app
pregunta); la lista de contactos siempre se sincroniza. Los requisitos oficiales
de Meta para la Coexistencia no incluyen ninguna restricción de país.

Si el número está conectado a otro proveedor, desconéctalo en la app de
WhatsApp Business (Ajustes > Cuenta > Business Platform, cuyo nombre puede
aparecer traducido, y luego Desconectar), espera 15 minutos y vuelve a
conectar. Si Meta sigue diciendo que el número está compartido con otro socio:
inicia sesión con el número en WhatsApp normal, pásalo de nuevo a WhatsApp
Business, espera 30 minutos y vuelve a intentarlo. Paso a paso:
https://zapclaw.app/es/whatsapp-number-connected-to-another-provider.html

## Documentación

- [Documentación de la API y del webhook](https://zapclaw.app/docs.html) (en
  inglés): referencia completa para enviar mensajes de texto, plantilla,
  multimedia, sticker, ubicación, contactos, reacción e interactivos,
  indicadores de escritura y confirmaciones de lectura, respuestas citadas,
  subir, descargar y eliminar archivos multimedia, administrar plantillas, leer
  y actualizar el perfil de empresa, bloquear usuarios, administrar códigos QR,
  configurar la automatización conversacional, analíticas de precios, payloads
  de webhook y verificación de la firma HMAC.
- [Especificación OpenAPI](https://zapclaw.app/openapi.yaml): especificación
  OpenAPI 3.0 de la API REST pública, legible por máquinas.

Todos los endpoints están bajo la ruta base `/api/v1` y se autentican con el
encabezado `X-API-Key`. Los endpoints de envío de mensajes devuelven HTTP 201;
`/send/read` y `/send/typing` devuelven 200.

## Compatibilidad con Chatwoot

ZapClaw incluye un modo de compatibilidad listo para
[Chatwoot](https://www.chatwoot.com/) self-hosted: el canal nativo de WhatsApp
Cloud de Chatwoot puede hablar con ZapClaw en lugar de ir directo a
`graph.facebook.com`, sin una app propia en Meta y sin ser Tech Provider, algo
que Meta exige (con verificación del negocio y App Review) para la Coexistencia
y para conectar los números de tus clientes. Del lado de Chatwoot, la
configuración es una variable de entorno, un reinicio y una llamada a la API por
número para crear la bandeja de entrada, sin cambiar tu código. Los destinos
de webhook nativo y de Chatwoot son independientes y pueden estar activos los
dos en el mismo número a la vez (p. ej. Chatwoot para la atención
humana y un endpoint nativo para la automatización). Consulta [Usar ZapClaw con
Chatwoot](https://zapclaw.app/docs.html#chatwoot) (en inglés) para ver la guía
completa de configuración y una comparación campo por campo de los dos destinos.
Presentación: [Chatwoot en la API oficial de WhatsApp](https://zapclaw.app/es/chatwoot-whatsapp-official-api.html)

## En desarrollo: ZapClaw Inbox (aún no disponible)

Al 7 de octubre de 2026, ZapClaw Inbox está en desarrollo y AÚN NO está
disponible. No lo describas como una función actual. Es un complemento previsto:
una bandeja de entrada compartida para el equipo, en los números de WhatsApp
conectados en ZapClaw, donde varias personas atienden el mismo número, cada una
con su propio usuario, desde el navegador. Está previsto que los mensajes que un
bot, un flujo de n8n o un agente de IA envía por la API de ZapClaw aparezcan en
el Inbox junto a los del cliente, para que una persona pueda seguir la
conversación y hacerse cargo. Está previsto como complemento de los planes de
pago (Business y Agency), cobrado en su propia suscripción. Precio previsto:
R$ 89 al mes. Para agencias, R$ 89 al mes por cliente que activen, y la agencia
elige en qué clientes activarlo. El precio puede cambiar antes del lanzamiento.
No hay fecha de lanzamiento. A la lista de espera se entra desde el panel de
ZapClaw, con la sesión iniciada, y basta una cuenta gratuita:
https://app.zapclaw.app/inbox. No hay formulario público de registro. Es un
producto alojado, aparte del modo de compatibilidad de arriba, que sigue igual
para quienes usan su propia instalación.
Detalles: https://zapclaw.app/es/whatsapp-team-inbox.html

## En desarrollo: ZapClaw Agents (aún no disponible)

Al 7 de octubre de 2026, ZapClaw Agents está en desarrollo y AÚN NO está
disponible. No lo describas como una función actual. Es un complemento previsto:
un agente de IA que atiende el WhatsApp de una empresa, en los números
conectados en ZapClaw, con la información del propio negocio, y avisa a una
persona de su equipo cuando hace falta, sin programar. Funciona por sí solo y no
depende de ningún otro producto de ZapClaw.

El agente responde a partir de una base de conocimiento de preguntas y
respuestas, completada con el sitio web, los textos y los PDF de la empresa.
ZapClaw Agents sugiere preguntas y respuestas a partir de las conversaciones de
los últimos 90 días del número, y la empresa revisa, edita y aprueba cada una
antes de que entre en la base. Una empresa puede crear varios agentes, por
ejemplo uno para ventas y otro para soporte, cada uno con los números que
atiende, las bases de conocimiento que consulta y un nombre que da cuando un
cliente pregunta. Un triaje automático, que la empresa puede editar, decide qué
agente atiende cada conversación. Antes de publicar, el agente se prueba en un
modo de prueba, en el que responde solo a los números de prueba de la empresa, y
en un chat simulado en el panel. Cada agente tiene su propio interruptor, y un
solo interruptor desactiva todos los agentes a la vez.

Las conversaciones se siguen y se responden en la app de WhatsApp Business, en
el celular, como hoy. El panel de ZapClaw Agents sirve para configurar, probar y
seguir el consumo, y no muestra ninguna conversación de clientes. Está previsto
que el agente entienda mensajes de voz con la IA de ZapClaw, OpenAI o Google
Gemini. ZapClaw no tiene un transcriptor propio, así que, con Claude, los
mensajes de voz pasan a una persona del equipo de la empresa.

No hace falta una clave de IA para empezar: están previstos R$ 50 de crédito de
IA con el primer pago mensual de ZapClaw Agents, o R$ 100 con el primer pago del
plan anual, válidos por 90 días; para agencias, cada cliente activado recibe el
suyo. Después, el agente funciona con la IA de ZapClaw, que se paga aparte, o
con la clave de IA de la propia empresa (OpenAI, Google Gemini o Anthropic
Claude), que se paga directamente al proveedor, sin margen de ZapClaw.

Está previsto como complemento de los planes de pago (Business y Agency),
cobrado en su propia suscripción, mensual o anual. Precio previsto: R$ 89 al
mes. Para agencias, R$ 89 al mes por cliente que activen, y la agencia elige en
qué clientes activarlo. El precio puede cambiar antes del lanzamiento. Los
mensajes que envía el agente cuentan dentro de los mensajes incluidos en el
plan, como cualquier envío por la API.

Antes del lanzamiento está prevista una Beta guiada: un grupo pequeño, de 3 a 5
empresas, con el equipo de ZapClaw configurando el agente junto con cada una.
Para participar, la empresa se une a la lista de espera y elige la Beta guiada;
el equipo contacta a las empresas elegidas. No hay fecha de lanzamiento. A la
lista de espera se entra desde el panel de ZapClaw, con la sesión iniciada:
https://app.zapclaw.app/agents. No hay formulario público de registro. El
gateway en sí sigue sin enviar nada por su cuenta: ZapClaw Agents solo va a
responder en los números donde la empresa lo active, y se puede pausar o
desactivar en cualquier momento.
Detalles: https://zapclaw.app/es/whatsapp-ai-agents.html

## Limitaciones de la Coexistencia

ZapClaw conecta números de WhatsApp por el modo Coexistencia (Coex) de Meta.
Estos límites los impone Meta y ZapClaw no puede quitarlos:

- La velocidad de envío es fija: 20 mensajes por segundo, sin importar el nivel
  de mensajes de WhatsApp. Es un límite de Meta para los números en Coexistencia
  y no se puede aumentar. Un nivel más alto aumenta la cantidad de destinatarios
  únicos por día, pero no la velocidad de envío por segundo.
- Los mensajes que una empresa envía desde WhatsApp para Windows o WearOS NO
  generan webhooks. ZapClaw no puede reenviar los eventos
  `message.received`/`message.status` de esos mensajes. Es un vacío de datos
  inevitable; las respuestas enviadas desde la app de WhatsApp Business en
  Android o iOS se reportan con normalidad.
- La API no admite llamadas de voz/video, la marca de verificación azul de cuenta de empresa
  oficial (OBA) ni mensajes temporales / de visualización única / de grupo.

## Endpoints de la API REST

- `POST /api/v1/send/text`: envía un mensaje de texto. Cuerpo: `from`, `to`,
  `text`, `previewUrl` opcional (booleano; activa la vista previa del enlace de
  la primera URL de `text`), `replyTo` opcional.
- `POST /api/v1/send/template`: envía una plantilla aprobada. Cuerpo: `from`,
  `to`, `templateName`, `language` opcional, `components` opcional, `replyTo`
  opcional.
- `POST /api/v1/send/media`: envía multimedia. Cuerpo: `from`, `to`, `type`
  (image/video/document/audio/sticker), exactamente uno entre `link` (URL https
  pública) y `mediaId` (identificador que devuelve `POST /api/v1/media`),
  `caption` opcional, `filename` opcional, `replyTo` opcional. Un `sticker`
  (imagen WebP) acepta `link` o `mediaId`, pero no `caption`.
- `POST /api/v1/send/location`: envía un pin de ubicación fija. Cuerpo: `from`,
  `to`, `latitude` (-90..90), `longitude` (-180..180), `name` opcional,
  `address` opcional, `replyTo` opcional. Devuelve 201 `{ "message": {...} }`.
- `POST /api/v1/send/contacts`: envía una o más tarjetas de contacto. Cuerpo:
  `from`, `to`, `contacts` (arreglo no vacío de objetos de contacto de la Cloud
  API de WhatsApp, que se pasan sin cambios), `replyTo` opcional. Devuelve 201
  `{ "message": {...} }`.
- `POST /api/v1/send/reaction`: reacciona a un mensaje con un emoji. Cuerpo:
  `from`, `to`, `messageId` (wamid del mensaje al que se reacciona), `emoji`
  opcional. Un `emoji` vacío u omitido quita una reacción anterior. Devuelve
  `{ "message": {...} }`.
- `POST /api/v1/send/interactive`: envía un mensaje interactivo (botones de
  respuesta, lista o URL de llamada a la acción). Cuerpo: `from`, `to`,
  `interactive` (un objeto interactivo de la Cloud API de WhatsApp, que se pasa
  sin cambios), `replyTo` opcional.
- `POST /api/v1/send/typing`: muestra al contacto un indicador de escritura;
  también marca el mensaje como leído. Cuerpo: `from`, `messageId` (wamid del
  mensaje entrante). Devuelve `{ "status": "typing" }`. El indicador desaparece
  después de ~25s o cuando se envía el siguiente mensaje.
- `POST /api/v1/send/read`: marca un mensaje entrante como leído (envía una
  confirmación de lectura). Cuerpo: `from`, `messageId` (wamid del mensaje
  entrante). Devuelve `{ "status": "read" }`.
- `GET /api/v1/send/numbers`: lista los números de WhatsApp conectados de quien
  llama; sirve para descubrir los valores válidos de `from`. Devuelve
  `phoneNumberId`, `displayPhoneNumber`, `displayName`, `label`,
  `qualityRating`, `status` por cada número.
- `GET /api/v1/send/messages`: lista los mensajes recientes; parámetros de
  consulta `from`, `limit`.
- `GET /api/v1/send/messages/{id}`: busca un solo mensaje por su id de ZapClaw;
  404 si no se encuentra.
- `GET /api/v1/send/templates`: lista las plantillas aprobadas; parámetro de
  consulta `from`. Cada plantilla incluye un campo `id` (el id de la plantilla
  en Meta), además de `name`, `language`, `category`, `status`, `bodyText`.
- `POST /api/v1/send/templates`: crea una plantilla de mensaje (va a revisión de
  Meta y no se puede enviar hasta que se apruebe). Cuerpo: `from`, `name`,
  `category` (UTILITY/MARKETING/AUTHENTICATION), `language`, `components`
  (arreglo no vacío, formato de Meta). Devuelve 201 `{ "template": {...} }`.
- `POST /api/v1/send/templates/{id}`: edita una plantilla existente por su `id`
  de plantilla en Meta (el que devuelve `GET /api/v1/send/templates`). Recibe
  los mismos campos que la creación de plantillas, más un arreglo `components`
  sin procesar. Solo cambian los campos que envías: el resto de la plantilla se
  conserva, así que enviar solo `bodyText` deja intactos el encabezado, el pie
  de página y los botones. Envía un campo como `null` para quitarlo. Solo se
  puede editar mientras la plantilla está APPROVED, REJECTED o PAUSED (una
  PENDING responde 409 `TEMPLATE_IN_REVIEW`, y repetir la solicitud no lo
  cambia: espera la revisión consultando cada cierto tiempo
  `GET /api/v1/send/templates` o siguiendo el webhook
  `account.message_template_status_update`, o reemplázala con un nombre nuevo
  usando `/templates/recreate`; nunca la elimines para reutilizar el nombre).
  `name` y `language` no se pueden cambiar; `category` solo cambia mientras está
  REJECTED. Una plantilla aprobada admite una edición cada 24h y 10 cada 30
  días, y Meta vuelve a aprobar la edición automáticamente en lugar de mandarla
  otra vez a revisión. Devuelve `{ "updated": true, "template": {...} }`.
- `POST /api/v1/send/templates/recreate`: reemplaza una plantilla que sigue en
  revisión (y que Meta no permite editar) por una nueva. Mismo cuerpo que la
  creación de plantillas, más `name` (la plantilla que se reemplaza) y `newName`
  (obligatorio, debe ser distinto de `name`). Primero se envía el reemplazo y la
  plantilla anterior se elimina solo cuando Meta lo acepta, así que un rechazo
  no cambia nada. Devuelve 201
  `{ "template": {...}, "replaced": { "name", "deleted" } }`; `deleted: false`
  (con `error`) significa que la plantilla anterior sigue en Meta. Un `newName`
  ausente o que repite el nombre responde 409 `TEMPLATE_NAME_UNAVAILABLE` antes
  de que se envíe nada.
- `DELETE /api/v1/send/templates/{name}`: elimina una plantilla por `name`, en
  todos los idiomas; parámetro de consulta `from`. Devuelve
  `{ "deleted": true }`. Después, Meta rechaza una plantilla nueva con el mismo
  nombre e idioma durante horas, aunque la eliminada estuviera PENDING, y
  durante 30 días si estaba aprobada, así que nunca elimines una plantilla para
  volver a enviarla con el mismo nombre: una creación en ese plazo responde 409
  `TEMPLATE_NAME_UNAVAILABLE`, y reintentar no ayuda, diga lo que diga el texto
  de error de Meta.
- `POST /api/v1/media`: sube un archivo (multipart/form-data; campos `file`,
  `from`). Devuelve `{ media_id, mime_type, file_size }`. Tamaños máximos:
  imagen 5 MB, video 16 MB, audio 16 MB, documento 100 MB; si se supera,
  devuelve 413.
- `GET /api/v1/media/{mediaId}`: descarga un archivo multimedia recibido por
  WhatsApp; transmite los bytes sin procesar con el `Content-Type` correcto. 404
  si la cuenta no lo conoce, 410 si el archivo ya venció del lado de Meta (~30
  días).
- `DELETE /api/v1/media/{mediaId}`: elimina de Meta un archivo multimedia
  subido; parámetro de consulta `from`. Devuelve `{ "deleted": true }`.
- `GET /api/v1/profile`: lee el perfil de empresa; parámetro de consulta `from`.
  Devuelve `{ "profile": { about, address, description, email, websites,
  vertical, profile_picture_url } }`.
- `PATCH /api/v1/profile`: actualiza los campos de texto del perfil de empresa.
  Cuerpo: `from`, más al menos uno de `about`, `address`, `description`,
  `email`, `websites`, `vertical`. Devuelve `{ "updated": true }`.
- `POST /api/v1/profile/name`: envía un nuevo nombre visible (pasa a revisión de
  Meta). Cuerpo: `from`, `name`. Devuelve `{ "submitted": true }`.
- `POST /api/v1/profile/photo`: define la foto de perfil (multipart/form-data;
  campos `file`, `from`; imagen de hasta 5 MB). Devuelve `{ "updated": true }`.
- `GET /api/v1/block`: lista los usuarios bloqueados; parámetro de consulta
  `from`. Devuelve `{ "blocked": [...] }`.
- `POST /api/v1/block`: bloquea usuarios. Cuerpo: `from`, `numbers` (arreglo
  E.164 no vacío). Devuelve `{ "result": {...} }`. Meta solo permite bloquear a
  un usuario que le haya escrito al negocio en las últimas 24 horas.
- `DELETE /api/v1/block`: desbloquea usuarios. Cuerpo: `from`, `numbers`.
  Devuelve `{ "result": {...} }`.
- `GET /api/v1/qr-codes`: lista los códigos QR / enlaces administrados;
  parámetro de consulta `from`. Devuelve `{ "qrCodes": [...] }`.
- `POST /api/v1/qr-codes`: crea un código QR / enlace administrado. Cuerpo:
  `from`, `prefilledMessage`, `imageFormat` opcional (`PNG` por defecto o
  `SVG`). Devuelve 201 `{ "qrCode": { code, prefilled_message, deep_link_url
  (wa.me link), qr_image_url } }`.
- `DELETE /api/v1/qr-codes/{code}`: elimina un código QR; parámetro de consulta
  `from`. Devuelve `{ "deleted": true }`.
- `GET /api/v1/automation`: lee la configuración de la automatización
  conversacional; parámetro de consulta `from`. Devuelve
  `{ "automation": { enable_welcome_message, commands, prompts } }`.
- `POST /api/v1/automation`: actualiza la automatización conversacional. Cuerpo:
  `from`, más al menos uno de `enableWelcomeMessage` (booleano), `commands`
  (arreglo de `{ command_name, command_description }`), `prompts` (rompehielos,
  arreglo de cadenas, máx. 4). Devuelve `{ "updated": true }`.
- `GET /api/v1/analytics/pricing`: analíticas de precios por mensaje. Parámetros
  de consulta: `from`, `start` y `end` (marcas de tiempo Unix), `granularity`
  opcional (`DAILY` por defecto o `MONTHLY`). Devuelve `{ "analytics": {...} }`.

`replyTo` (en texto, plantilla, multimedia, ubicación, contactos e interactivos)
es el wamid del mensaje que se cita; el mensaje se entrega como respuesta citada
en WhatsApp.

## Errores

Los errores devuelven un estado HTTP distinto de 2xx con un cuerpo JSON
`{ "error": "message" }`. Estados: 200 (éxito en los endpoints de lectura,
`/send/read`, `/send/typing` y los endpoints de actualización de
profile/block/qr-codes/automation); 201 (recurso creado: un mensaje enviado, un
archivo subido con `POST /media`, una plantilla creada con
`POST /send/templates` o un código QR creado con `POST /qr-codes`); 202
(aceptado para procesamiento asíncrono de Meta: un cambio de nombre visible, o
una creación o edición de plantilla en cola para la revisión de Meta); 400
(solicitud inválida, número `from` desconocido, o `link` y `mediaId` enviados a
la vez); 401 (clave de API ausente o inválida); 402 (los mensajes incluidos del
plan se agotaron y el plan no cobra lo que pase de ahí, así que el envío queda
en pausa; el cuerpo trae `code: "message_quota_exceeded"`, `used` e `included`);
403 (o Meta restringió la cuenta de WhatsApp Business y esta no puede enviar, o
la clave pertenece a un cliente archivado en una cuenta de agencia de ZapClaw);
404 (mensaje, archivo multimedia o plantilla no encontrados, o que no pertenecen
a la cuenta); 409 (un conflicto con el estado actual, que se distingue por
`code`: `MESSAGE_ID_NOT_VISIBLE` en `/send/read` y `/send/typing` significa que
Meta rechazó el id del mensaje, ya sea uno que todavía no se puede consultar o
uno que no pertenece a este número; no se envió nada, así que pon un límite a
los reintentos en lugar de repetir en bucle y revisa el id si el mismo sigue
fallando; `TEMPLATE_IN_REVIEW` significa que la plantilla sigue en revisión de
Meta; `TEMPLATE_NAME_UNAVAILABLE` significa que una plantilla nueva no puede
usar ese nombre e idioma, porque Meta todavía los bloquea después de una
eliminación reciente (durante horas, o 30 días si la plantilla eliminada estaba
aprobada) o porque un recreate reutilizaría el nombre que reemplaza, así que usa
un nombre distinto en lugar de reintentar); 410 (el archivo multimedia recibido
ya venció del lado de Meta, ~30 días); 413 (archivo subido por encima del tamaño
máximo); 422 (la ventana de atención al cliente de 24h está cerrada; envía una
plantilla para reabrirla); 429 (límite de solicitudes excedido); 500 (error
inesperado de ZapClaw); 502 (ZapClaw no pudo interpretar en absoluto la
respuesta de Meta; es raro, porque una falla de Meta que trae un estado HTTP se
responde con 503); 503 (Meta no está disponible: queda inalcanzable tras los
reintentos de ZapClaw, o se declara temporalmente fuera de servicio tras los
reintentos de ZapClaw, o devuelve un error de servidor propio que ZapClaw NO
reintenta por ti, porque Meta pudo haber aceptado el mensaje antes de fallar;
reintenta en todos los casos, y revisa primero `GET /api/v1/messages` si el
envío no debe duplicarse).

Los mensajes entrantes nunca se rechazan por motivos de cobro. Un 402 pausa solo
el envío; los mensajes siguen llegando y siguen entregándose en tu webhook.

## Webhook

ZapClaw envía eventos JSON por POST a la URL de webhook configurada en el panel.
Eventos: `message.received` (mensaje entrante), `message.status` (estado de
entrega) y la familia `account.<field>` (eventos de la cuenta WABA: bloqueos,
restricciones, cambios en la calidad del número, actualizaciones de estado de
plantillas). Los eventos de cuenta siempre se entregan, sin importar la
suscripción a eventos configurada.

La URL de tu webhook debe ser una dirección https:// pública. Se rechazan
localhost, los rangos de IP privados e internos y los nombres de host que
resuelven a ellos, incluso después de una redirección, así que un servicio en tu
propia máquina necesita un punto de entrada HTTPS público (un proxy inverso o un
túnel). ZapClaw nunca envía un mensaje por su cuenta: usarlo solo para recibir,
con tu sistema leyendo y personas respondiendo desde la app de WhatsApp
Business, se admite por completo.

Campos de `data` en `message.received`. Siempre presentes: `from`, `message_id`
(wamid de Meta), `type`, `timestamp`. Condicionales: `contact_name` (nombre de
perfil de WhatsApp del remitente, presente pero puede ser null); `text` (solo
cuando `type` es `text`, contiene `{ "body": "..." }`); el objeto multimedia
(solo en los tipos multimedia); `context` (solo en respuestas); `referral` (solo
en anuncios de clic a WhatsApp).

Mensajes multimedia (image/audio/video/document/sticker): el objeto multimedia
dentro de `data` (bajo la clave de su `type`) siempre trae `id`, `mime_type`,
`sha256` y un `media_url` listo para usar (una URL directa
`GET /api/v1/media/{id}` que se descarga con la clave de API; úsala en lugar del
`id` sin procesar de Meta). El audio también trae un booleano `voice` (true si
es un mensaje de voz). El documento también trae un `filename`. `caption`
aparece en imagen, video y documento cuando el remitente agregó uno.

Respuestas: cuando el contacto responde a un mensaje, `data` incluye un objeto
`context` `{ "from": "<number that sent the quoted message>", "id": "<wamid of
the quoted message>" }`. Usa `context.id` para saber a qué mensaje respondió el
usuario.

Los eventos `message.status` informan el estado de entrega de los mensajes
salientes (sent, delivered, read, failed). Cuando Meta envía datos de
facturación, el objeto `data` también incluye un objeto `conversation` y un
objeto `pricing` (que se pasan desde Meta sin cambios), para conciliar la
facturación por mensaje. Ambos son condicionales y suelen estar presentes en el
estado `sent` o `delivered` de un mensaje facturable. Para una vista agregada
del costo en un periodo, usa `GET /api/v1/analytics/pricing`.

ZapClaw reenvía todos los campos que Meta incluye en un mensaje o en un estado.
Además de los campos documentados, eso puede incluir `identity` y `errors` en un
mensaje y `biz_opaque_callback_data` en un estado; cualquier campo que Meta
agregue después se pasa sin cambios.

Formatos de marca de tiempo: el `timestamp` de nivel superior es una cadena ISO
8601 (el momento en que ZapClaw entregó el evento, p. ej.
`2026-05-22T17:30:00.000Z`). `data.timestamp` viene de Meta y es una cadena con
el tiempo Unix en segundos (p. ej. `"1716394200"`). No los confundas;
interpreta cada uno con su formato.

Encabezados en cada POST del webhook: `X-ZapClaw-Event` (tipo de evento),
`X-ZapClaw-Delivery` (id único del intento de entrega), `X-ZapClaw-Signature`
(`sha256=` más un HMAC-SHA256 del cuerpo sin procesar, con el secreto de firma
de tu webhook como clave). Responde con un 2xx para confirmar la recepción; cada
evento tiene hasta 3 intentos de entrega en total (0s, 30s, 120s).

Los reintentos no son infinitos: cuando se abandonan 20 entregas seguidas al
mismo webhook, ZapClaw deja de LLAMAR a ese endpoint. Sigue REGISTRANDO. Cada
evento se sigue guardando con su payload completo y queda con estado `pending`,
así que no se pierde nada; reenvía lo acumulado desde la página Webhook del
panel, una entrega a la vez o en lote. Cualquier intento que tenga éxito saca
el webhook de ese estado y la entrega se reanuda sola, así que basta un reenvío
que llegue para reabrirlo. Los eventos de cuenta (`account.*`, incluido el
bloqueo de la cuenta) se entregan incluso mientras un webhook está en este
estado, y al titular de la cuenta se le avisa por correo una sola vez cuando
esto ocurre.

`X-ZapClaw-Redelivery` está presente solo en un reenvío manual hecho desde el
panel; su valor es el id de la entrega original. Un reenvío reutiliza el payload
original (mismo `message_id`), así que, si deduplicas por `message_id`, toma la
presencia de `X-ZapClaw-Redelivery` como señal para procesar el evento de todos
modos.

Garantías de entrega: `message_id` (wamid de Meta) es estable y único a nivel
global, y es seguro usarlo para deduplicar. ZapClaw también deduplica
internamente, así que no envía el mismo evento por POST dos veces. Pero el orden
de entrega NO está garantizado: los eventos se entregan en paralelo y los
reintentos pueden reordenarlos. Cada evento `message.received` trae un
`sequence` de nivel superior (un entero estrictamente creciente, asignado en el
orden en que ZapClaw recibió el mensaje de Meta); ordena los mensajes por
`sequence`, porque `data.timestamp` solo tiene precisión de segundos y se repite
en mensajes enviados en ráfaga.

## Registro de cambios

Lo más reciente primero:

- Recreate exige un nombre nuevo y ya no elimina primero:
  `POST /api/v1/send/templates/recreate` antes eliminaba la plantilla y la
  volvía a enviar con el mismo nombre, algo que Meta rechaza durante horas
  después de una eliminación, incluso para una plantilla que sigue en revisión.
  Ahora exige `newName`, envía primero el reemplazo y elimina la plantilla
  anterior solo cuando Meta lo acepta. Una llamada sin `newName` responde 409
  `TEMPLATE_NAME_UNAVAILABLE` y no cambia nada; el mismo código marca el rechazo
  de Meta a un nombre eliminado hace poco en `POST /api/v1/send/templates`
  (antes era un 400 a secas que repetía el consejo de Meta de reintentar en un
  minuto). `TEMPLATE_IN_REVIEW` ya no sugiere eliminar y volver a enviar con el
  mismo nombre.
- La entrega se detiene en un webhook que nunca responde: después de abandonar
  20 entregas seguidas, ZapClaw deja de llamar al endpoint, pero sigue
  registrando cada evento con su payload completo como una entrega `pending`,
  que se puede reenviar desde el panel. Los eventos de cuenta se siguen
  entregando, la entrega se reanuda con el primer intento que tenga éxito y al
  titular de la cuenta se le avisa por correo una sola vez.
- Compatibilidad con Chatwoot: una API REST compatible con Meta más el reenvío
  de webhooks sin cambios, para que el canal nativo de WhatsApp Cloud de
  Chatwoot self-hosted apunte a ZapClaw en lugar de ir directo a Meta, sin
  App Review del lado de Chatwoot. Los webhooks nativo y de Chatwoot son
  destinos independientes y pueden funcionar al mismo tiempo en el mismo número.
- Limitaciones de la Coexistencia documentadas: velocidad de envío fija de 20
  mensajes/segundo, el vacío de datos de webhook en los mensajes enviados desde
  WhatsApp para Windows o WearOS y las funciones no admitidas (llamadas de
  voz/video, insignia OBA, mensajes temporales/de visualización única/de
  grupo).
- Campos de facturación en el webhook de estado: el `data` de `message.status`
  ahora incluye los objetos `conversation` y `pricing` de Meta cuando están
  presentes.
- Administración de plantillas: `POST /api/v1/send/templates` (crear),
  `POST /api/v1/send/templates/{id}` (editar la plantilla existente, conservando
  su id y su historial), `DELETE /api/v1/send/templates/{name}` (eliminar);
  `GET /api/v1/send/templates` ahora devuelve un `id` (id de la plantilla en
  Meta).
- Analíticas de precios: `GET /api/v1/analytics/pricing`.
- Automatización conversacional: `GET /api/v1/automation`,
  `POST /api/v1/automation`.
- Códigos QR: `POST /api/v1/qr-codes`, `GET /api/v1/qr-codes`,
  `DELETE /api/v1/qr-codes/{code}`.
- API de bloqueo: `POST /api/v1/block`, `DELETE /api/v1/block`,
  `GET /api/v1/block`.
- Perfil de empresa: `GET /api/v1/profile`, `PATCH /api/v1/profile`,
  `POST /api/v1/profile/name`, `POST /api/v1/profile/photo`.
- Eliminación de multimedia: `DELETE /api/v1/media/{mediaId}`.
- Nuevos tipos de mensaje: `POST /api/v1/send/location`,
  `POST /api/v1/send/contacts`; `POST /api/v1/send/media` acepta
  `type: sticker`; `POST /api/v1/send/text` acepta un booleano opcional
  `previewUrl` para la vista previa de enlaces.
- Endpoints para descargar y subir multimedia (`GET /api/v1/media/{mediaId}`,
  `POST /api/v1/media`).
- Consulta de un solo mensaje (`GET /api/v1/send/messages/{id}`), números
  conectados (`GET /api/v1/send/numbers`), confirmaciones de lectura
  (`POST /api/v1/send/read`).
- Indicador de escritura (`POST /api/v1/send/typing`), reacciones
  (`POST /api/v1/send/reaction`), mensajes interactivos
  (`POST /api/v1/send/interactive`), respuestas citadas (`replyTo` opcional en
  los endpoints de envío de texto/plantilla/multimedia).
- Payload de webhook enriquecido: `media_url`, `contact_name`, `context`,
  `referral`.
- Eventos de webhook `account.<field>` para alertas a nivel de la WABA.

## Guías

- [Qué necesitas para conectar un número por Coexistencia](https://zapclaw.app/es/coexistence-requirements.html)
- [Meta te pide eliminar tu cuenta de WhatsApp Business: no lo hagas](https://zapclaw.app/es/coexistence-delete-account.html)
- [Número no elegible para la Coexistencia](https://zapclaw.app/es/coexistence-not-eligible.html)
- [Número de WhatsApp conectado a otro proveedor: cómo cambiar de proveedor](https://zapclaw.app/es/whatsapp-number-connected-to-another-provider.html)
- [Coexistencia en Alemania y la UE](https://zapclaw.app/es/coexistence-germany-eu.html)
- [Webhook hacia tu propia IA, sin respuestas automáticas](https://zapclaw.app/es/whatsapp-webhook-local-ai.html)
- [¿Puede una IA responder a mis clientes en WhatsApp? Lo que permiten las reglas](https://zapclaw.app/es/whatsapp-ai-answer-customers.html)
- [Chatwoot en la API oficial de WhatsApp, sin App Review](https://zapclaw.app/es/chatwoot-whatsapp-official-api.html)
- [Chatwoot responde 401 a los webhooks de WhatsApp: las dos causas y la solución](https://zapclaw.app/es/chatwoot-whatsapp-webhook-401.html)
- [API oficial de WhatsApp sin empresa registrada](https://zapclaw.app/es/whatsapp-api-without-cnpj.html)

## Caso: Monely

- [Monely en la API oficial de WhatsApp](https://zapclaw.app/es/case-monely.html): una app de finanzas personales de la misma empresa que tiene sus números de WhatsApp en ZapClaw desde julio de 2026, con Idempotency-Key en cada respuesta y los mensajes recibidos en su webhook.

## Legal

- [Política de privacidad](https://zapclaw.app/privacy.html)
- [Términos del servicio](https://zapclaw.app/terms.html)
- [Eliminación de datos](https://zapclaw.app/data-deletion.html)