# Funnelchat: WhatsApp desde tu código

> Las instrucciones de la API de Funnelchat para tu agente de IA, en un solo archivo: guárdalo en tu proyecto (por ejemplo, como `FUNNELCHAT.md`) y nómbralo desde `AGENTS.md`. Es lo mismo que la skill `funnelchat`: el primer uso entero y, de lo demás, el índice con el enlace al texto de cada tema. Se baja de https://developers-portal.funnelchat.app/ia/instrucciones.md.
>
> Léelo cuando la persona quiere mandar o recibir mensajes de WhatsApp desde su código con Funnelchat, sincronizar su CRM, armar un bot de atención, automatizar grupos, campañas o difusiones, o el código usa FUNNELCHAT_API_KEY.

Usa solo lo que dicen este archivo y los textos que enlaza: no inventes rutas, campos, eventos ni errores. Si algo no está acá,
dile a la persona que no lo encuentras en la documentación de la API de Funnelchat.

## Lo básico

- **URL base:** `https://api.funnelchat.com`. Cada llamada es la URL base + la ruta completa, que empieza con `/api/v1/`.
- **Cabeceras:** `Authorization: Bearer $FUNNELCHAT_API_KEY` y `Accept: application/json`; si mandas un cuerpo,
  `Content-Type: application/json`.
- **La clave sale de la variable de entorno `FUNNELCHAT_API_KEY`. Nunca se la pidas a la persona en el chat**, ni la
  escribas en el código, en un log o en un archivo que se suba a un repositorio. Si no está definida, dile que la
  defina. La crea el titular de la cuenta en el panel de Funnelchat (**Desarrolladores › Crear clave**) y se muestra una
  sola vez; lleva un `|`, así que en un `.env` va entre comillas simples (`FUNNELCHAT_API_KEY='…'`).
- **Permisos:** cada llamada de abajo y de los textos enlazados dice qué casilla del panel pide, como «Área → Casilla». Si falta, la API
  responde `403 permission_denied`: la persona tiene que crear una clave con esa casilla marcada.
- **Errores:** el cuerpo trae `error` (un código estable) y `message`; un `422` trae además `errors`. Decide por el
  código HTTP y por `error`, nunca por `message`. `402 payment_required`: el pago de la cuenta o del workspace está vencido, reintentar
  no sirve (`402 plan_cap_reached`, en las acciones de grupo y al crear un grupo, es el tope del plan). `404 not_found`:
  no existe o es de otra cuenta o de otro workspace (responde igual; un número de otra cuenta da este `404` antes que
  cualquier otro error). `500 internal_error` (en los envíos, también `gate_misconfigured`): reintenta más tarde y, en un
  envío, busca antes el mensaje por su `client_reference`.
- **Límites:** hasta 10 000 llamadas por día por clave en accounts y otras tantas en communities (se reinicia a
  las 00:00 UTC; `429 daily_cap_exceeded`; conversations no tiene tope diario) y topes por minuto por grupo de llamadas, que según la llamada se cuentan por
  usuario (lo comparten todas sus claves y su uso del panel), por workspace, por clave o por número (`429 rate_limited`):
  espera los segundos de la cabecera `Retry-After` y reintenta. Los envíos de mensajes no tienen tope por minuto: los
  limita el ritmo de cada número, con el mismo `429 rate_limited`. Con `429 mac_lockout_24h` o
  `mac_limit_reached` (límite de contactos activos) no hay `Retry-After`, reintentar no sirve y no se guarda ningún
  mensaje: díselo a la persona.
- **Workspaces:** cada clave ve y opera solo el workspace donde se creó.

## El primer uso

1. **La clave**, en `FUNNELCHAT_API_KEY`.
2. **El número:** primero `GET /api/v1/devices`. Si ya hay uno conectado (`connected` en `1`) que le sirve a la
   persona, úsalo y no conectes otro; si hay varios, pregúntale cuál. Si no hay ninguno, `POST /api/v1/connect-links`
   devuelve la `url` del link de alta, una sola vez: con `{"type": "qr"}`, quien va a conectar su número la abre en una
   pantalla que no sea la de ese celular y escanea el QR con WhatsApp, en **Dispositivos vinculados**; con
   `{"type": "meta", "allowed_connection_types": ["dedicated"], "provision_us_number": true}`, pide un número de EE. UU.
   de Funnelchat (oficial: inicia sesión con Facebook y Meta le cobra los mensajes). Con `device_id`, el link reconecta
   un número de la cuenta. Sabes que quedó conectado por el evento `device.connected` o por `GET /api/v1/devices`
   (`connected` en `1`); su `id` es el `device_id`. Detalle: «Números» (en este archivo).
3. **Mandar un mensaje a un teléfono:** `POST /api/v1/message/send-message` con
   `{"device_id": "dev_Ac7Ku7iIZDXJTjdCu0UB1mX", "phone": "5491122334455", "text": "¡Hola!"}`, el teléfono con código de país. Responde el
   mensaje en `queued`. Detalle: «Mensajes» (en este archivo).
4. **Saber si lo leyeron:** crea un webhook con `POST /api/v1/webhooks`, `url` y
   `"events": ["message.status_changed"]`, y guarda el `secret` de la respuesta. Cada cambio llega con `data.status`:
   `sent`, `delivered`, `read` (lo leyeron) o `failed`. Detalle: «Webhooks» (en este archivo).
5. **Seguir un grupo:** los grupos del número están en `GET /api/v1/devices/{device}/groups`.
   `POST /api/v1/groups/{group}/import`, con el `uid` del grupo y `{"device_id": "dev_Ac7Ku7iIZDXJTjdCu0UB1mX"}`, lo sigue: desde ahí llegan
   `group_participant.joined` y `group_participant.left`. Para escribirle no hace falta seguirlo antes. Detalle:
   «Grupos» (en este archivo).

## Más funciones

Después del primer uso, la API sirve para mucho más, en dos partes:

- **Funciones de WhatsApp:** administrar tus números (editarlos, borrarlos, reiniciar su sesión, su QR, su nombre de
  usuario, la salud de uno oficial, su historial de conexión y su cola de mensajes), atender una conversación
  (responderle a un contacto por su `id`, leído, «escribiendo…», reacciones, reenviar y tarjetas de contacto), grupos y
  sus acciones (crear un grupo, participantes, administradores, link de invitación, solicitudes, y los canales y grupos
  de anuncios de un número), plantillas de Meta, formularios de WhatsApp, Conversions API y costos de WhatsApp y cuentas
  de Meta.
- **Funciones de Funnelchat:** contactos y conversaciones, etiquetas y campos personalizados, notas, tableros, tickets,
  respuestas rápidas, automatizaciones y carpetas de flujos, difusiones, campañas de grupos, envíos programados,
  estadísticas de grupos (también por país), puntaje, ventas, dominios propios, tu cuenta, tu equipo y tu consumo de
  contactos activos, alertas (qué alerta le llega a cada destino, silencio y reporte diario), y más sobre tus webhooks.

Para enterarte de lo que pasa sin consultar en un bucle, cada tema tiene sus eventos. Cada tema tiene su referencia,
abajo: lee solo la del tema que necesitas, antes de escribir el código.

## Trampas

- **Nombra cada evento.** `events` del webhook no tiene comodín (`*` no es un valor aceptado): pide cada evento por su
  nombre, también `message.status_changed`. Para sumar uno, usa «Editar un webhook» (`PUT /api/v1/webhooks/{id}`)
  con la lista completa.
- **El envío por teléfono crea el contacto.** No lo crees antes: si el teléfono todavía no es contacto, el envío lo crea
  en el workspace de la clave. La respuesta en `queued` no es enviado: el resultado llega por
  `message.status_changed`. No reenvíes un mensaje `queued`: lo duplicarías.
- **El freno de importaciones.** Seguir un grupo, también al escribirle por primera vez, cuenta en un tope de 5 por
  minuto en cada número. `429 import_rate_limited` trae `retry_after` en segundos: espera ese tiempo y reintenta.
- **Grupos, solo con números por QR.** Seguir un grupo con un número oficial responde `422 provider_unsupported`. Para
  escribirle a un grupo, el número tiene que ser administrador del grupo.
- **Ventana de 24 horas con número oficial.** Por un número oficial de WhatsApp, a quien no te escribió en las últimas
  24 horas (también a un teléfono nuevo) solo le puedes mandar una plantilla aprobada: el texto responde
  `422 window_closed`. Por un número conectado por QR no pasa.
- **La plantilla no está en la lista.** Las que la persona crea directamente en Meta llegan solas una vez por día. Si
  acaba de crear una y no aparece en `GET /api/v1/templates`, tráela de Meta con
  `POST /api/v1/devices/{device}/templates` (solo números oficiales; pide **Contactos y conversaciones → Editar**) y
  vuelve a listar: con `in_progress`, en unos segundos. No concluyas que no existe. Detalle:
  «Mensajes» (en este archivo).
- **Grupos: el envío no sale en la llamada.** Mandar un mensaje a un grupo (y cualquier acción de grupo) responde `202`
  con `action_id`: para saber cómo salió, `GET /api/v1/groups/actions/{action}` o los eventos `group_action.completed`
  y `group_action.failed`. No repitas el pedido. Detalle: «Grupos» (en este archivo).
- **Pide confirmación antes de lo que no se deshace o borra algo.** Las llamadas marcadas «No se puede deshacer»
  (desconectar un número con `POST /api/v1/devices/{device}/clean`, borrarlo, reiniciar su sesión, vaciar su cola de
  mensajes, borrar un dominio propio) y cualquiera que borra, cancela, vacía o saca algo (contactos, etiquetas, campos,
  difusiones, tableros, formularios, notas…): solo con un pedido explícito de la persona para eso, y antes de llamar
  confírmale qué vas a cambiar, con su nombre y su `id`. Nunca para «probar» ni para arreglar otro error. Detalle:
  [Administrar tus números](https://developers-portal.funnelchat.app/ia/mas-funciones/whatsapp/administrar-tus-numeros.md).
- **El estado de un número no trae el QR.** Con una clave, `qrCode` de `GET /api/v1/devices/{device}/status` llega
  siempre vacío: para conectar o reconectar un número, crea un link de alta (`POST /api/v1/connect-links`, con
  `device_id` para reconectar). Detalle: [Administrar tus números](https://developers-portal.funnelchat.app/ia/mas-funciones/whatsapp/administrar-tus-numeros.md).
- **Crear o actualizar cambia el nombre y el email.** `POST /api/v1/contacts/update-or-create` con un teléfono que ya
  es contacto le actualiza el `name` y el `email` que mandes: manda los que tienen que quedar. `POST /api/v1/contacts`
  con uno que ya existe responde `200` con ese contacto y no le cambia nada, tampoco sus `custom_fields`. Detalle:
  [Contactos y conversaciones](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/contactos-y-conversaciones.md).
- **Agregar una etiqueta puede mandar mensajes.** `POST /api/v1/contacts/add-tags` recibe una lista (un elemento por
  contacto y etiqueta, hasta 200). Con un solo elemento arranca, como en el panel, la automatización «Tag agregado» de
  esa etiqueta, que puede escribirle al contacto; con dos o más, o con `?bulk=true`, no arranca ninguna. Agregar y
  quitar responden `200` sin cuerpo aunque un elemento no haga nada: confirma con `GET /api/v1/contacts/{contact}/tags`.
- **El valor de un campo personalizado es texto, en el formato de su tipo.** `"1500"`, no `1500`; una fecha,
  `AAAA-MM-DD`; una URL, con `https://`. Con otro formato la API responde `422`: al crear un contacto con
  `custom_fields`, todo o nada; en `POST /api/v1/contacts/attach-custom-field`, que responde `200` aunque falle uno,
  en el `status` de ese elemento: revisa cada uno. Detalle:
  [Etiquetas y campos personalizados](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/etiquetas-y-campos.md).
- **La reacción no queda con el `202`.** Poner o quitar una reacción responde `202`: aceptada, no aplicada. Si al final
  no se aplica, llega `message.reaction_failed`; no la reintentes en un bucle. Detalle:
  [Atender una conversación](https://developers-portal.funnelchat.app/ia/mas-funciones/whatsapp/atender-una-conversacion.md).
- **En `form_id` va el `family_id`.** `GET /api/v1/forms` trae de cada formulario `id` (una versión) y `family_id` (el
  formulario): para mandarlo con `POST /api/v1/contacts/{contact}/message/form`, usa el `family_id`. Lo que contestó
  el contacto llega por `whatsapp_form.completed`, con `data.form.id` igual a ese `family_id`. Detalle:
  [Formularios de WhatsApp](https://developers-portal.funnelchat.app/ia/mas-funciones/whatsapp/formularios.md).
- **«Escribiendo…» y formularios, solo con número oficial.** Por un número conectado por QR responden `422`
  (`provider_unsupported` y `number_not_eligible`). «Escribiendo…» también marca como leído: pídelo solo justo antes de
  responder. Detalle: [Atender una conversación](https://developers-portal.funnelchat.app/ia/mas-funciones/whatsapp/atender-una-conversacion.md) y
  [Formularios de WhatsApp](https://developers-portal.funnelchat.app/ia/mas-funciones/whatsapp/formularios.md).
- **Verifica la firma.** Cada entrega trae `X-Funnelchat-Signature: t=…,v1=…`. Calcula el HMAC-SHA256 de
  `t + "." + el cuerpo crudo` con el secreto completo del webhook (con su `whsec_`), antes de parsear el JSON;
  compáralo con `v1` en tiempo constante y rechaza si no coincide o si `t` está a más de 300 segundos de la hora
  actual. Las funciones probadas, en Node.js, Python y PHP, están en «Webhooks» (en este archivo).

## Referencias

Lee la del tema antes de escribir el código (las del primer uso están abajo, en este archivo; las demás, en su enlace): cada llamada con su permiso, sus campos, sus respuestas y sus errores, y cada evento con su ejemplo. Lee solo la del tema que necesitas.

### Primer uso

- «Conectar un número» (en este archivo): Conectar un número con el link de alta, por QR o con un número de EE. UU. de Funnelchat, ver los tuyos y saber cuándo se conecta o se desconecta.
- «Mensajes» (en este archivo): Mandar un texto o una plantilla a un teléfono, traer de Meta una plantilla que no aparece, saber si lo leyeron y recibir mensajes.
- «Grupos» (en este archivo): Ver los grupos de un número, escribirles sin importarlos antes, saber cómo salió el envío y seguirlos para enterarte de quién entra y quién sale.
- «Webhooks» (en este archivo): Crearlos, verlos, probarlos y borrarlos, cómo llega cada entrega, todos los eventos (con el tema que detalla cada uno) y cómo verificar la firma.

### Funciones de WhatsApp

- [Administrar tus números](https://developers-portal.funnelchat.app/ia/mas-funciones/whatsapp/administrar-tus-numeros.md): Mira, edita, desconecta o borra tus números, conéctalos por QR desde tu sistema, revisa su salud, su historial de conexión y su cola de mensajes, y entérate cuando algo cambia.
- [Atender una conversación](https://developers-portal.funnelchat.app/ia/mas-funciones/whatsapp/atender-una-conversacion.md): Respóndele a un contacto por su id, marca como leído lo que te escribió, muestra «escribiendo…», reacciona a sus mensajes, reenvía un mensaje y compártele una tarjeta de contacto.
- [Grupos y sus acciones](https://developers-portal.funnelchat.app/ia/mas-funciones/whatsapp/grupos-y-acciones.md): Ve los grupos de tu workspace y sus participantes, crea grupos, suma y saca personas, cambia sus datos y su link, responde a las solicitudes para unirse y entérate de lo que pasa adentro.
- [Plantillas de Meta](https://developers-portal.funnelchat.app/ia/mas-funciones/whatsapp/plantillas.md): Crea, revisa y edita tus plantillas de WhatsApp, mira sus métricas, bórrala de un número y entérate cuando Meta cambia su estado.
- [Formularios de WhatsApp](https://developers-portal.funnelchat.app/ia/mas-funciones/whatsapp/formularios.md): Arma tus formularios de WhatsApp, publícalos en tus números oficiales, mándaselos a tus contactos, cámbialos con versiones nuevas y lee sus respuestas y sus métricas.
- [Conversions API](https://developers-portal.funnelchat.app/ia/mas-funciones/whatsapp/conversions-api.md): Prepara y prueba la conexión de tus números oficiales con la Conversions API de Meta: el dataset de cada cuenta de WhatsApp Business y su estado.
- [Costos de WhatsApp y cuentas de Meta](https://developers-portal.funnelchat.app/ia/mas-funciones/whatsapp/costos-y-cuentas-de-meta.md): Mira cuánto te cuesta WhatsApp en un mes y las cuentas de WhatsApp Business de tus números oficiales, con su límite de mensajes por día.

### Funciones de Funnelchat

- [Contactos y conversaciones](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/contactos-y-conversaciones.md): Busca tus contactos y los de cada número, créalos o actualízalos por su teléfono, edítalos o bórralos, mira su ventana de 24 horas, lee y cuenta tus conversaciones, márcalas todas como leídas o no leídas y entérate cuando algo cambia.
- [Etiquetas y campos personalizados](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/etiquetas-y-campos.md): Ve, arma y borra tus etiquetas y tus campos personalizados, agrégales o quítales etiquetas a tus contactos, guárdales tus propios datos y entérate cuando un contacto recibe o pierde una etiqueta.
- [Notas de un contacto](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/notas.md): Lee las notas que tu equipo dejó sobre un contacto, agrega una nueva o borra la que ya no sirve.
- [Tableros](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/tableros.md): Arma tus tableros y sus etapas, mira qué contactos hay en cada etapa, muévelos o sácalos, y entérate cada vez que un contacto cambia de etapa.
- [Tickets](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/tickets.md): Abre tickets sobre tus contactos, dáselos a alguien de tu equipo, edítalos, ciérralos y vuelve a abrirlos.
- [Respuestas rápidas](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/respuestas-rapidas.md): Mira las respuestas rápidas de tu equipo, crea nuevas, edítalas o bórralas.
- [Automatizaciones y carpetas de flujos](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/automatizaciones.md): Mira tus flujos y sus pasos, qué automatizaciones se corrieron sobre un contacto y quiénes están en curso o pausados en cada flujo, cancela una ejecución, pausa las automatizaciones de un contacto, ordena tus flujos en carpetas y entérate cuando una termina o falla.
- [Difusiones](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/difusiones.md): Mira tus difusiones, a quién llegan, sus estadísticas, su costo y el resultado con cada contacto, cancela una que quedó pausada, borra una que todavía no salió y ordénalas en carpetas.
- [Campañas de grupos](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/campanas.md): Mira tus campañas de grupos, sus grupos, quién entra y quién sale, y cómo van sus pipelines y planes de operación.
- [Envíos programados](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/envios-programados.md): Mira tus envíos programados a grupos, sus grupos, cómo salió cada uno en cada grupo, cada vez que salió uno que se repite, cuántos lo leyeron y qué respondieron, y entérate cuando termina o falla.
- [Estadísticas de tus grupos](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/estadisticas.md): Mira cuántas personas entran y salen de tus grupos y campañas, cuántas están activas, tus grupos por estado, los clics en tus links y de qué países son.
- [Puntaje de tus contactos](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/puntaje.md): Mira el puntaje de tus contactos y cómo se reparte, ajusta el de uno y configura cómo se calcula.
- [Ventas](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/ventas.md): Mira las ventas que registran tus plataformas de pagos, sus métricas, el embudo de conversaciones a compras, las ventas por plataforma y los productos de cada una.
- [Dominios propios](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/dominios-propios.md): Usa un dominio tuyo, como `go.mimarca.com`, para el servicio de redirección de Funnelchat: lo registras, creas en tu DNS los registros que te indica, lo verificas y lo borras cuando ya no lo usas.
- [Tu cuenta y tu equipo](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/cuenta-y-equipo.md): Mira tu cuenta y su plan, tu consumo de contactos activos y las personas de tu equipo, y entérate de tus cobros, tu suscripción y tu límite de contactos activos.
- [Alertas](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/alertas.md): Mira las alertas de tu operación y los teléfonos y webhooks que las reciben, elige qué alerta le llega a cada uno, y configura el horario de silencio y el reporte diario.
- [Más sobre tus webhooks](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/mas-webhooks.md): Mira uno de tus webhooks y sus entregas, edítalo o páusalo y consulta los tipos de evento que hay.

## Conectar un número

Conectar un número con el link de alta, por QR o con un número de EE. UU. de Funnelchat, ver los tuyos y saber cuándo se conecta o se desconecta.

### Antes de conectar: los números que ya tiene

`GET /api/v1/devices` lista los números de la cuenta (la clave necesita **Números de WhatsApp → Ver**). Cada uno trae
`id` (el `device_id` de las demás llamadas), `alias`, `number`, `connected` (`1` si está conectado, `0` si no) y
`connection`: `qr` (por QR), `coexistence` o `dedicated` (los dos, oficiales de WhatsApp).

- **Si ya hay un número conectado que le sirve, úsalo: no conectes otro.** Dile cuál encontraste y pregúntale si lo
  usan; si hay varios, pregúntale cuál. Usar uno que ya está no ocupa otro lugar del plan.
- Si el que quiere usar está desconectado (`connected` en `0`), ofrécele reconectarlo: ver «Reconectar un número».
- Si no tiene ninguno, pregúntale cómo lo quiere conectar: su número por QR, o un número de EE. UU. de Funnelchat.

### Conectar un número, paso a paso

Las dos maneras usan el link de alta.

1. `POST /api/v1/connect-links` con uno de estos cuerpos. La clave necesita **Números de WhatsApp → Crear, conectar y
   borrar**.
   - **Su número, por QR:** `{"type": "qr"}`. Opcional, solo por QR: `country` (el país del teléfono que va a
     escanear, dos letras ISO, por ejemplo `"mx"`: si la sesión se abre desde otro país, WhatsApp puede rechazar la
     vinculación).
   - **Un número de EE. UU. de Funnelchat:**
     `{"type": "meta", "allowed_connection_types": ["dedicated"], "provision_us_number": true}`. Antes, cuéntale a la
     persona lo de «Antes de pedir un número de EE. UU.».
   - Opcionales en los dos: `external_reference` (tu propia referencia, por ejemplo `"mi-numero"` o el id de tu
     cliente: pasa al número que se conecte), `return_url` (https: adonde vuelve la persona al terminar, con el
     resultado en la query string: `connect_link_id`, `status` —`completed` o `failed`—, `device_id` o `error_code`) y
     `expires_in_minutes` (de 30 minutos a 7 días; 24 horas si no lo mandas).
2. La respuesta (`201`) trae en `data` el `id` del link y su `url`, **la única vez que aparece**: quien la tenga puede
   conectar un número a esta cuenta mientras el link esté pendiente. Dásela solo a quien va a conectar: a la persona,
   si es su número, o a su cliente. No la guardes en un log ni en un repositorio.
3. Quien conecta abre la URL; abrirla no gasta el link.
   - **Por QR:** la abre en una pantalla que no sea la del celular que va a conectar (por ejemplo, la computadora) y
     toca el botón para conectar. Desde ese momento tiene **10 minutos** para escanear el QR con WhatsApp en el
     celular, en **Dispositivos vinculados**; si no, el link queda `failed` con `qr_timeout` y hay que pedir otro. La
     página renueva el QR sola.
   - **Número de EE. UU.:** elige el número de EE. UU. de Funnelchat, inicia sesión con Facebook y sigue los pasos de
     Meta con su cuenta de WhatsApp Business. El número se crea al terminar.
4. Para saber cuándo quedó conectado, una de estas:
   - el webhook `device.connected`: trae `data.device` (con su `id`, que es el `device_id` de las demás llamadas, y tu
     `external_reference`) y `data.connect_link_id` (el `id` del link);
   - `GET /api/v1/devices?external_reference=mi-numero`: el número aparece cuando el link lo crea; `connected` es `1`
     cuando quedó conectado y `0` si no. Su `id` es el `device_id`. Si consultas así, espera unos segundos entre
     consulta y consulta;
   - la `return_url`, si la mandaste.

- Cada workspace puede tener hasta 20 links pendientes (`429 too_many_open_links`).
- Para saber después si un número sigue conectado: `GET /api/v1/devices` (campo `connected`) o el webhook
  `device.disconnected`.

### Antes de pedir un número de EE. UU.

Dile a la persona, antes de crear el link:

- Va a iniciar sesión con Facebook y seguir los pasos de Meta con su cuenta de WhatsApp Business.
- Meta le cobra los mensajes con el medio de pago de su cuenta de WhatsApp Business: tiene que cargarlo en Meta.
- Ocupa un lugar del plan y cuenta en el tope de números de EE. UU.: hasta 3 por cuenta (menos si el plan tiene menos
  lugares; 1 en las cuentas de prueba). Si ya llegó a ese tope, el link termina `failed` con `quota_exceeded` al
  usarlo.
- Es un número oficial (`connection` `dedicated`): no sigue grupos —eso es solo con números por QR— y a un teléfono que
  no le escribió en las últimas 24 horas solo le manda una plantilla aprobada (ver «Mandar mensajes»).

Si la página falla en el inicio de sesión de Facebook (`facebook_auth_failed`) o Meta da un error (`meta_error`), el
link **sigue `pending`** y la persona puede intentarlo de nuevo con el mismo link; al quinto intento fallido pasa a
`failed` con ese código. `quota_exceeded`, `trial_number_blocked` y `number_not_owned` lo cierran al primer intento.

### Reconectar un número

`POST /api/v1/connect-links` con `device_id` (el `id` de un número de la cuenta) reconecta ese número en lugar de sumar
uno: no ocupa un lugar nuevo y anula los links de reconexión anteriores de ese número. El `type` tiene que coincidir con
el del número: `qr` si su `connection` es `qr`, `meta` si es oficial (y con `meta`, `allowed_connection_types` es
obligatorio). Por ejemplo, `{"type": "qr", "device_id": "dev_Ac7Ku7iIZDXJTjdCu0UB1mX"}`. `country` y `provision_us_number` no valen con
`device_id`. La URL se trata igual que la de un alta.

### Los webhooks de los números

`device.connected` (un número quedó conectado) y `device.disconnected` (un número perdió la conexión) traen
`data.device` (`id`, `name`, `number`, `connection` —`qr`, `coexistence` o `dedicated`— y `external_reference`),
`data.connect_link_id` (el link de alta que lo conectó, o `null`) y `data.workspace_id` (el id del workspace, un
entero). `device.disconnected` trae además `reason`:
`qr_logged_out` (se cerró la sesión de un número por QR), `meta_account_not_registered` (un número oficial dejó de estar
registrado en Meta), `shadow_ban_protection` (Funnelchat lo desconectó para protegerlo de un posible bloqueo),
`disconnected_by_user` (alguien de la cuenta lo desconectó) o `unknown` (no se sabe por qué).

### Errores al conectar

- `403 numbers_not_included`: el plan no incluye números. `403 number_limit_reached`: no queda lugar en el plan.
  `403 connect_not_allowed`: quien llama no es el titular de la cuenta. `402 payment_required`: el pago de la cuenta
  o del workspace está vencido. Reintentar no los arregla: díselo a la persona.
- Cada workspace tiene como máximo un número por QR sin conectar (la cuenta entera, si no usa workspaces): con otro
  pendiente, crear un número responde `409 pending_number_exists` con su `device_id`.
- El lugar del plan (el del workspace, si paga su propio plan; si no, el de la cuenta) se controla también al usar el link: si ya no queda, el link termina `failed` con `quota_exceeded`.
  Con un número de EE. UU., lo mismo si la cuenta ya llegó a su tope de números de EE. UU.
- `422 invalid_request`: un dato no es válido; el cuerpo dice cuál. También si `provision_us_number` va sin `dedicated`
  en `allowed_connection_types` o con `device_id`.
- `422 invalid_reference_device`: el `device_id` no es un número de la cuenta. `422 connection_type_mismatch`: el
  `type` no coincide con el del número.
- `503 meta_connect_disabled`: el alta oficial por link (también el número de EE. UU.) no está habilitada en este
  momento. Díselo a la persona; su número por QR sí se puede conectar.
- Para conectar su propio número oficial de WhatsApp (de Meta), indícale a la persona el panel de Funnelchat.
- Un número conectado por QR no es oficial: WhatsApp puede restringirlo o bloquearlo si manda mensajes que la gente no
  espera.

### Llamadas

#### Conectar un número

`POST /api/v1/connect-links` · permiso **Números de WhatsApp → Crear, conectar y borrar** · área accounts · `operationId` `connectLink.store`

**Para qué sirve:** Sirve para conectar un número de WhatsApp a tu cuenta —el tuyo o el de tu cliente— desde una página de Funnelchat, sin entrar al panel: le das la `url` de un solo uso a quien lo va a conectar y te enteras del resultado por webhook o en tu URL de vuelta.

> 🔑 **Da el control de un WhatsApp.** Por eso pide **Números de WhatsApp → Crear, conectar y borrar**: crear un número ocupa un lugar del plan, y quien escanee su QR o use un link de alta conecta un teléfono a esta cuenta. Trata el QR y la URL del link como un secreto.

Un link de un solo uso para que tu cliente conecte un número de WhatsApp a tu cuenta, desde
una página de Funnelchat y sin entrar al panel. Envíale la `url` de la respuesta: es la
**única vez** que aparece (Funnelchat guarda solo un hash) y quien la tenga puede conectar
un número a tu cuenta mientras el link esté pendiente. Trátala como un secreto.

Abrir la página no usa el link (la vista previa de un mensajero no lo gasta): el link se
usa cuando tu cliente toca el botón para conectar.

- `type: "qr"`: al tocar el botón se crea el número (si no es una reconexión) y la página
  muestra el QR, que renueva sola cada 5 segundos. Tu cliente tiene **10 minutos** desde
  que toca el botón para escanearlo; si no lo escanea a tiempo, el link queda `failed` con
  `qr_timeout` y el número que creó el link se borra (libera el lugar). Si el alta tomó un
  lugar libre que tu cuenta ya tenía, ese lugar no se borra: queda como estaba. `country`
  (opcional, ISO 3166-1 alfa-2, por ejemplo `"mx"`) es el país desde donde se abre la
  sesión de WhatsApp del número: conviene que sea el del teléfono de tu cliente, porque
  WhatsApp puede rechazar la vinculación («no se puede vincular ahora») si la sesión se abre
  desde otro país. Sin `country` se usa el país que detecta el navegador de tu cliente en
  la página y, si no detecta ninguno, Colombia (`co`). No vale con `device_id` (una
  reconexión no crea el número) ni con `type: "meta"`.
- `type: "meta"`: número oficial con el Embedded Signup de Meta, el mismo del panel. El
  número se crea **al terminar** el Embedded Signup. `allowed_connection_types` es
  obligatorio: `coexistence` (el número sigue en la app WhatsApp Business), `dedicated` (un
  número solo para la API) o los dos, y entonces elige tu cliente. `provision_us_number:
  true` ofrece además un número de EE. UU. del pool de Funnelchat: es siempre un número
  dedicado, así que exige `dedicated` en `allowed_connection_types` y no vale con
  `device_id`; si no, responde `422 invalid_request`. Si falla el inicio de sesión de
  Facebook (`facebook_auth_failed`) o Meta da un error (`meta_error`), el link **sigue
  `pending`** y tu cliente puede intentarlo de nuevo con el mismo link; al quinto intento
  fallido el link pasa a `failed` con ese código. Mientras el alta oficial por link no esté
  habilitada responde `503 meta_connect_disabled`. El cliente le paga a Meta los mensajes
  con el medio de pago de su cuenta de WhatsApp Business: tiene que cargarlo en Meta.

El cupo del plan y el pago de la cuenta se controlan al crear el link y otra vez al usarlo:
el link no reserva lugar. Con el pago vencido, crear el link responde `403`, y usarlo deja
el link `failed` con `quota_exceeded`. Con `device_id` el link **reconecta** ese número (no ocupa un lugar nuevo;
el `type` tiene que coincidir con el del número) y revoca los links de reconexión anteriores
de ese número. Cada workspace puede tener como máximo 20 links pendientes.

Para enterarte del resultado: el webhook `device.connected` (trae `connect_link_id` y
`external_reference`), la `return_url` o `GET connect-links/{link}`. Al terminar, la página
lleva a tu cliente a la `return_url` con el resultado **en la query string**, nada más:
`connect_link_id`, `status` (`completed` o `failed`), `device_id` (solo si completó) y
`error_code` (solo si falló); por ejemplo
`https://tu-sistema.com/vuelta?connect_link_id=<id del link>&status=completed&device_id=<id del número>`. Si tu
`return_url` ya trae parámetros, se suman a los tuyos. El link muere si revocas la clave de
API que lo creó.

Acepta el header `Idempotency-Key` (de 1 a 255 caracteres) para reintentar sin crear otro
link: la misma clave con el mismo cuerpo, desde el mismo workspace y dentro de las 24 horas,
devuelve el mismo link. Otro workspace de la cuenta puede usar la misma clave sin cruzarse
con este.

**Cuerpo** (`application/json`, obligatorio)

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `type` | string ∈ {"meta", "qr"} | sí | `meta`: official number (Embedded Signup of Meta). `qr`: number by QR code. |
| `allowed_connection_types` | array<string ∈ {"coexistence", "dedicated"}> | no | `type: meta` only, and required there: which official connections the customer may choose (`coexistence` keeps the WhatsApp Business app; `dedicated` does not). |
| `provision_us_number` | boolean | no | `type: meta` only: offer a US number of the Funnelchat pool. |
| `device_id` | string \| null | no | Reconnect THIS number of the account instead of adding one (uses no new place). Id opaco: un texto que empieza con `dev_`. Se usa tal como llega; no se arma ni se interpreta. |
| `same_number_as` | string \| null | no | `type: qr` only: add QR to this coexistence number of the account. Id opaco: un texto que empieza con `dev_`. Se usa tal como llega; no se arma ni se interpreta. |
| `country` | string \| null | no | `type: qr` only, and not with `device_id` (a reconnection creates nothing): country the WhatsApp session is opened from (ISO 3166-1 alpha-2, two letters, any case). |
| `external_reference` | string \| null | no | Your own reference; it is copied to the number the link creates. |
| `return_url` | string (uri) \| null | no | Where to send the customer at the end (https only). It receives only the result. |
| `expires_in_minutes` | integer \| null | no | How long the link lives, in minutes. |

**Respuestas**

- `201` — El link creado. `url` aparece solo en esta respuesta.

  | Campo | Tipo | Descripción |
  |---|---|---|
  | `data` | ConnectLinkResource |  |
  | `data.id` | string | Id opaco: un texto que empieza con `lnk_`. Se usa tal como llega; no se arma ni se interpreta. |
  | `data.type` | string |  |
  | `data.status` | string |  |
  | `data.url` | string |  |
  | `data.expires_at` | string |  |
  | `data.allowed_connection_types` | array<string> \| null |  |
  | `data.provision_us_number` | boolean |  |
  | `data.country` | string \| null |  |
  | `data.device_id` | string \| null | Id opaco: un texto que empieza con `dev_`. Se usa tal como llega; no se arma ni se interpreta. |
  | `data.external_reference` | string \| null |  |
  | `data.return_url` | string \| null |  |
  | `data.error_code` | string \| null |  |
  | `data.created_at` | string \| null |  |
  | `data.completed_at` | string \| null |  |

- `401` — Unauthenticated (`AccountsAuthenticationException`)
- `402` — El pago de la cuenta o del workspace está vencido (`payment_required`). Regularízalo en el panel de Funnelchat para seguir usando esta ruta.
- `403` — El plan no incluye números (`numbers_not_included`), no queda lugar (`number_limit_reached`) o quien llama no es el titular (`connect_not_allowed`).
- `422` — Datos inválidos (`invalid_request`; también `provision_us_number` sin `dedicated` o con `device_id`), `device_id` no es un número de la cuenta (`invalid_reference_device`), el `type` no coincide con el del número (`connection_type_mismatch`), `same_number_as` no admite QR (`qr_requires_coexistence`, `method_already_present`), la clave de idempotencia ya se usó con otro cuerpo (`idempotency_key_mismatch`) o el header `Idempotency-Key` está vacío o tiene más de 255 caracteres (`invalid_idempotency_key`).
- `429` — El workspace ya tiene el máximo de links pendientes (`too_many_open_links`), o se superó el límite de creaciones por minuto.. Cabeceras: `Retry-After`
- `503` — El alta de números oficiales por link no está habilitada en este momento (`meta_connect_disabled`).

#### Ver tus números

`GET /api/v1/devices` · permiso **Números de WhatsApp → Ver** · área accounts · `operationId` `device.index`

**Para qué sirve:** Sirve para listar tus números de WhatsApp con su proveedor, si están conectados y activos y su estado de salud, y obtener los IDs que usan las demás operaciones.

**Listado** · `perPage` de 1 a 100 (por defecto 25) · orden fijo: id ascendente · no acepta parámetros de orden.

`external_reference` filtra por tu propia referencia (igualdad exacta).

**Parámetros**

| Nombre | En | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
| `external_reference` | query | string \| null | no |  |

**Respuestas**

- `200` — Los números del workspace.

  | Campo | Tipo | Descripción |
  |---|---|---|
  | `[].id` | string | Id opaco: un texto que empieza con `dev_`. Se usa tal como llega; no se arma ni se interpreta. |
  | `[].alias` | string |  |
  | `[].image` | string |  |
  | `[].color` | string |  |
  | `[].number` | string |  |
  | `[].normalized_number` | string | `number` en formato internacional normalizado, para reconocer el mismo teléfono conectado por QR y como oficial. `null` mientras el número no está conectado. |
  | `[].first_conecction_at` | string |  |
  | `[].user_id` | string | Id opaco: un texto que empieza con `usr_`. Se usa tal como llega; no se arma ni se interpreta. |
  | `[].provider` | integer ∈ {1, 2, 3, 4} |  |
  | `[].waba_id` | string |  |
  | `[].phone_number_id` | string \| null | El identificador del número en Meta (`phone_number_id`) de un número oficial; `null` en los números por QR. |
  | `[].whatsapp_username` | string \| null |  |
  | `[].is_business` | integer |  |
  | `[].connected` | integer |  |
  | `[].active` | integer \| null |  |
  | `[].health` | string | El resumen del estado de salud de un número oficial, el mismo `health` de `GET devices/{device}/health`. `null` si el número no es oficial. |
  | `[].number_key` | string \| null | La identidad del teléfono de este número: se mantiene aunque se desconecte, y es el último teléfono para mostrar cuando `number` está vacío. |
  | `[].number_key_confirmed` | string | `true` cuando ese teléfono ya se conectó en este número; `false` si `number_key` es solo el teléfono que se espera conectar. |
  | `[].is_coexistence` | boolean |  |
  | `[].slot_state` | string | El estado del lugar del plan que ocupa: `held` (tiene o tuvo un teléfono), `pending` (todavía sin teléfono, pero ya ocupa un lugar), `reserved` (vacío y reservado por un alta en curso) o `free` (vacío, no ocupa lugar). |
  | `[].pool_suspended` | boolean | Si el número está suspendido por el plan (por ejemplo, porque el plan tiene menos lugares que números); `pool_suspension_reason` dice por qué, `pool_keep` si la cuenta eligió conservarlo y `qr_allowed` si se puede conectar por QR. |
  | `[].pool_suspension_reason` | string \| null |  |
  | `[].pool_keep` | boolean |  |
  | `[].qr_allowed` | boolean |  |
  | `[].can_change_to_meta` | boolean | `true` si este número por QR puede pasar a ser oficial en el mismo lugar, con el alta oficial del mismo teléfono. |
  | `[].connected_by_user_id` | string \| null | Quién de la cuenta hizo la conexión actual (`connected_by_name` es su nombre), o `null` si no se sabe; `abilities` dice qué puede hacer con este número quien llama. Id opaco: un texto que empieza con `usr_`. Se usa tal como llega; no se arma ni se interpreta. |
  | `[].connected_by_name` | string \| null |  |
  | `[].abilities` | object |  |
  | `[].abilities.connect` | boolean |  |
  | `[].abilities.disconnect` | boolean |  |
  | `[].abilities.delete` | boolean |  |
  | `[].abilities.update` | boolean |  |
  | `[].capabilities` | object | Qué se puede hacer con este número por la API, según cómo está conectado. |
  | `[].capabilities.messages` | object |  |
  | `[].capabilities.groups` | object |  |
  | `[].capabilities.statuses` | array<string> |  |
  | `[].connection` | string \| null ∈ {"qr", "coexistence", "dedicated", null} | Cómo está conectado el número: `qr`, `coexistence`, `dedicated`, o `null` si todavía no se sabe. `external_reference` es tu propia referencia. |
  | `[].external_reference` | string \| null |  |
  | `[].overloaded` | boolean | El número está sobrecargado (muchos grupos / conversaciones); `false` si nunca se evaluó. |
  | `[].overloaded_computed_at` | string (date-time) \| null |  |
  | `[].overloaded_groups_count` | integer \| null | En la última evaluación, cuántos grupos tenía el número; `null` si nunca se evaluó. |
  | `[].overloaded_one_to_one_count` | integer \| null |  |
  | `[].overloaded_has_pending_broadcast` | boolean |  |
  | `[].overloaded_has_active_flow` | boolean |  |
  | `[].overloaded_has_active_ai_agent` | boolean |  |
  | `[].overloaded_alert_level` | string | El evento de número sobrecargado: `loud` (sin descartar), `latent` (descartado en este episodio) o `none` (no está sobrecargado o nunca se evaluó). |
  | `[].overloaded_dismissed_at` | string (date-time) \| null |  |
  | `[].sync_all_groups` | boolean | `true` si el dueño activó "Sincronizar todos mis grupos y mensajes" para este número. |

- `401` — Unauthenticated (`AccountsAuthenticationException`)
- `403` — Quien llama no puede usar esta ruta (`forbidden`). Los códigos de workspace que puede traer `error` con una clave:
- `422` — Validation error (`AccountsValidationException`)
- `429` — Superaste un límite de llamadas. Espera los segundos que indica `Retry-After` antes de volver a llamar.. Cabeceras: `Retry-After`

### Los eventos

Llegan por webhook. Cómo crearlo, cómo llega cada entrega y cómo verificar la firma: «Webhooks» (en este archivo).

#### `device.connected`

Uno de los números de WhatsApp de la cuenta quedó conectado: al escanear el código QR o al terminar el alta de un número de WhatsApp Cloud. Trae `device.connection` (`qr`, `coexistence` o `dedicated`), `device.external_reference` y `connect_link_id` (el link de alta que lo conectó, o null).

Ejemplo:

```json
{
  "id": "evt_0f8e4b526c1d4c7a9a3e2b5d",
  "type": "device.connected",
  "version": 1,
  "occurred_at": "2026-10-05T03:00:00Z",
  "data": {
    "device": {
      "id": "dev_AFHtaOVjNBTEWzCuDrmxMPP",
      "name": "Ventas",
      "number": "5491100000000",
      "connection": "qr",
      "external_reference": "cliente-42"
    },
    "connected_at": "2026-10-05T03:00:00Z",
    "connect_link_id": "lnk_AEF0eLF7bcRyfgK70NSWVdy",
    "workspace_id": 37
  }
}
```

#### `device.disconnected`

Uno de los números de WhatsApp de la cuenta se desconectó y dejó de poder enviar o recibir. `reason` dice por qué: `qr_logged_out` (se cerró la sesión de un número por QR), `meta_account_not_registered` (un número oficial dejó de estar registrado en Meta y no se pudo volver a registrar solo), `shadow_ban_protection` (Funnelchat lo desconectó para protegerlo de un posible bloqueo), `disconnected_by_user` (alguien de la cuenta desconectó o borró los datos de un número oficial) o `unknown` (no se sabe por qué). Trae `device.connection`, `device.external_reference` y `connect_link_id` (el link de alta que conectó el número por última vez, o null).

Ejemplo:

```json
{
  "id": "evt_0f8e4b526c1d4c7a9a3e2b5d",
  "type": "device.disconnected",
  "version": 1,
  "occurred_at": "2026-10-05T03:00:00Z",
  "data": {
    "device": {
      "id": "dev_AFHtaOVjNBTEWzCuDrmxMPP",
      "name": "Ventas",
      "number": "5491100000000",
      "connection": "qr",
      "external_reference": "cliente-42"
    },
    "disconnected_at": "2026-10-05T03:00:00Z",
    "reason": "qr_logged_out",
    "connect_link_id": "lnk_AEF0eLF7bcRyfgK70NSWVdy",
    "workspace_id": 37
  }
}
```

## Mensajes

Mandar un texto o una plantilla a un teléfono, traer de Meta una plantilla que no aparece, saber si lo leyeron y recibir mensajes.

### Mandar un texto: una sola llamada

1. Elige el número que manda: el `id` de un número conectado de `GET /api/v1/devices` es el `device_id`.
2. `POST /api/v1/message/send-message` con `{"device_id": "dev_Ac7Ku7iIZDXJTjdCu0UB1mX", "phone": "5491122334455", "text": "¡Hola!"}`. `phone`
   es el teléfono con código de país. **No crees el contacto antes**: el teléfono se busca y, si todavía no es un contacto, el
   envío lo crea en el workspace de la clave, con el mismo permiso (**Contactos y conversaciones → Enviar**). Agrega
   `client_reference` (opcional: de 1 a 64 caracteres visibles, sin espacios; por ejemplo `pedido-8841`) para reconocer
   el envío: vuelve en el evento `message.status_changed` y en la consulta del mensaje. No pongas datos personales en ella.
3. La respuesta es `200` con `message`: el mensaje ya registrado, con su `id`, su `contact_id` (el contacto de ese
   teléfono, nuevo o el que ya existía; el mismo que traen los eventos `message.status_changed`) y `status: "queued"`.
   **`queued` no es enviado**: el resultado (`sent`, `delivered`, `read` o `failed`) llega por el webhook de
   `message.status_changed` o consultando `GET /api/v1/contacts/{contact}/messages/{message}`. No reenvíes un mensaje
   `queued`: lo duplicarías.

### A quién: `phone`, `contact_id` o `whatsapp_id`

- **`phone`** es el camino de arriba y sirve con cualquier número.
- **`contact_id`**, si ya lo tienes (por ejemplo, el `message.contact_id` de un envío anterior o el `data.contact.id` de
  un mensaje recibido), puede ir en lugar de `phone`. Si mandas los dos, tienen que ser del mismo contacto; si no,
  `422 recipient_mismatch`.
- **`whatsapp_id`**, solo con un número oficial de WhatsApp (WhatsApp Cloud): el identificador que manda Meta (BSUID,
  por ejemplo `US.13491208655302741918`), en lugar de `phone`. Por un número conectado por QR responde `422`.

### Fuera de las 24 horas: plantillas

Por un número oficial de WhatsApp (WhatsApp Cloud) solo puedes mandar un mensaje que no es plantilla a un contacto que te
escribió en las últimas 24 horas; si no, `send-message` responde `422 window_closed` y no manda nada. **Por eso, por un
número oficial, el primer mensaje a un teléfono nuevo es una plantilla.** Para escribirle o retomar la conversación
manda una plantilla aprobada:

- `GET /api/v1/templates` lista tus plantillas, con su estado de aprobación.
- `POST /api/v1/devices/{device}/templates/{template}/send-template` con `phone` (o `whatsapp_id`), que va siempre, y,
  si la plantilla tiene variables, `template_variables.body` (una lista de textos). Igual que el texto: si el teléfono
  todavía no es contacto, se crea; `contact_id` es opcional y, si lo mandas, tiene que ser el de ese teléfono. La
  respuesta es la misma: el mensaje en `queued`, con su `contact_id`. Si la plantilla no existe responde
  `404 template_not_found` (y `404 not_found` si el contacto no existe); si una variable usa un campo que no existe en
  la cuenta, `422 template_unresolved_placeholder`; si la plantilla es de otra cuenta de WhatsApp Business que la que
  hoy usa el número, `422 template_waba_mismatch`: tráelas de Meta (abajo) y elige una de esa cuenta.
- **Si la plantilla no está en la lista:** las que la persona crea o cambia directamente en Meta llegan solas una vez
  por día. Si la acaba de crear y no aparece en `GET /api/v1/templates`, **tráela de Meta y vuelve a listar**; no
  concluyas que no existe. `POST /api/v1/devices/{device}/templates`, sin cuerpo, con el `id` del número oficial en
  `{device}`, trae las que se crearon o cambiaron en Meta (y quita las de una cuenta de WhatsApp Business que el número
  ya no usa). Pide **Contactos y conversaciones → Editar**, no la casilla de enviar. Responde `202` con `status`:
  `completed` (ya terminó: lista otra vez) o `in_progress` (la primera página, hasta 100 plantillas, ya está; las demás
  siguen en segundo plano: vuelve a listar en unos segundos).
  - Solo con números oficiales: por un número conectado por QR (o sin cuenta de WhatsApp Business o credenciales en
    Meta) responde `422 number_not_connected_to_meta`.
  - `409 template_sync_in_progress`: ya hay una de ese número en curso. No lances otra: espera unos segundos y lista.
  - `422 meta_rejected`: Meta rechazó la lectura (por ejemplo, el token del número venció); su código viene en
    `meta_code` y no se trajo nada. `502 meta_unavailable`: Meta no respondió.
  - `404`: el número no existe o es de otra cuenta o de otro workspace: responde igual.

Un número conectado por QR no tiene esta ventana: a un teléfono nuevo le mandas el texto directamente.

### Errores al mandar

El cuerpo de un rechazo trae `error` (el código) y `message`; cuando una regla frena el envío, no se manda ni se
registra nada.

- `422 window_closed`: ver «Fuera de las 24 horas».
- `422 antiblock_duplicate_content`: el mismo contenido ya se mandó 2 veces a ese contacto en las últimas 24 horas.
  `422 antiblock_unanswered_limit`: ya van 5 mensajes seguidos sin que el contacto responda. Los contadores se reinician
  cuando el contacto responde.
- `422 recipient_mismatch`: el `phone` o el `whatsapp_id` no son del contacto de `contact_id`. Manda uno solo.
- `422 recipient_unsupported`: el contacto es un grupo, una lista de difusión o un canal; por esta llamada solo se le
  escribe a personas. A un grupo se le escribe con `POST /api/v1/groups/{group}/messages` (ver «Grupos»).
- `422 validation_failed` con `errors`: un dato no es válido, por ejemplo el teléfono; `errors` dice cuál.
- `429 rate_limited` con `Retry-After`: superaste el ritmo del número (WhatsApp Cloud: 60 mensajes por segundo y 10 por
  minuto al mismo contacto; coexistencia: 15 por segundo; QR: sin límite). Espera esos segundos y reintenta.
- `404 not_found` al mandar por `phone` o `whatsapp_id`: solo cuando los workspaces de tu cuenta comparten los contactos
  y ese teléfono ya es un contacto de **otro workspace**. Responde igual que un contacto que no existe, sin datos de
  ese contacto. No reintentes; desde esta clave no se le puede escribir: hace falta una clave creada en ese otro
  workspace. Si cada workspace tiene sus propios contactos, no ocurre: el contacto se busca y se crea en el workspace
  de tu clave.
- `404 not_found` al mandar por `contact_id`: ese contacto no existe. Manda por `phone`.
- `415 bad_request`: el tipo de archivo no se puede mandar; `supported_file_types` trae los que sí.
- `429 mac_lockout_24h` o `mac_limit_reached`: la cuenta (o, si usa workspaces separados, el workspace del número) llegó a su límite de contactos activos. No sale, no se guarda
  nada (tampoco tu `client_reference`) y reintentar no sirve: díselo a la persona (ver «Límites y errores»).
- Un `5xx` (por ejemplo `500 internal_error`, o `500 gate_misconfigured`) o una llamada sin respuesta: el mensaje
  puede haber quedado registrado. No lo reenvíes enseguida: busca tu `client_reference` en los mensajes del contacto
  antes de reintentar; reintentar puede duplicarlo.

### Saber si lo leyeron, paso a paso

1. Crea un webhook: `POST /api/v1/webhooks` con
   `{"url": "https://tu-servidor.example/funnelchat", "events": ["message.status_changed"]}` (opcional:
   `description`). `url` es la dirección pública de tu receptor; usa `https`. `events` lleva de 1 a 50 nombres de
   evento y **no tiene comodín**: nombra cada evento que quieras, también `message.status_changed`. La clave necesita
   **Avisos (webhooks) → Administrar** (así aparece en el panel) y, porque es un evento de mensajes, también
   **Contactos y conversaciones → Ver**; si le falta, responde `422`.
2. La respuesta (`201`) trae el webhook con su `id` y su `secret` (empieza con `whsec_`). **El secreto aparece solo en
   esa respuesta**: guárdalo en el servidor que recibe los eventos (por ejemplo en una variable de entorno) y nunca en
   el código. Con él se verifica cada entrega.
3. Pruébalo: `POST /api/v1/webhooks/{id}/test` manda una sola entrega `webhook.test`, firmada igual que una real, y
   responde si tu servidor contestó `2xx`.
4. Cada cambio de estado llega como `message.status_changed`. Relaciónalo con tu envío por `data.message_id` (el `id`
   que devolvió el envío) junto con `data.contact_id`, y por `data.client_reference` si la mandaste. `data.status` es
   `sent`, `delivered`, `read` o `failed`: **`read` es que lo leyeron**.
5. Sin esperar el webhook: `GET /api/v1/contacts/{contact}/messages/{message}`, con el `contact_id` y el `id` que
   devolvió el envío, devuelve el mensaje con su `status`.

- No crees un webhook por cada cosa: `GET /api/v1/webhooks` lista los del workspace de tu clave, también los de otras
  integraciones, así que guarda el `id` del tuyo. Para cambiar la dirección o los eventos, usa «Editar un webhook»
  (`PUT /api/v1/webhooks/{id}`): reemplaza la dirección y la lista de eventos, así que manda todo como tiene que quedar.

### Recibir mensajes, paso a paso

1. Crea un webhook con `message.received`: `POST /api/v1/webhooks` con `"events": ["message.received"]` (la clave
   necesita también **Contactos y conversaciones → Ver**). Si ya tienes un webhook y quieres sumar este evento, usa
   «Editar un webhook» (`PUT /api/v1/webhooks/{id}`) con la lista completa de eventos, este incluido. Guarda el
   `secret` de la respuesta del alta: aparece una sola vez.
2. Cada mensaje entrante llega como `message.received`, con `data.message` (`id`, `type`, `text`, `media`),
   `data.contact` (`id`, `name`, `phone`), `data.receiver.phone` (el teléfono de tu número que lo recibió) y
   `data.device_id` (el número de tu cuenta que lo recibió). `data.message.type` dice si es texto u otra cosa.
3. Para contestar: `POST /api/v1/message/send-message` con `contact_id` = `data.contact.id` y `device_id` =
   `data.device_id`. Como el contacto te acaba de escribir, la ventana de 24 horas de un número oficial está abierta.

### Llamadas

#### Mandar un mensaje

`POST /api/v1/message/send-message` · permiso **Contactos y conversaciones → Enviar** · área conversations · `operationId` `message.sendMessage`

**Para qué sirve:** Sirve para enviar un mensaje de texto o un archivo a un teléfono, aunque todavía no sea tu contacto (se crea solo), o a un contacto por su `contact_id`, indicando en el cuerpo el número desde el que sale.

Indica a quién envías con `phone`: el teléfono con código de país, por ejemplo `5491122334455`. No hace falta crear el contacto antes: el teléfono se busca y, si todavía no es un contacto, se crea en el workspace de tu clave, igual que con `POST /contacts/update-or-create` y con el mismo permiso, que **Enviar** ya incluye. Si en tu cuenta cada workspace tiene sus propios contactos, se busca solo en el workspace de tu clave; si tus workspaces comparten los contactos, en toda tu cuenta. La respuesta trae su id en `message.contact_id`, el mismo que llevan los eventos `message.status_changed`. Si el teléfono no es válido, la respuesta es la misma que daría `POST /contacts/update-or-create`: 422. Si tus workspaces comparten los contactos y el teléfono ya es un contacto de otro workspace de tu cuenta, también: 404, sin datos de ese contacto. Con un número oficial de WhatsApp (API Cloud) también puedes indicar `whatsapp_id`, el BSUID que envía Meta (por ejemplo `US.13491208655302741918`), en lugar de `phone`; usado así con un número conectado por QR, responde 422. En un número oficial, el primer mensaje a un contacto nuevo tiene que ser una plantilla: un mensaje libre solo sale dentro de las 24 horas desde que el contacto te escribió. Si ya tienes el `contact_id`, puedes seguir enviándolo: si junto con él mandas `phone` o `whatsapp_id`, tienen que ser de ese mismo contacto (si no, 422 `recipient_mismatch`). En `send-template`, `phone` o `whatsapp_id` va siempre, con o sin `contact_id`.

Si el límite de contactos activos (MAC) frena el envío, responde `429` con `error` = `mac_lockout_24h` o `mac_limit_reached` y sin `Retry-After`: reintentar no sirve hasta que sumes capacidad o empiece un ciclo nuevo. El envío no sale y no se guarda ningún mensaje ni tu `client_reference`: no queda nada en el historial del contacto. Detalle en «Errores y límites».

**Cuerpo** (`application/json`, obligatorio)

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `device_id` | string | sí | Id opaco: un texto que empieza con `dev_`. Se usa tal como llega; no se arma ni se interpreta. |
| `text` | string | no |  |
| `contact_id` | string \| null | no | Id opaco: un texto que empieza con `ctc_`. Se usa tal como llega; no se arma ni se interpreta. |
| `phone` | string \| null | no |  |
| `whatsapp_id` | string \| null | no |  |
| `file` | string | no | Archivo del mensaje: el nombre de un archivo ya subido a tu cuenta o la URL pública de un archivo (te recomendamos `https://`), que WhatsApp o el proveedor descarga; admite hasta 4096 caracteres. Si empieza con `http`, en mayúsculas o minúsculas, tiene que ser una URL `http://` o `https://`; si no, la respuesta es 422. Consulta la sección «Enviar un archivo por URL». |
| `file_type` | string \| null ∈ {"image", "video", "audio", "document", "sticker", null} | no | Tipo del archivo. Es obligatorio cuando `file` es una URL que no termina en una extensión reconocida; si lo envías, manda sobre la extensión. Valores: `image`, `video`, `audio`, `document`, `sticker`. Consulta la sección «Enviar un archivo por URL». |
| `file_name` | string \| null | no | Nombre con el que el contacto ve un documento, con su extensión (por ejemplo `factura.pdf`), de hasta 255 caracteres. Es obligatorio al enviar un documento por URL que no termina en una extensión de la lista. Consulta la sección «Enviar un archivo por URL». |
| `temporal_uuid` | string | no |  |
| `local_id` | string \| null | no |  |
| `note` | boolean | no |  |
| `mentions` | array<integer> \| null | no |  |
| `client_reference` | string \| null | no |  |

**Respuestas**

- `200` — OK

  | Campo | Tipo | Descripción |
  |---|---|---|
  | `message` | PublicMessageResource \| null |  |
  | `message.id` | string | Id opaco: un texto que empieza con `msg_`. Se usa tal como llega; no se arma ni se interpreta. |
  | `message.contact_id` | string \| null | Id opaco: un texto que empieza con `ctc_`. Se usa tal como llega; no se arma ni se interpreta. |
  | `message.device_id` | string \| null | Id opaco: un texto que empieza con `dev_`. Se usa tal como llega; no se arma ni se interpreta. |
  | `message.direction` | string ∈ {"outbound", "inbound"} |  |
  | `message.type` | string ∈ {"text", "image", "video", "document", "sticker", "contact", "audio", "note", "action", "invalid", "interactive", "location", "voice_call", "video_call", "event", "button", "template", "notification", "option_list", "template_button_reply", "poll", "whatsapp_form", "call_permission_request", "call_permission_reply", "request_contact_info"} |  |
  | `message.status` | string \| null ∈ {"sent", "delivered", "read", "failed", "queued", null} |  |
  | `message.error` | object \| null |  |
  | `message.client_reference` | string \| null |  |
  | `message.created_at` | string \| null |  |
  | `message.updated_at` | string \| null |  |

- `401` — Unauthorized (`ConversationsAuthenticationException`)
- `402` — Payment Required
- `403` — Forbidden (`ConversationsAuthorizationException`)
- `404` — Not Found
- `415` — Unsupported Media Type
- `422` — Unprocessable Content
- `429` — Too Many Requests. Cabeceras: `Retry-After`
- `500` — Internal Server Error

#### Mandar una plantilla

`POST /api/v1/devices/{device}/templates/{template}/send-template` · permiso **Contactos y conversaciones → Enviar** · área conversations · `operationId` `messageTemplate.send`

**Para qué sirve:** Sirve para enviar una plantilla desde uno de tus números a un teléfono o contacto, completando sus variables, por ejemplo un recordatorio, una confirmación o una novedad. Si una plantilla que creaste directamente en Meta todavía no aparece en tu lista, tráela con «Traer tus plantillas de Meta» (`POST /api/v1/devices/{device}/templates`).

Indica a quién envías con `phone`: el teléfono con código de país, por ejemplo `5491122334455`. No hace falta crear el contacto antes: el teléfono se busca y, si todavía no es un contacto, se crea en el workspace de tu clave, igual que con `POST /contacts/update-or-create` y con el mismo permiso, que **Enviar** ya incluye. Si en tu cuenta cada workspace tiene sus propios contactos, se busca solo en el workspace de tu clave; si tus workspaces comparten los contactos, en toda tu cuenta. La respuesta trae su id en `message.contact_id`, el mismo que llevan los eventos `message.status_changed`. Si el teléfono no es válido, la respuesta es la misma que daría `POST /contacts/update-or-create`: 422. Si tus workspaces comparten los contactos y el teléfono ya es un contacto de otro workspace de tu cuenta, también: 404, sin datos de ese contacto. Con un número oficial de WhatsApp (API Cloud) también puedes indicar `whatsapp_id`, el BSUID que envía Meta (por ejemplo `US.13491208655302741918`), en lugar de `phone`; usado así con un número conectado por QR, responde 422. En un número oficial, el primer mensaje a un contacto nuevo tiene que ser una plantilla: un mensaje libre solo sale dentro de las 24 horas desde que el contacto te escribió. Si ya tienes el `contact_id`, puedes seguir enviándolo: si junto con él mandas `phone` o `whatsapp_id`, tienen que ser de ese mismo contacto (si no, 422 `recipient_mismatch`). En `send-template`, `phone` o `whatsapp_id` va siempre, con o sin `contact_id`.

**Parámetros**

| Nombre | En | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
| `device` | path | string | sí |  |
| `template` | path | string | sí |  |

**Cuerpo** (`application/json`)

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `contact_id` | string \| null | no | Id opaco: un texto que empieza con `ctc_`. Se usa tal como llega; no se arma ni se interpreta. |
| `phone` | string \| null | no |  |
| `whatsapp_id` | string \| null | no |  |
| `template_variables` | object | no |  |
| `template_variables.body` | array<string \| null> | no |  |
| `client_reference` | string \| null | no |  |

**Respuestas**

- `200` — OK

  | Campo | Tipo | Descripción |
  |---|---|---|
  | `message` | PublicMessageResource \| null |  |
  | `message.id` | string | Id opaco: un texto que empieza con `msg_`. Se usa tal como llega; no se arma ni se interpreta. |
  | `message.contact_id` | string \| null | Id opaco: un texto que empieza con `ctc_`. Se usa tal como llega; no se arma ni se interpreta. |
  | `message.device_id` | string \| null | Id opaco: un texto que empieza con `dev_`. Se usa tal como llega; no se arma ni se interpreta. |
  | `message.direction` | string ∈ {"outbound", "inbound"} |  |
  | `message.type` | string ∈ {"text", "image", "video", "document", "sticker", "contact", "audio", "note", "action", "invalid", "interactive", "location", "voice_call", "video_call", "event", "button", "template", "notification", "option_list", "template_button_reply", "poll", "whatsapp_form", "call_permission_request", "call_permission_reply", "request_contact_info"} |  |
  | `message.status` | string \| null ∈ {"sent", "delivered", "read", "failed", "queued", null} |  |
  | `message.error` | object \| null |  |
  | `message.client_reference` | string \| null |  |
  | `message.created_at` | string \| null |  |
  | `message.updated_at` | string \| null |  |

- `401` — Unauthorized (`ConversationsAuthenticationException`)
- `402` — Payment Required
- `403` — Forbidden (`ConversationsAuthorizationException`)
- `404` — Not Found
- `422` — Unprocessable Content
- `429` — Too Many Requests. Cabeceras: `Retry-After`
- `500` — Internal Server Error

#### Ver tus plantillas

`GET /api/v1/templates` · permiso **Contactos y conversaciones → Ver** · área conversations · `operationId` `messageTemplate.templates`

**Para qué sirve:** Úsalo para listar tus plantillas de WhatsApp con su estado de aprobación, categoría, idioma y número, y elegir cuál usar en un envío. Si una que creaste directamente en Meta no aparece, tráela con «Traer tus plantillas de Meta» (`POST /api/v1/devices/{device}/templates`) y vuelve a listar.

**Parámetros**

| Nombre | En | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
| `name` | query | string \| null | no |  |
| `uid` | query | string \| null | no |  |
| `language_code` | query | string \| null | no |  |
| `status` | query | string \| null ∈ {"PENDING", "APPROVED", "REJECTED", "PENDING_DELETION", "PAUSED", "DISABLED", "ARCHIVED", null} | no |  |
| `category` | query | string \| null | no |  |
| `deviceId` | query | string \| null | no |  |
| `type` | query | string \| null ∈ {"text", "image", "document", "video", "location", "default", null} | no |  |
| `created_by_webhook` | query | boolean | no |  |
| `quality[]` | query | array<string \| null ∈ {"GREEN", "YELLOW", "RED", "UNKNOWN", "NOT_APPLICABLE", null}> \| null ∈ {"GREEN", "YELLOW", "RED", "UNKNOWN", "NOT_APPLICABLE", null} | no |  |
| `include` | query | string \| null ∈ {"quality_counts", null} | no |  |
| `scope` | query | string \| null ∈ {"waba", null} | no |  |
| `perPage` | query | integer | no |  |
| `orderBy` | query | string ∈ {"name", "created_at", "updated_at"} | no |  |
| `orderByMethod` | query | string ∈ {"asc", "desc"} | no |  |

**Respuestas**

- `200` — OK

  | Campo | Tipo | Descripción |
  |---|---|---|
  | `data` | array<object> |  |
  | `links` | object |  |
  | `links.first` | string \| null |  |
  | `links.last` | string \| null |  |
  | `links.prev` | string \| null |  |
  | `links.next` | string \| null |  |
  | `meta` | object |  |
  | `meta.current_page` | integer |  |
  | `meta.from` | integer \| null |  |
  | `meta.last_page` | integer |  |
  | `meta.links` | array<object> |  |
  | `meta.path` | string |  |
  | `meta.per_page` | integer |  |
  | `meta.to` | integer \| null |  |
  | `meta.total` | integer |  |

- `401` — Unauthorized (`ConversationsAuthenticationException`)
- `402` — Payment Required
- `403` — Forbidden (`ConversationsAuthorizationException`)
- `422` — Unprocessable Content (`ConversationsValidationException`)

#### Traer tus plantillas de Meta

`POST /api/v1/devices/{device}/templates` · permiso **Contactos y conversaciones → Editar** · área conversations · `operationId` `messageTemplate.sync`

**Para qué sirve:** Úsalo si creaste o cambiaste una plantilla directamente en Meta y todavía no aparece en tu lista (llegan solas una vez por día): la trae en el momento. Solo con números oficiales de WhatsApp. Si responde `in_progress`, vuelve a listar en unos segundos.

Sincroniza con Meta las plantillas de un número de la API oficial de WhatsApp: trae las que se crearon o cambiaron directamente en Meta y quita las de una cuenta de WhatsApp Business que el número ya no usa. `{device}` es el `id` del número.

- **Asíncrona:** la primera página (hasta 100 plantillas) se lee en el momento y las siguientes en segundo plano. Responde 202 con `status`: `completed` si ya terminó, `in_progress` si sigue. Las plantillas sincronizadas se listan con `GET /templates`.
- **Una a la vez:** mientras hay una sincronización de ese número en curso, otra llamada responde 409 y no lanza una nueva.
- **Errores de Meta:** si Meta rechaza la lectura (por ejemplo, porque el token del número venció o la cuenta de WhatsApp Business no existe), responde 422 `meta_rejected` con el código de error de Meta en `meta_code` y no sincroniza nada.

| HTTP | `error` | Cuándo |
|---|---|---|
| 404 | — | El número no existe en tu cuenta o está fuera del workspace de tu clave. |
| 409 | `template_sync_in_progress` | Ya hay una sincronización de ese número en curso. |
| 422 | `number_not_connected_to_meta` | El número está conectado por QR o no tiene una cuenta de WhatsApp Business o credenciales en Meta. |
| 422 | `meta_rejected` | Meta rechazó la lectura de las plantillas (`meta_code` trae su código de error). |
| 429 | — | Demasiadas solicitudes por minuto (ver `Retry-After`). |
| 502 | `meta_unavailable` | Meta no respondió. |

**Parámetros**

| Nombre | En | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
| `device` | path | string | sí |  |

**Respuestas**

- `202` — Accepted

  | Campo | Tipo | Descripción |
  |---|---|---|
  | `status` | string ∈ {"in_progress", "completed"} |  |

- `401` — Unauthorized (`ConversationsAuthenticationException`)
- `402` — Payment Required
- `403` — Forbidden (`ConversationsAuthorizationException`)
- `404` — Not Found
- `409` — Conflict
- `422` — Unprocessable Content
- `502` — Bad Gateway

#### Ver un mensaje

`GET /api/v1/contacts/{contact}/messages/{message}` · permiso **Contactos y conversaciones → Ver** · área conversations · `operationId` `message.showMessage`

**Para qué sirve:** Úsalo para saber qué pasó con un mensaje que enviaste: con el id que te devolvió el envío ves su estado (en cola, enviado, entregado, leído o fallido) y, si falló, el motivo.

Devuelve un mensaje de tu cuenta por el id que te dio el envío o un webhook. Aceptado no es entregado: el estado final llega por `message.status_changed` o por este GET. `status` es `queued`, `sent`, `delivered`, `read` o `failed` en los mensajes que enviaste. `sent`, `delivered`, `read` y `failed` tienen el mismo significado que en `message.status_changed`; `queued` es un mensaje en cola que todavía no se envió (en cola no es enviado) y no se reintenta. `status` es `null` en los mensajes recibidos, las notas y las acciones. `status` también es `null` en un mensaje enviado cuyo resultado no se conoce (el proveedor no confirmó ni rechazó el envío o el envío se interrumpió): puede haber llegado y no cambia de estado; también cuando lleva más de una hora en cola sin resultado: un mensaje cuyo envío no empezó dentro de la hora ya no sale; pasada la hora sin resultado, `status` es `null`, o `failed` con `error.reason` `not_sent` y su evento si su envío llega tarde. Reintentar es un envío nuevo, que sólo puede duplicar si el envío había empezado y se cortó. `error` trae `code`, `title` y `reason` solo cuando `status` es `failed`. `error.reason` es `null` cuando el rechazo lo informó el proveedor; si Funnelchat decidió que un mensaje enviado con clave no salía, trae `device_unavailable`, `insufficient_balance`, `window_closed`, `recipient_unreachable`, `template_not_found`, `template_unresolved_placeholder`, `not_queued` o `not_sent`, `code` es `null` y `title` es un texto llano en el idioma de la cuenta. `client_reference` es la referencia que mandaste al enviar, o `null`. Responde 404 si el mensaje no existe o no es de ese contacto.

**Parámetros**

| Nombre | En | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
| `contact` | path | string | sí |  |
| `message` | path | string | sí |  |

**Respuestas**

- `200` — OK

  | Campo | Tipo | Descripción |
  |---|---|---|
  | `id` | string | Id opaco: un texto que empieza con `msg_`. Se usa tal como llega; no se arma ni se interpreta. |
  | `contact_id` | string \| null | Id opaco: un texto que empieza con `ctc_`. Se usa tal como llega; no se arma ni se interpreta. |
  | `device_id` | string \| null | Id opaco: un texto que empieza con `dev_`. Se usa tal como llega; no se arma ni se interpreta. |
  | `direction` | string ∈ {"outbound", "inbound"} |  |
  | `type` | string ∈ {"text", "image", "video", "document", "sticker", "contact", "audio", "note", "action", "invalid", "interactive", "location", "voice_call", "video_call", "event", "button", "template", "notification", "option_list", "template_button_reply", "poll", "whatsapp_form", "call_permission_request", "call_permission_reply", "request_contact_info"} |  |
  | `status` | string \| null ∈ {"sent", "delivered", "read", "failed", "queued", null} |  |
  | `error` | object \| null |  |
  | `error.code` | integer \| null |  |
  | `error.title` | string \| null |  |
  | `error.reason` | string \| null |  |
  | `client_reference` | string \| null |  |
  | `created_at` | string \| null |  |
  | `updated_at` | string \| null |  |

- `401` — Unauthorized (`ConversationsAuthenticationException`)
- `402` — Payment Required
- `403` — Forbidden (`ConversationsAuthorizationException`)
- `404` — Not Found (`ConversationsModelNotFoundException`)

### Los eventos

Llegan por webhook. Cómo crearlo, cómo llega cada entrega y cómo verificar la firma: «Webhooks» (en este archivo).

#### `message.received`

Un contacto le escribió a un número de WhatsApp de la cuenta.

`device_id` es el número de tu cuenta que recibió el mensaje: el mismo `device_id` que mandas para responder por ese número. Es `null` si el mensaje no tiene número asociado.

Ejemplo:

```json
{
  "id": "evt_000000000000000000000001",
  "type": "message.received",
  "version": 1,
  "occurred_at": "2026-10-01T12:00:00Z",
  "data": {
    "message": {
      "id": "msg_ADyPfpgQyD89BoEabkSQkV1",
      "type": "text",
      "text": "Hola, quiero más información",
      "media": null
    },
    "contact": {
      "id": "ctc_ABViuUDF93I2VL1tInstRDG",
      "name": "Contacto de ejemplo",
      "phone": "+5491100000000"
    },
    "receiver": {
      "phone": "+5491100000001"
    },
    "device_id": "dev_AFHtaOVjNBTEWzCuDrmxMPP",
    "workspace_id": 37
  }
}
```

#### `message.status_changed`

Cambió el estado de entrega de un mensaje enviado.

Se emite cuando cambia el estado de entrega de un mensaje que enviaste a un contacto, ya sea desde el chat, una automatización o un asistente de IA (incluye los enviados con clave). No se emite para mensajes de difusiones ni para mensajes recibidos. `message_id` es el id que devuelve la API, `contact_id` el del contacto y `device_id` el número de tu cuenta por el que salió el mensaje, el mismo `device_id` que usas para enviar (`null` si no tiene). `status` es `sent`, `delivered`, `read` o `failed`. `previous_status` es el estado que el mensaje tenía justo antes de este cambio y es `null` en tres casos: es el primer evento del mensaje, es el mismo estado que `status` (por ejemplo, el proveedor confirma el `sent` que ya registró el envío) o no se pudo leer. `error` solo viene cuando `status` es `failed`: `code` es el código numérico del proveedor y `title` su título, y cualquiera de los dos puede ser `null` si el proveedor no los informa. `error.reason` es `null` cuando el fallo lo informó el proveedor; cuando Funnelchat decidió que un mensaje enviado con clave no salía (por ejemplo, por saldo insuficiente o ventana de 24 horas cerrada) trae el motivo (`device_unavailable`, `insufficient_balance`, `window_closed`, `recipient_unreachable`, `template_not_found`, `template_unresolved_placeholder`, `not_queued` o `not_sent`), `code` es `null` y `title` es un texto llano en el idioma de la cuenta. `occurred_at` es el momento en que Funnelchat registró el estado, en UTC. `client_reference` es la referencia que mandaste al enviar el mensaje (por ejemplo `pedido-1001`) y `null` si el envío no la llevaba: sirve para relacionar cada evento con tu envío también cuando la llamada de envío no respondió. Cada estado se informa una sola vez por mensaje: si llegan varios eventos juntos se informa el más avanzado y un evento atrasado que no cambia el estado no genera evento. Un mensaje que no llegó a salir (por ejemplo, por ventana de 24 horas cerrada) no recibe eventos de estado, salvo uno enviado con clave: ese recibe un único evento `failed` con `previous_status` en `null`, su `error.reason` y su `client_reference`. Un mensaje enviado con clave cuyo resultado no se conoce (el proveedor no respondió o el envío se interrumpió) no recibe evento. Un mensaje cuyo envío no empezó dentro de la hora ya no sale: pasada la hora sin resultado, su estado es `null`, o `failed` con `error.reason` `not_sent` y su evento si su envío llega tarde. Reintentar es un envío nuevo, que sólo puede duplicar si el envío había empezado y se cortó. Un mensaje `queued` no es enviado: su resultado llega por este evento o por la consulta del mensaje. En cuentas con mucho tráfico, los eventos que excedan el límite de entrega por minuto de la cuenta se descartan.

Ejemplo:

```json
{
  "id": "evt_000000000000000000000014",
  "type": "message.status_changed",
  "version": 1,
  "occurred_at": "2026-10-01T12:00:00Z",
  "data": {
    "message_id": "msg_ADyPfpgQyD89BoEabkSQkV1",
    "contact_id": "ctc_ABViuUDF93I2VL1tInstRDG",
    "device_id": "dev_AFHtaOVjNBTEWzCuDrmxMPP",
    "status": "failed",
    "previous_status": "sent",
    "error": {
      "code": 131047,
      "title": "Re-engagement message",
      "reason": null
    },
    "occurred_at": "2026-10-01T12:00:00Z",
    "client_reference": "pedido-1001",
    "workspace_id": 37
  }
}
```

## Grupos

Ver los grupos de un número, escribirles sin importarlos antes, saber cómo salió el envío y seguirlos para enterarte de quién entra y quién sale.

### Grupos: empieza por los grupos del número

- **Los grupos de un número están en `GET /api/v1/devices/{device}/groups`**: los lee de WhatsApp, también los que
  todavía no están en el workspace de tu clave. `{device}` es el `id` del número en `GET /api/v1/devices`. La clave necesita
  **Grupos y campañas → Ver**.
- Viene por páginas: `page` y `pageSize` (25 por defecto, hasta 100); pide `page` 1, 2, … hasta `meta.last_page`. Cada
  grupo trae `uid` (su identificador en WhatsApp, por ejemplo `120363000000000001@g.us`) y `name`; si ya está en el
  workspace, trae además `device_id`. La lista se reutiliza durante un minuto por número: un grupo recién creado en
  WhatsApp puede tardar hasta un minuto en aparecer.
- **Para encontrar un grupo por su nombre**, compara el `name` de cada grupo de todas las páginas. La especificación
  declara también un parámetro `name`, pero no dice cómo filtra: no dependas de él. Si ningún grupo coincide, o
  coincide más de uno, muéstrale a la persona los nombres parecidos y pregúntale cuál es; no elijas por ella.
- **El número que manda** es aquel en cuya lista aparece el grupo. Si la persona tiene un solo número conectado, es
  ese. Con varios, busca en la lista de cada número conectado.

### Mandar un mensaje a un grupo, paso a paso

1. Toma el `uid` del grupo y el `id` del número de la lista de arriba.
2. `POST /api/v1/groups/{group}/messages`, con `{group}` el `uid` del grupo, y
   `{"device_id": "dev_Ac7Ku7iIZDXJTjdCu0UB1mX", "type": "text", "text": "¡Hola a todos!"}`. `type` es `text`, `image`, `video`, `audio` o
   `document`; para un archivo, `media_url` (hasta 255 caracteres) y, si quieres, `caption` y `file_name`.
   **No lo sigas antes:** si el grupo todavía no está en el workspace y el número es por QR, este envío lo importa (lo
   empieza a seguir) y sigue con el envío. La clave necesita **Grupos y campañas → Enviar** y, si el grupo todavía no
   estaba en el workspace, además **Grupos y campañas → Administrar grupos**. Esa importación cuenta en el tope de 5 por
   minuto del número.
3. **No sale dentro de la llamada.** La respuesta es `202` con `action_id` y `"status": "queued"`: el pedido quedó
   en cola y el mensaje sale después, al ritmo del número. Para saber cómo salió, consulta
   `GET /api/v1/groups/actions/{action}` con ese `action_id`, o espera el webhook `group_action.completed` (salió) o
   `group_action.failed` (falló). **`queued` no es enviado**, y no reenvíes el pedido: lo mandarías dos veces.
4. La consulta responde `data` con `status` (`queued`, `running`, `completed` o `failed`), `result` y `reason`.
   Con `completed`, `result.message.uid` es el id del mensaje en WhatsApp; mientras está `queued` o `running`,
   `result` y `reason` son `null`; con `failed`, `result` es `null` y `reason` dice por qué (un código, por ejemplo
   `device_not_connected` o `window_closed`; lo que no tiene un motivo propio sale `internal_error`).

### Seguir un grupo: enterarte de quién entra y quién sale

- Para qué: que el grupo quede en el workspace y que desde entonces lleguen los eventos de quién entra y quién sale. Para
  escribirle no hace falta: el envío lo sigue solo.
- `POST /api/v1/groups/{group}/import`, con `{group}` el `uid` del grupo y `{"device_id": "dev_Ac7Ku7iIZDXJTjdCu0UB1mX"}`. La clave necesita
  **Grupos y campañas → Administrar grupos**.
- Responde `201` si lo importó y `200` si ya estaba en el workspace, los dos con `data`: `uid`, `name`, `imported`
  (`true` si lo importó esta llamada) e `is_admin` (si el número es administrador del grupo, según WhatsApp, leído en la
  misma llamada). Con `is_admin: false` el grupo queda en el workspace, pero ese número no puede escribirle.
- Solo con números conectados por QR, hasta 5 grupos por minuto por número. Dos pedidos a la vez por el mismo grupo lo
  importan una sola vez. Si cada workspace de la cuenta tiene sus propios grupos, se importa la copia de este workspace sin tocar la del otro; si no, el grupo es uno solo para toda la cuenta y responde `404 group_not_found`.

### Quién entra y quién sale: el webhook

- Llegan por los eventos `group_participant.joined` y `group_participant.left`, de los grupos que están en el workspace:
  un grupo los genera desde que se sigue (con «Seguir un grupo», con el primer envío o desde el panel).
- Crea un webhook con `POST /api/v1/webhooks` y `"events": ["group_participant.joined", "group_participant.left"]`;
  la clave necesita además **Grupos y campañas → Ver**. Cada evento trae `data.group` (`uid`, `name`),
  `data.participant` (`identity`, `identity_type`, `name`) y `data.campaign` (`null` si el grupo no es de una campaña).
- Llega como mucho uno por persona, grupo y día UTC: si la misma persona vuelve a entrar al mismo grupo ese día, o
  vuelve a salir, no llega otro. No los uses para contar entradas y salidas.

### Errores al seguir un grupo y al mandarle

El cuerpo de un rechazo trae `error` (el código) y `message`.

- `403 import_permission_required`: el grupo no estaba en el workspace y a la clave le falta **Grupos y campañas →
  Administrar grupos** para seguirlo. La persona tiene que crear una clave con esa casilla marcada.
- `422 device_not_group_admin`: el número no es administrador del grupo; no se siguió nada. Reintentar no sirve.
- `422 provider_unsupported`: el número no permite eso; trae `provider` y, si a la cuenta le falta una habilitación,
  `requires` con lo que hace falta. Seguir un grupo con un número oficial responde esto: los grupos se siguen solo con números por
  QR. Mandarle un mensaje con un número oficial también, cuando el chat de grupos de la API oficial no está disponible
  para ese grupo, sea cual sea el tipo de mensaje.
- `404 group_not_found`: el grupo no es de ese número o no existe en el workspace de tu clave. `404 device_not_found`: el número no
  existe en el workspace de tu clave.
- `422 device_not_connected`: el número no está conectado. `422 device_not_group_number`: el número no es el del grupo.
- Con un número oficial de WhatsApp se verifican, antes de aceptar, la ventana de 24 horas (`422 window_closed`) y la
  calidad del número (`422 number_restricted`).
- `429 import_rate_limited`: el número ya siguió 5 grupos en el último minuto; trae `retry_after` en segundos: espera
  ese tiempo y reintenta. `429 too_many_pending_actions`: el número ya tiene 50 pedidos en cola sin terminar; espera a
  que salgan.
- `409 import_in_progress`: otro pedido está siguiendo ese mismo grupo en este momento. Reintenta en unos segundos: si
  ya quedó en la cuenta, responde `200`.
- Un `5xx` (por ejemplo `502 provider_error`) o una llamada sin respuesta: no hay clave de idempotencia, así que
  reintentar un envío puede mandar el mensaje dos veces.

### Llamadas: Grupos

#### Ver tus grupos

`GET /api/v1/devices/{device}/groups` · permiso **Grupos y campañas → Ver** · área communities · `operationId` `group.groups`

**Para qué sirve:** Sirve para ver los grupos de un número tal como están en WhatsApp, también los que todavía no importaste a tu cuenta: de acá sale el `uid` para escribirle a un grupo o seguirlo.

**Nota:** La lista se lee de WhatsApp y, para una API key, se reutiliza durante un minuto por número: un grupo recién creado en WhatsApp puede tardar hasta un minuto en aparecer. Si un grupo ya está en el workspace de la llamada, trae `device_id`. Para importar uno: `POST /groups/{group}/import`.

**Con API key:** la respuesta siempre viene paginada. Tamaño de página: `pageSize` (por defecto 25, máximo 100; un valor mayor, menor que 1 o no entero responde `422`).

**Parámetros**

| Nombre | En | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
| `device` | path | string | sí |  |
| `page` | query | integer | no |  |
| `pageSize` | query | integer | no |  |
| `name` | query | string \| null | no |  |

**Respuestas**

- `200` — Array of `GroupMinResource`

  | Campo | Tipo | Descripción |
  |---|---|---|
  | `data` | array<GroupMinResource> |  |
  | `data[].uid` | string \| string ∈ {""} |  |
  | `data[].name` | string \| string ∈ {""} |  |
  | `data[].description` | string \| string ∈ {""} |  |
  | `data[].device_id` | string | Id opaco: un texto que empieza con `dev_`. Se usa tal como llega; no se arma ni se interpreta. |
  | `data[].alias` | string \| string ∈ {""} |  |
  | `data[].number` | string \| string ∈ {""} |  |
  | `data[].communityUid` | string \| string ∈ {""} |  |
  | `meta` | object |  |
  | `meta.current_page` |  |  |
  | `meta.last_page` |  |  |
  | `meta.per_page` |  |  |
  | `meta.total` | integer |  |

- `400`
- `401` — Unauthenticated (`CommunitiesAuthenticationException`)
- `403` — Authorization error (`CommunitiesAuthorizationException`)
- `404`
- `422` — Validation error (`CommunitiesValidationException`)

#### Mandar un mensaje a un grupo

`POST /api/v1/groups/{group}/messages` · permiso **Grupos y campañas → Enviar** · área communities · `operationId` `apiGroupAction.sendMessage`

**Para qué sirve:** Úsalo para mandarle a un grupo un texto, o una imagen, un video, un audio o un documento, desde uno de tus números. El pedido se acepta enseguida, queda en cola y el mensaje sale después, al ritmo del número.

**Nota:** Asíncrona: responde 202 con `action_id`; consulta el resultado en `GET /groups/actions/{action}` (`result.message.uid` es el id del mensaje en WhatsApp). `type`: `text`, `image`, `video`, `audio` o `document`. Con un número QR sale al ritmo de los mensajes programados de velocidad Low, que el integrador no puede cambiar. Con un número oficial se verifican, antes de aceptar, la ventana de servicio de 24 horas y la calidad del número. No tiene tope de volumen del plan. Si el grupo todavía no está en la cuenta y el número es QR, primero se importa como en `POST /groups/{group}/import` (pide además **Grupos y campañas → Administrar grupos**, `403 import_permission_required` sin él) y el envío sigue con las mismas reglas: si el número no es administrador del grupo no se importa nada y responde `422 device_not_group_admin`. Esa importación cuenta en el tope de 5 por minuto del número.

**Parámetros**

| Nombre | En | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
| `group` | path | string | sí |  |

**Cuerpo** (`application/json`, obligatorio)

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `device_id` | string | sí | Id opaco: un texto que empieza con `dev_`. Se usa tal como llega; no se arma ni se interpreta. |
| `type` | string ∈ {"text", "image", "video", "audio", "document"} | sí |  |
| `text` | string | no |  |
| `media_url` | string | no |  |
| `caption` | string | no |  |
| `file_name` | string | no |  |

**Respuestas**

- `202` — `ApiGroupActionAcceptedResource`

  | Campo | Tipo | Descripción |
  |---|---|---|
  | `action_id` | string |  |
  | `status` | "queued" |  |

- `401` — Unauthenticated (`CommunitiesAuthenticationException`)
- `403` — Authorization error (`CommunitiesAuthorizationException`)
- `422` — Validation error (`CommunitiesValidationException`)

#### Seguir un grupo

`POST /api/v1/groups/{group}/import` · permiso **Grupos y campañas → Administrar grupos** · área communities · `operationId` `v2.apiGroupImport`

**Para qué sirve:** Úsalo para seguir un grupo de tu número sin escribirle: lo importa a tu cuenta y desde entonces te enteras de quién entra y quién sale. Si ya estaba en tu cuenta, no lo importa de nuevo.

**Nota:** Importa al workspace de la API key un grupo del número indicado en `device_id`, igual que importarlo desde el panel: queda visible en el panel, se sincronizan sus participantes y desde entonces genera los eventos `group_participant.joined` y `group_participant.left`. Los datos del grupo y si el número es administrador se leen de WhatsApp en la misma llamada. Responde `201` si lo importó y `200` si ya estaba en el workspace, con `is_admin`. Solo números QR: con un número oficial responde `422 provider_unsupported`. Si el grupo no es del número responde `404 group_not_found`. Cada número importa hasta 5 grupos por minuto (`429 import_rate_limited`, con `retry_after` en segundos). Dos pedidos a la vez por el mismo grupo en el mismo workspace lo importan una sola vez. Si el grupo ya está en otro workspace de la cuenta: cuando cada workspace de la cuenta tiene sus propios grupos, se importa la copia de este workspace sin tocar la del otro; si no, el grupo es uno solo para toda la cuenta y responde `404 group_not_found`.

**Parámetros**

| Nombre | En | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
| `group` | path | string | sí | Identificador del grupo en WhatsApp, como lo lista `GET /v1/devices/{device}/groups`. |

**Cuerpo** (`application/json`, obligatorio)

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `device_id` | string | sí | Id opaco: un texto que empieza con `dev_`. Se usa tal como llega; no se arma ni se interpreta. |

**Respuestas**

- `200` — El grupo ya estaba en el workspace: no se importó de nuevo.

  | Campo | Tipo | Descripción |
  |---|---|---|
  | `data` | ApiGroupImportResource |  |
  | `data.uid` | string | Identificador del grupo en WhatsApp. |
  | `data.name` | string \| null | Nombre del grupo. |
  | `data.imported` | boolean | `true` si esta llamada lo importó; `false` si ya estaba en el workspace. |
  | `data.is_admin` | boolean | Si el número indicado es administrador del grupo, según WhatsApp. Sin serlo no puede enviarle mensajes ni hacer acciones de grupo. |

- `201` — El grupo se importó en esta llamada.

  | Campo | Tipo | Descripción |
  |---|---|---|
  | `data` | ApiGroupImportResource |  |
  | `data.uid` | string | Identificador del grupo en WhatsApp. |
  | `data.name` | string \| null | Nombre del grupo. |
  | `data.imported` | boolean | `true` si esta llamada lo importó; `false` si ya estaba en el workspace. |
  | `data.is_admin` | boolean | Si el número indicado es administrador del grupo, según WhatsApp. Sin serlo no puede enviarle mensajes ni hacer acciones de grupo. |

- `401` — Unauthenticated (`CommunitiesAuthenticationException`)
- `403` — Authorization error (`CommunitiesAuthorizationException`)
- `422` — Validation error (`CommunitiesValidationException`)

### Llamadas: Acciones de grupo

#### Ver cómo salió una acción de grupo

`GET /api/v1/groups/actions/{action}` · permiso **Grupos y campañas → Ver** · área communities · `operationId` `apiGroupAction.show`

**Para qué sirve:** Sirve para saber cómo terminó lo que le pediste a un grupo, como mandarle un mensaje: si sigue en cola, se está haciendo, terminó o falló, y su resultado.

**Parámetros**

| Nombre | En | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
| `action` | path | string | sí |  |

**Respuestas**

- `200` — El estado de la acción y, si terminó `completed`, su resultado.

  | Campo | Tipo | Descripción |
  |---|---|---|
  | `data` | ApiGroupActionResource |  |
  | `data.action_id` | string | Id de la acción: el `action_id` del `202`. |
  | `data.type` | string ∈ {"create_group", "add_participants", "remove_participants", "promote_admins", "demote_admins", "update_name", "update_description", "update_photo", "update_settings", "renew_invite_link", "send_message", "approve_join_requests", "reject_join_requests"} | Tipo de acción. |
  | `data.status` | string ∈ {"queued", "running", "completed", "failed"} | Estado de la acción. |
  | `data.device_id` | string \| null | Número que ejecuta la acción; `null` si es de otro workspace que el de la key. Id opaco: un texto que empieza con `dev_`. Se usa tal como llega; no se arma ni se interpreta. |
  | `data.group` | object \| null | Grupo de la acción; `null` si todavía no existe (una creación sin terminar) o es de otro workspace que el de la key. |
  | `data.result` | object \| null | Resultado de una acción `completed`; `null` mientras está `queued` o `running` y cuando termina `failed`. Su forma depende de `type`: `{"participants": [...]}` (una lista, en el orden del pedido) para las acciones con lista de teléfonos; `{"group": {"uid", "name"}, "invite_link"}` para `create_group`; `{"invite_link"}` para `renew_invite_link`; `{"message": {"uid"}}` para `send_message`; `{}` para las demás. Es el mismo `result` del evento `group_action.completed`. |
  | `data.reason` | string \| null | Motivo de una acción `failed`; `null` en los demás estados. Vocabulario cerrado: la sección «Motivos» de «Acciones de grupo». |
  | `data.created_at` | string \| null |  |
  | `data.started_at` | string \| null |  |
  | `data.completed_at` | string \| null |  |
  | `data.failed_at` | string \| null |  |

- `401` — Unauthenticated (`CommunitiesAuthenticationException`)
- `403` — Authorization error (`CommunitiesAuthorizationException`)

### Los eventos

Llegan por webhook. Cómo crearlo, cómo llega cada entrega y cómo verificar la firma: «Webhooks» (en este archivo).

#### `group_participant.joined`

Una persona entró a un grupo del workspace; `campaign` es null si el grupo no es de una campaña, y sale como mucho uno por persona, grupo y día UTC en cada workspace (si la misma persona vuelve a entrar ese día, no sale otro).

Ejemplo:

```json
{
  "id": "evt_00000000000000000000000000000002",
  "type": "group_participant.joined",
  "version": 1,
  "occurred_at": "2026-10-01T12:00:00Z",
  "data": {
    "group": {
      "uid": "120363000000000001@g.us",
      "name": "Grupo de ejemplo"
    },
    "campaign": {
      "uuid": "xK9mQz"
    },
    "participant": {
      "identity": "5491100000000",
      "identity_type": "phone",
      "name": "Ana Pérez"
    },
    "workspace_id": 37
  }
}
```

#### `group_participant.left`

Una persona salió de un grupo del workspace; `campaign` es null si el grupo no es de una campaña, y sale como mucho uno por persona, grupo y día UTC en cada workspace (si la misma persona vuelve a salir ese día, no sale otro).

Ejemplo:

```json
{
  "id": "evt_00000000000000000000000000000003",
  "type": "group_participant.left",
  "version": 1,
  "occurred_at": "2026-10-01T12:00:00Z",
  "data": {
    "group": {
      "uid": "120363000000000001@g.us",
      "name": "Grupo de ejemplo"
    },
    "campaign": {
      "uuid": "xK9mQz"
    },
    "participant": {
      "identity": "5491100000000",
      "identity_type": "phone",
      "name": "Ana Pérez"
    },
    "workspace_id": 37
  }
}
```

#### `group_action.completed`

Terminó una acción sobre un grupo. `action.uuid` es el mismo `action_id` que devolvió la API al pedirla, y `action.type` dice qué acción fue. `result` depende del tipo de acción: en las que reciben una lista de teléfonos (agregar o quitar participantes, nombrar o quitar administradores) trae `participants`, con el resultado por persona: `identity`, `identity_type`, `status` (`added`, `removed`, `promoted` o `demoted` según la acción, o `failed`) y `reason`, que es `null` salvo cuando `status` es `failed`; al crear un grupo o renovar su link de invitación trae `invite_link`; al enviar un mensaje trae `message.uid`; en las demás (cambiar el nombre, la descripción, la foto o los ajustes) viene como objeto vacío (`{}`). `group` y `campaign` pueden venir `null`.

Ejemplo:

```json
{
  "id": "evt_0f8e4b526c1d4c7a9a3e2b5d",
  "type": "group_action.completed",
  "version": 1,
  "occurred_at": "2026-10-01T12:00:00Z",
  "data": {
    "action": {
      "uuid": "00000000-0000-4000-8000-000000000001",
      "type": "add_participants"
    },
    "group": {
      "uid": "120363000000000000@g.us",
      "name": "Grupo de ejemplo"
    },
    "campaign": {
      "uuid": "xK9mQz",
      "name": "Campaña de ejemplo"
    },
    "result": {
      "participants": [
        {
          "identity": "5491100000000",
          "identity_type": "phone",
          "status": "added",
          "reason": null
        }
      ]
    },
    "workspace_id": 37
  }
}
```

#### `group_action.failed`

Una acción sobre un grupo falló entera (si terminó con resultados por persona, llega `group_action.completed`). Si la pidió la API, `action.uuid` es el mismo `action_id` que devolvió al pedirla y `pipeline` viene `null`. Si la ejecutó una campaña o un pipeline, `action.uuid` viene `null`, y `pipeline` trae ese pipeline (`uuid` y `name`) o viene `null` fuera de un pipeline. `reason` es el motivo de la falla. `group` y `campaign` pueden venir `null`.

Ejemplo:

```json
{
  "id": "evt_0f8e4b526c1d4c7a9a3e2b5d",
  "type": "group_action.failed",
  "version": 1,
  "occurred_at": "2026-10-01T12:00:00Z",
  "data": {
    "campaign": {
      "uuid": "xK9mQz",
      "name": "Campaña de ejemplo"
    },
    "pipeline": null,
    "group": {
      "uid": "120363000000000000@g.us",
      "name": "Grupo de ejemplo"
    },
    "action": {
      "uuid": "00000000-0000-4000-8000-000000000001",
      "type": "add_participants"
    },
    "reason": "motivo_de_ejemplo",
    "workspace_id": 37
  }
}
```

## Webhooks

Crearlos, verlos, probarlos y borrarlos, cómo llega cada entrega, todos los eventos (con el tema que detalla cada uno) y cómo verificar la firma.

Esta página es el detalle de los webhooks: cómo funcionan, cuatro de sus llamadas (crear, ver todos, probar y borrar; ver uno, editarlo, sus entregas y los tipos de evento están en «Más sobre tus webhooks», en Más funciones), qué trae cada evento y cómo verificar la firma.

### Cómo funcionan los webhooks

- Un webhook es una dirección pública de tu servidor (con `https`) a la que Funnelchat le manda los eventos que elegiste.
  Se crea con `POST /api/v1/webhooks`: `url` y `events` (de 1 a 50 nombres de evento, sin comodín: nombra cada uno).
  La clave necesita **Avisos (webhooks) → Administrar** (así se llama la casilla en el panel) y, por cada evento, el
  permiso de lectura de su área: **Números de WhatsApp → Ver** para `device.connected` y `device.disconnected`;
  **Contactos y conversaciones → Ver** para los de mensajes, contactos, conversaciones, formularios y automatizaciones
  (`message.received`, `message.status_changed`, `message.reaction_failed`, `contact.created`, `contact.updated`,
  `contact.tag_added`, `contact.tag_removed`, `conversation.assigned`, `conversation.closed`,
  `whatsapp_form.completed`, `flow.completed` y `flow.failed`), y **Grupos y campañas → Ver** para `group_participant.joined` y `group_participant.left`. Si falta
  alguno, `422`.
- La respuesta del alta (`201`) trae el `id` del webhook y su `secret` (empieza con `whsec_`). El secreto aparece solo
  ahí: guárdalo en el servidor que recibe los eventos, por ejemplo en una variable de entorno.
- **El alta no acepta `Idempotency-Key`:** si la llamada no respondió y la repites, puede quedar otro webhook, con otro
  secreto. Antes de repetirla, mira `GET /api/v1/webhooks`. Hay un tope de 50 webhooks por workspace (por cuenta, si no
  usa workspaces), sea cual sea su estado: con 50, el alta responde `422 webhooks_limit_reached`; borra los que ya no
  se usan, con confirmación de la persona.
- **Un webhook con todos los eventos que necesitas.** Al crearlo, nombra todos. Para sumar o quitar eventos más adelante,
  usa «Editar un webhook» (`PUT /api/v1/webhooks/{id}`) con la lista completa: el secreto no cambia.
  `GET /api/v1/webhooks` lista los webhooks del workspace de la clave, también los de otras integraciones: guarda el `id` del tuyo.
- Cada entrega es un `POST` a tu `url` con el cuerpo JSON `{id, type, version, occurred_at, data}` y las cabeceras
  `X-Funnelchat-Signature` (la firma), `X-Funnelchat-Event` (el tipo de evento) y `X-Funnelchat-Delivery` (cambia en
  cada intento).
- Todos los eventos traen `data.workspace_id`: el id del workspace del número (un entero). Un webhook recibe solo los
  eventos de su workspace: las suscripciones son del workspace de la clave.
- Los eventos de contactos activos (`mac.*`), de bloqueo (`account.blocked`), de cobros (`billing.*`) y de la suscripción
  (`subscription.*`) llegan al workspace al que corresponden: el que tiene facturación propia o, si el pool es el de la
  cuenta, el workspace por defecto (cada descripción lo dice).
- Verifica la firma sobre el cuerpo crudo, antes de parsear el JSON (ver «Verificar la firma»). Rechaza la entrega si no
  coincide o si `t` está a más de 300 segundos de la hora actual.
- Responde `2xx` enseguida y procesa después. Ante un error de red, un `5xx` o un `429` se reintenta: hasta 4 intentos
  en total, esperando 60 segundos, 5 minutos y 30 minutos entre ellos. Otra respuesta (`3xx`, o un `4xx` que no sea
  `429`) no se reintenta. Después de 5 entregas fallidas seguidas el webhook se deshabilita (`status: disabled`): crea
  uno nuevo, guarda su secreto y borra el deshabilitado.
- El `id` del sobre es el mismo en todos los reintentos: úsalo para descartar los repetidos.
- Para probar sin esperar un evento real: `POST /api/v1/webhooks/{id}/test` manda una sola entrega `webhook.test`,
  firmada igual que una real, y responde si tu servidor contestó `2xx`. A `webhook.test` no se suscribe nadie: solo
  llega al probar.

### Llamadas

#### Crear un webhook

`POST /api/v1/webhooks` · permiso **Avisos (webhooks) → Administrar** · área accounts · `operationId` `webhookSubscription.store`

**Para qué sirve:** Sirve para empezar a recibir eventos en tu sistema: eliges la URL y los eventos de cualquiera de las tres áreas, y guardas el secreto de firma, que se muestra solo esta vez.

Con una clave de API, cada tipo de `events` exige además el permiso
**Números de WhatsApp → Ver**, **Contactos y conversaciones → Ver** o
**Grupos y campañas → Ver**, según su área; si falta, 422.

Hay un tope de 50 suscripciones por workspace (por cuenta, si no usas workspaces), sea
cual sea su estado: con 50, crear otra responde `422` con `error`
`webhooks_limit_reached`.

No acepta `Idempotency-Key`: reintentar una creación que sí llegó crea otra suscripción,
con otro secreto.

**Cuerpo** (`application/json`, obligatorio)

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `url` | string (uri) | sí |  |
| `description` | string \| null | no |  |
| `events` | array<string ∈ {"device.disconnected", "device.connected", "device.deleted", "device.health_changed", "device.quality_changed", "device.messaging_limit_changed", "device.display_name_reviewed", "billing.payment_failed", "billing.upcoming_charge", "subscription.trial_ending", "subscription.reactivated", "subscription.cancellation_confirmed", "subscription.dormant_ending", "mac.usage_80", "mac.usage_100", "mac.expiring", "account.blocked", "message.received", "flow.completed", "broadcast.finished", "contact.stage_changed", "message.status_changed", "conversation.closed", "conversation.assigned", "contact.tag_added", "broadcast.paused", "contact.tag_removed", "contact.created", "template.status_changed", "flow.failed", "whatsapp_form.completed", "contact.updated", "message.reaction_failed", "group.created", "group.invite_link_down", "group.invite_link_renewed", "group_participant.joined", "group_participant.left", "scheduled_message.group_delivery_failed", "scheduled_message.response_received", "poll.voted", "pipeline.finished", "group.blocked", "group.recovered", "campaign.status_changed", "scheduled_message.finished", "group_action.failed", "daily_report.generated", "campaign.no_groups_available", "group.full", "group_action.completed", "group.message_received", "group.reaction_added", "group_join_request.created", "group_join_request.revoked"}> | sí |  |
| `filters` | object | no |  |
| `filters.campaign_ids` | array<string> \| null | no |  |

**Respuestas**

- `201` — La suscripción creada, con su secreto de firma (`secret`). Es la única vez que aparece.

  | Campo | Tipo | Descripción |
  |---|---|---|
  | `id` | string |  |
  | `url` | string |  |
  | `description` | string \| null |  |
  | `events` | array<string> |  |
  | `filters` | object \| null | Siempre un objeto: `{}` si no hay filtro. |
  | `status` | string |  |
  | `disabled_reason` | string \| null |  |
  | `last_delivery_at` | string \| null |  |
  | `last_success_at` | string \| null |  |
  | `secret_rotated_at` | string \| null |  |
  | `created_at` | string \| null |  |
  | `updated_at` | string \| null |  |
  | `migration` | object \| null |  |
  | `migration.origin` | string |  |
  | `migration.status` | string |  |
  | `migration.activated_via` | string \| null |  |
  | `migration.activated_at` | string \| null |  |
  | `migration.last_result` | string \| null |  |
  | `secret` | string |  |
  | `secret_notice` | "Guarda este secreto ahora: es la única vez que se muestra. Con él validas la firma del header de cada entrega." |  |

- `401` — Unauthenticated (`AccountsAuthenticationException`)
- `403` — Quien llama no puede usar esta ruta (`forbidden`). Los códigos de workspace que puede traer `error` con una clave:
- `422` — Validation error (`AccountsValidationException`)
- `429` — Superaste un límite de llamadas. Espera los segundos que indica `Retry-After` antes de volver a llamar.. Cabeceras: `Retry-After`

#### Ver tus webhooks

`GET /api/v1/webhooks` · permiso **Avisos (webhooks) → Ver** · área accounts · `operationId` `webhookSubscription.index`

**Para qué sirve:** Úsalo para revisar a qué URLs le está mandando eventos tu cuenta y en qué estado está cada suscripción.

**Listado** · `perPage` de 1 a 100 (por defecto 25) · orden fijo: id ascendente · no acepta parámetros de orden.

Con una clave de API, solo las que la clave puede leer: se omiten las que
tienen eventos de un área cuyo permiso le falta: **Números de WhatsApp → Ver**,
**Contactos y conversaciones → Ver** o **Grupos y campañas → Ver**.

**Respuestas**

- `200` — Las suscripciones del workspace.

  | Campo | Tipo | Descripción |
  |---|---|---|
  | `[].id` | string |  |
  | `[].url` | string |  |
  | `[].description` | string \| null |  |
  | `[].events` | array<string> |  |
  | `[].filters` | object \| null | Siempre un objeto: `{}` si no hay filtro. |
  | `[].status` | string |  |
  | `[].disabled_reason` | string \| null |  |
  | `[].last_delivery_at` | string \| null |  |
  | `[].last_success_at` | string \| null |  |
  | `[].secret_rotated_at` | string \| null |  |
  | `[].created_at` | string \| null |  |
  | `[].updated_at` | string \| null |  |
  | `[].migration` | object \| null |  |
  | `[].migration.origin` | string |  |
  | `[].migration.status` | string |  |
  | `[].migration.activated_via` | string \| null |  |
  | `[].migration.activated_at` | string \| null |  |
  | `[].migration.last_result` | string \| null |  |

- `401` — Unauthenticated (`AccountsAuthenticationException`)
- `403` — Quien llama no puede usar esta ruta (`forbidden`). Los códigos de workspace que puede traer `error` con una clave:
- `429` — Superaste un límite de llamadas. Espera los segundos que indica `Retry-After` antes de volver a llamar.. Cabeceras: `Retry-After`

#### Borrar un webhook

`DELETE /api/v1/webhooks/{id}` · permiso **Avisos (webhooks) → Administrar** · área accounts · `operationId` `webhookSubscription.destroy`

**Para qué sirve:** Úsalo para dejar de recibir los eventos de una suscripción; también se borra su historial de entregas.

Con una clave de API, la clave necesita además el permiso de lectura del
área de cada tipo de evento de la suscripción; si falta alguno, 403
`permission_denied` y no se borra.

**Parámetros**

| Nombre | En | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
| `id` | path | string | sí |  |

**Respuestas**

- `204` — No content
- `401` — Unauthenticated (`AccountsAuthenticationException`)
- `403` — La clave de API no tiene el permiso de lectura de un área de los eventos de la suscripción.
- `404`
- `409`
- `429` — Superaste un límite de llamadas. Espera los segundos que indica `Retry-After` antes de volver a llamar.. Cabeceras: `Retry-After`

#### Probar un webhook

`POST /api/v1/webhooks/{id}/test` · permiso **Avisos (webhooks) → Administrar** · área accounts · `operationId` `webhookSubscriptionTest.test`

**Para qué sirve:** Sirve para probar tu receptor y tu verificación de firma con una entrega firmada, sin esperar a que pase algo en tu cuenta.

Envía una entrega de prueba firmada a la URL de la suscripción y devuelve el resultado

Solo a suscripciones `active` o `paused`; una `disabled` responde 422 sin enviar nada.

Con una clave de API, la clave necesita además el permiso de lectura del área
de cada tipo de evento de la suscripción; si falta alguno, 403
`permission_denied`, antes que el 422 de una `disabled`.

**Parámetros**

| Nombre | En | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
| `id` | path | string | sí |  |

**Respuestas**

- `200`

  | Campo | Tipo | Descripción |
  |---|---|---|
  | `succeeded` | boolean |  |
  | `response_status` | integer \| null |  |
  | `error` | string \| null ∈ {"non_2xx", "internal_error", "timeout", "connection_failed", "tls_error", "destination_not_allowed", "secret_unreadable", null} |  |
  | `duration_ms` | integer \| null |  |
  | `delivery_id` | string | Id opaco: un texto que empieza con `dlv_`. Se usa tal como llega; no se arma ni se interpreta. |

- `401` — Unauthenticated (`AccountsAuthenticationException`)
- `403` — La clave de API no tiene el permiso de lectura de un área de los eventos de la suscripción.
- `404`
- `422` — La suscripción está deshabilitada: no se envía nada.
- `429` — Superaste un límite de llamadas. Espera los segundos que indica `Retry-After` antes de volver a llamar.. Cabeceras: `Retry-After`

### Los eventos

| Evento | Cuándo llega | Detalle y ejemplo |
|---|---|---|
| `message.received` | Alguien le escribe a uno de tus números. | «Mensajes» (en este archivo) |
| `message.status_changed` | Un mensaje que mandaste cambia de estado: enviado, entregado, leído o falló. | «Mensajes» (en este archivo) |
| `message.reaction_failed` | Una reacción que pediste no se pudo aplicar. | [Atender una conversación](https://developers-portal.funnelchat.app/ia/mas-funciones/whatsapp/atender-una-conversacion.md) |
| `template.status_changed` | Cambia el estado de aprobación de una de tus plantillas en Meta: por ejemplo, la aprueba o la rechaza. | [Plantillas de Meta](https://developers-portal.funnelchat.app/ia/mas-funciones/whatsapp/plantillas.md) |
| `broadcast.finished` | Una de tus difusiones termina: enviada, fallida o con fallos parciales. | [Difusiones](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/difusiones.md) |
| `broadcast.paused` | Una de tus difusiones se pausa sola, por ejemplo porque bajó la calidad del número. | [Difusiones](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/difusiones.md) |
| `device.connected` | Uno de tus números queda conectado. | «Conectar un número» (en este archivo) |
| `device.disconnected` | Uno de tus números pierde la conexión. | «Conectar un número» (en este archivo) |
| `device.deleted` | Se borra uno de tus números y libera su lugar en tu plan. | [Administrar tus números](https://developers-portal.funnelchat.app/ia/mas-funciones/whatsapp/administrar-tus-numeros.md) |
| `device.health_changed` | Cambia el estado de envío de uno de tus números oficiales, según Meta. | [Administrar tus números](https://developers-portal.funnelchat.app/ia/mas-funciones/whatsapp/administrar-tus-numeros.md) |
| `device.quality_changed` | Meta cambia la calidad de uno de tus números oficiales. | [Administrar tus números](https://developers-portal.funnelchat.app/ia/mas-funciones/whatsapp/administrar-tus-numeros.md) |
| `device.messaging_limit_changed` | Meta cambia el límite de mensajes por día de uno de tus números oficiales. | [Administrar tus números](https://developers-portal.funnelchat.app/ia/mas-funciones/whatsapp/administrar-tus-numeros.md) |
| `device.display_name_reviewed` | Meta aprueba o rechaza el nombre visible de uno de tus números oficiales. | [Administrar tus números](https://developers-portal.funnelchat.app/ia/mas-funciones/whatsapp/administrar-tus-numeros.md) |
| `group_participant.joined` | Alguien entra a un grupo que sigues. | «Grupos» (en este archivo) |
| `group_participant.left` | Alguien sale de un grupo que sigues. | «Grupos» (en este archivo) |
| `group.message_received` | Alguien escribe en un grupo que sigues. | [Grupos y sus acciones](https://developers-portal.funnelchat.app/ia/mas-funciones/whatsapp/grupos-y-acciones.md) |
| `group.reaction_added` | Alguien reacciona a un mensaje en un grupo que sigues. | [Grupos y sus acciones](https://developers-portal.funnelchat.app/ia/mas-funciones/whatsapp/grupos-y-acciones.md) |
| `poll.voted` | Alguien vota en una encuesta de un grupo, o cambia su voto. | [Grupos y sus acciones](https://developers-portal.funnelchat.app/ia/mas-funciones/whatsapp/grupos-y-acciones.md) |
| `group_join_request.created` | Alguien pide entrar a un grupo oficial que pide aprobación. | [Grupos y sus acciones](https://developers-portal.funnelchat.app/ia/mas-funciones/whatsapp/grupos-y-acciones.md) |
| `group_join_request.revoked` | Alguien retira su pedido para entrar a un grupo antes de que lo aprueben o lo rechacen. | [Grupos y sus acciones](https://developers-portal.funnelchat.app/ia/mas-funciones/whatsapp/grupos-y-acciones.md) |
| `group.created` | Se crea un grupo en una de tus campañas, o se importa a una. | [Grupos y sus acciones](https://developers-portal.funnelchat.app/ia/mas-funciones/whatsapp/grupos-y-acciones.md) |
| `group.full` | Un grupo se llena. | [Grupos y sus acciones](https://developers-portal.funnelchat.app/ia/mas-funciones/whatsapp/grupos-y-acciones.md) |
| `group.blocked` | Un grupo deja de poder operar: sin administrador conectado, con el link de invitación inválido o suspendido por WhatsApp. | [Grupos y sus acciones](https://developers-portal.funnelchat.app/ia/mas-funciones/whatsapp/grupos-y-acciones.md) |
| `group.recovered` | Un grupo que estaba bloqueado vuelve a operar. | [Grupos y sus acciones](https://developers-portal.funnelchat.app/ia/mas-funciones/whatsapp/grupos-y-acciones.md) |
| `group.invite_link_down` | El link de invitación de un grupo se cae y no se pudo renovar. | [Grupos y sus acciones](https://developers-portal.funnelchat.app/ia/mas-funciones/whatsapp/grupos-y-acciones.md) |
| `group.invite_link_renewed` | Se renueva el link de invitación de un grupo, solo o porque lo pediste. | [Grupos y sus acciones](https://developers-portal.funnelchat.app/ia/mas-funciones/whatsapp/grupos-y-acciones.md) |
| `group_action.completed` | Termina una acción sobre un grupo, como sumar participantes o cambiarle el nombre. | «Grupos» (en este archivo) |
| `group_action.failed` | Falla entera una acción sobre un grupo. | «Grupos» (en este archivo) |
| `campaign.status_changed` | Una de tus campañas de grupos se activa o se pausa. | [Campañas de grupos](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/campanas.md) |
| `campaign.no_groups_available` | Una de tus campañas no tiene grupos a los que llevar a quien entra por su link. | [Campañas de grupos](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/campanas.md) |
| `pipeline.finished` | Termina un pipeline de operaciones sobre grupos. | [Campañas de grupos](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/campanas.md) |
| `scheduled_message.finished` | Termina un envío programado a grupos, con su resultado. | [Envíos programados](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/envios-programados.md) |
| `scheduled_message.group_delivery_failed` | Un envío programado falla en un grupo. | [Envíos programados](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/envios-programados.md) |
| `scheduled_message.response_received` | Alguien responde a un envío programado: vota en una encuesta o responde a un evento de WhatsApp. | [Envíos programados](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/envios-programados.md) |
| `daily_report.generated` | Se genera el reporte diario de tu cuenta: clics, entradas y salidas. | [Estadísticas de tus grupos](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/estadisticas.md) |
| `contact.created` | Se crea un contacto nuevo. | [Contactos y conversaciones](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/contactos-y-conversaciones.md) |
| `contact.updated` | Cambian el nombre, el email, el teléfono o un campo personalizado de un contacto. | [Contactos y conversaciones](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/contactos-y-conversaciones.md) |
| `contact.tag_added` | Un contacto recibe una etiqueta. | [Etiquetas y campos personalizados](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/etiquetas-y-campos.md) |
| `contact.tag_removed` | Un contacto pierde una etiqueta. | [Etiquetas y campos personalizados](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/etiquetas-y-campos.md) |
| `conversation.assigned` | Una conversación queda asignada a una persona de tu equipo o a un agente de IA. | [Contactos y conversaciones](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/contactos-y-conversaciones.md) |
| `conversation.closed` | Una conversación se cierra. | [Contactos y conversaciones](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/contactos-y-conversaciones.md) |
| `contact.stage_changed` | Un contacto entra a un tablero, cambia de etapa o sale. | [Tableros](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/tableros.md) |
| `whatsapp_form.completed` | Un contacto completa un formulario de WhatsApp. | [Formularios de WhatsApp](https://developers-portal.funnelchat.app/ia/mas-funciones/whatsapp/formularios.md) |
| `flow.completed` | Una automatización termina bien para un contacto. | [Automatizaciones y carpetas de flujos](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/automatizaciones.md) |
| `flow.failed` | Una automatización termina por un error para un contacto. | [Automatizaciones y carpetas de flujos](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/automatizaciones.md) |
| `mac.usage_80` | Llegas al 80 % de tus contactos activos del mes. | [Tu cuenta y tu equipo](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/cuenta-y-equipo.md) |
| `mac.usage_100` | Agotas tus contactos activos del mes: empiezan 24 horas de gracia. | [Tu cuenta y tu equipo](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/cuenta-y-equipo.md) |
| `account.blocked` | Tu cuenta queda bloqueada: pasaron las 24 horas de gracia después de agotar tus contactos activos. | [Tu cuenta y tu equipo](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/cuenta-y-equipo.md) |
| `mac.expiring` | Tienes contactos activos que vencen en los próximos 7 días. | [Tu cuenta y tu equipo](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/cuenta-y-equipo.md) |
| `billing.upcoming_charge` | Faltan unos días para el próximo cobro de tu suscripción. | [Tu cuenta y tu equipo](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/cuenta-y-equipo.md) |
| `billing.payment_failed` | No se pudo cobrar tu suscripción. | [Tu cuenta y tu equipo](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/cuenta-y-equipo.md) |
| `subscription.trial_ending` | Tu prueba termina en 1 a 3 días. | [Tu cuenta y tu equipo](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/cuenta-y-equipo.md) |
| `subscription.cancellation_confirmed` | Se confirma la cancelación de tu suscripción. | [Tu cuenta y tu equipo](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/cuenta-y-equipo.md) |
| `subscription.reactivated` | Se revierte la cancelación que tenías programada: tu suscripción sigue. | [Tu cuenta y tu equipo](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/cuenta-y-equipo.md) |
| `subscription.dormant_ending` | Faltan unos 7 días para que termine el reposo de tu cuenta. | [Tu cuenta y tu equipo](https://developers-portal.funnelchat.app/ia/mas-funciones/funnelchat/cuenta-y-equipo.md) |

#### `webhook.test`

Evento de prueba enviado desde la ruta de prueba de una suscripción.

Ejemplo:

```json
{
  "id": "evt_000000000000000000000002",
  "type": "webhook.test",
  "version": 1,
  "occurred_at": "2026-10-01T12:00:00Z",
  "data": {
    "subscription": "00000000-0000-4000-8000-000000000001",
    "sent_at": "2026-10-01T12:00:00Z"
  }
}
```

### Verificar la firma

La cabecera `X-Funnelchat-Signature` trae `t=<unix>,v1=<hex>`. `v1` es el HMAC-SHA256, en hexadecimal, de `"<t>.<cuerpo crudo>"` con el secreto completo de la suscripción (con su prefijo `whsec_`). Calcúlalo sobre el cuerpo tal como llegó, antes de parsear el JSON, compáralo en tiempo constante y rechaza si `t` está a más de 300 segundos de la hora actual. Estas funciones están probadas contra la fórmula:

**Node.js:**

```js
// Verifica la cabecera X-Funnelchat-Signature de una entrega de webhook (Node.js 16+).
// cuerpoCrudo: el cuerpo tal como llegó (Buffer o string), sin parsear ni volver a serializar.
// secreto: el secreto completo de la suscripción, tal como se mostró al crearla o rotarla.
const crypto = require('node:crypto');

function verificarFirma(cuerpoCrudo, cabecera, secreto, toleranciaSegundos = 300) {
  if (typeof cabecera !== 'string' || typeof secreto !== 'string' || secreto === '') return false;

  let t = null;
  const firmas = [];
  for (const parte of cabecera.split(',')) {
    const i = parte.indexOf('=');
    if (i === -1) continue;
    const clave = parte.slice(0, i).trim();
    const valor = parte.slice(i + 1).trim();
    if (clave === 't') t = valor;
    if (clave === 'v1') firmas.push(valor);
  }
  if (t === null || !/^\d+$/.test(t) || firmas.length === 0) return false;

  // Rechaza entregas viejas o del futuro (protección contra repeticiones).
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(t)) > toleranciaSegundos) return false;

  const esperada = crypto
    .createHmac('sha256', secreto)
    .update(`${t}.`)
    .update(cuerpoCrudo)
    .digest('hex');
  const a = Buffer.from(esperada, 'utf8');

  return firmas.some((v1) => {
    const b = Buffer.from(v1, 'utf8');
    return a.length === b.length && crypto.timingSafeEqual(a, b);
  });
}

module.exports = { verificarFirma };

// Uso con Express: lee el cuerpo crudo, verifica, y recién después parsea.
// app.post('/hooks/funnelchat', express.raw({ type: 'application/json' }), (req, res) => {
//   if (!verificarFirma(req.body, req.get('X-Funnelchat-Signature'), process.env.FUNNELCHAT_WEBHOOK_SECRET)) {
//     return res.sendStatus(400);
//   }
//   const evento = JSON.parse(req.body.toString('utf8')); // toma type e id de acá, no de las cabeceras
//   res.sendStatus(200); // responde rápido; procesa después
// });
```

**Python:**

```python
# Verifica la cabecera X-Funnelchat-Signature de una entrega de webhook (Python 3.8+).
# cuerpo_crudo: los bytes del cuerpo tal como llegaron, sin parsear ni volver a serializar.
# secreto: el secreto completo de la suscripción, tal como se mostró al crearla o rotarla.
import hashlib
import hmac
import time

def verificar_firma(cuerpo_crudo: bytes, cabecera: str, secreto: str, tolerancia_segundos: int = 300) -> bool:
    if not isinstance(cabecera, str) or not isinstance(secreto, str) or not secreto:
        return False

    t = None
    firmas = []
    for parte in cabecera.split(","):
        clave, separador, valor = parte.partition("=")
        if not separador:
            continue
        clave, valor = clave.strip(), valor.strip()
        if clave == "t":
            t = valor
        elif clave == "v1":
            firmas.append(valor)
    if t is None or not t.isdigit() or not firmas:
        return False

    # Rechaza entregas viejas o del futuro (protección contra repeticiones).
    if abs(int(time.time()) - int(t)) > tolerancia_segundos:
        return False

    esperada = hmac.new(secreto.encode("utf-8"), t.encode("ascii") + b"." + cuerpo_crudo, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(esperada, v1) for v1 in firmas)

# Uso con Flask: lee el cuerpo crudo, verifica, y recién después parsea.
# @app.post("/hooks/funnelchat")
# def recibir():
#     cuerpo = request.get_data()  # bytes crudos
#     if not verificar_firma(cuerpo, request.headers.get("X-Funnelchat-Signature", ""), os.environ["FUNNELCHAT_WEBHOOK_SECRET"]):
#         return "", 400
#     evento = json.loads(cuerpo)  # toma type e id de acá, no de las cabeceras
#     return "", 200  # responde rápido; procesa después
```

**PHP:**

```php
<?php
// Verifica la cabecera X-Funnelchat-Signature de una entrega de webhook (PHP 8.0+).
// $cuerpoCrudo: el cuerpo tal como llegó (file_get_contents('php://input')), sin volver a codificar.
// $secreto: el secreto completo de la suscripción, tal como se mostró al crearla o rotarla.

function verificarFirma(string $cuerpoCrudo, string $cabecera, string $secreto, int $toleranciaSegundos = 300): bool
{
    if ($secreto === '') {
        return false;
    }

    $t = null;
    $firmas = [];
    foreach (explode(',', $cabecera) as $parte) {
        $i = strpos($parte, '=');
        if ($i === false) {
            continue;
        }
        $clave = trim(substr($parte, 0, $i));
        $valor = trim(substr($parte, $i + 1));
        if ($clave === 't') {
            $t = $valor;
        } elseif ($clave === 'v1') {
            $firmas[] = $valor;
        }
    }
    if ($t === null || ! ctype_digit($t) || $firmas === []) {
        return false;
    }

    // Rechaza entregas viejas o del futuro (protección contra repeticiones).
    if (abs(time() - (int) $t) > $toleranciaSegundos) {
        return false;
    }

    $esperada = hash_hmac('sha256', $t.'.'.$cuerpoCrudo, $secreto);
    foreach ($firmas as $v1) {
        if (hash_equals($esperada, $v1)) {
            return true;
        }
    }

    return false;
}

// Uso:
// $cuerpo = file_get_contents('php://input');
// if (! verificarFirma($cuerpo, $_SERVER['HTTP_X_FUNNELCHAT_SIGNATURE'] ?? '', (string) getenv('FUNNELCHAT_WEBHOOK_SECRET'))) {
//     http_response_code(400);
//     exit;
// }
// $evento = json_decode($cuerpo, true); // toma type e id de acá, no de las cabeceras
// http_response_code(200); // responde rápido; procesa después
```
