Funnelchat APICatálogo de eventos
Los eventos que emite hoy cada área, con su payload de ejemplo, y los que están planificados.
Los nombres son recurso.acción en inglés y se publican tal como los emite el código: renombrar un evento ya emitido rompería integraciones, así que no se hace en v0. Las descripciones están en español. (Q36, enmienda C3 del 04-10)
- Construido: el catálogo de eventos de su dominio lo declara emitido (
liveoactive) en el commit que el dominio tiene en producción, que es de donde sale cada instantánea. Si el catálogo no declara estado, se toma el de DECISIONES-2026-10-04. Cada evento dice de dónde sale su estado. - Planificado: anunciado para que te prepares. Todavía no lo vas a recibir, aunque te suscribas (ver abajo).
Los ejemplos de payload salen del código de cada dominio, no se escriben a mano. Si un evento no trae ejemplo, dice «ejemplo pendiente».
Construidos (48)
broadcast.finished — Conversations · construido
Una campaña llegó a su estado final (enviada, fallida o con fallos parciales), con sus conteos.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_000000000000000000000011",
"type": "broadcast.finished",
"version": 1,
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"broadcast": {
"id": 6001,
"name": "Campaña de ejemplo"
},
"status": "partially_failed",
"reason": "completed",
"totals": {
"processed": 1200,
"failed": 30,
"skipped_unreachable": 12
}
}
}broadcast.paused — Conversations · construido
Una campaña se pausó sola, por ejemplo porque bajó la calidad del número.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_000000000000000000000007",
"type": "broadcast.paused",
"version": 1,
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"broadcast": {
"id": 6001,
"name": "Campaña de ejemplo"
},
"reason": "quality_degraded",
"quality": "YELLOW",
"quality_baseline": "GREEN"
}
}contact.created — Conversations · construido
Se creó un contacto nuevo en la cuenta.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_000000000000000000000010",
"type": "contact.created",
"version": 1,
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"contact": {
"id": 2001,
"name": "Contacto de ejemplo",
"phone": "+5491100000000",
"email": "contacto@example.com"
}
}
}contact.stage_changed — Conversations · construido
Un contacto cambió de etapa en un tablero.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_000000000000000000000008",
"type": "contact.stage_changed",
"version": 1,
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"contact": {
"id": 2001,
"name": "Contacto de ejemplo",
"phone": "+5491100000000"
},
"board": {
"id": 5001,
"name": "Embudo de ejemplo"
},
"kind": "move",
"from_stage": {
"id": 6001,
"name": "Nuevo",
"position": 0
},
"to_stage": {
"id": 6002,
"name": "En seguimiento",
"position": 1
}
}
}contact.tag_added — Conversations · construido
Un contacto recibió una etiqueta.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_000000000000000000000006",
"type": "contact.tag_added",
"version": 1,
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"contact": {
"id": 2001,
"name": "Contacto de ejemplo",
"phone": "+5491100000000"
},
"tag": {
"id": 4001,
"name": "Etiqueta de ejemplo"
},
"source": "manual"
}
}contact.tag_removed — Conversations · construido
Un contacto perdió una etiqueta.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_000000000000000000000009",
"type": "contact.tag_removed",
"version": 1,
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"contact": {
"id": 2001,
"name": "Contacto de ejemplo",
"phone": "+5491100000000"
},
"tag": {
"id": 4001,
"name": "Etiqueta de ejemplo"
},
"source": "manual"
}
}conversation.assigned — Conversations · construido
Una conversación quedó asignada a una persona del equipo o a un agente de IA.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_000000000000000000000005",
"type": "conversation.assigned",
"version": 1,
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"contact": {
"id": 2001,
"name": "Contacto de ejemplo",
"phone": "+5491100000000"
},
"assignee": {
"type": "human",
"name": "Agente de ejemplo"
}
}
}conversation.closed — Conversations · construido
Una conversación pasó a cerrada.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_000000000000000000000004",
"type": "conversation.closed",
"version": 1,
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"contact": {
"id": 2001,
"name": "Contacto de ejemplo",
"phone": "+5491100000000"
}
}
}flow.completed — Conversations · construido
Un contacto terminó un flujo de automatización.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_000000000000000000000003",
"type": "flow.completed",
"version": 1,
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"flow": {
"id": 3001,
"name": "Flujo de ejemplo"
},
"contact": {
"id": 2001,
"name": "Contacto de ejemplo",
"phone": "+5491100000000"
}
}
}flow.failed — Conversations · construido
La ejecución de un flujo para un contacto terminó por un error.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_000000000000000000000013",
"type": "flow.failed",
"version": 1,
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"flow": {
"id": 3001,
"name": "Flujo de ejemplo"
},
"contact": {
"id": 2001,
"name": "Contacto de ejemplo",
"phone": "+5491100000000"
},
"reason": "execution_error"
}
}message.received — Conversations · construido
Un contacto le escribió a un número de WhatsApp de la cuenta.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_000000000000000000000001",
"type": "message.received",
"version": 1,
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"message": {
"id": 1001,
"type": "text",
"text": "Hola, quiero más información",
"media": null
},
"contact": {
"id": 2001,
"name": "Contacto de ejemplo",
"phone": "+5491100000000"
},
"receiver": {
"phone": "+5491100000001"
},
"device_id": 4521
}
}message.status_changed — Conversations · construido
Cambió el estado de entrega de un mensaje enviado.
Estados: sent, delivered, read, failed. DECISIONES-2026-10-04 lo registra como planificado; el dominio ya lo emite.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_000000000000000000000014",
"type": "message.status_changed",
"version": 1,
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"message_id": 1001,
"contact_id": 2001,
"device_id": 4521,
"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"
}
}template.status_changed — Conversations · construido
Una plantilla cambió de estado de aprobación en Meta.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_000000000000000000000012",
"type": "template.status_changed",
"version": 1,
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"template": {
"id": 7001,
"uid": "1234567890",
"name": "plantilla_ejemplo",
"category": "MARKETING"
},
"previous_status": "PENDING",
"status": "APPROVED",
"reason": null
}
}whatsapp_form.completed — Conversations · construido
Un contacto completó un formulario de WhatsApp.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_000000000000000000000015",
"type": "whatsapp_form.completed",
"version": 1,
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"form": {
"id": 4001,
"name": "Captar un lead",
"version_id": 4002
},
"message_id": 1001,
"contact_id": 2001,
"device_id": 5001,
"answers": [
{
"key": "nombre",
"label": "Nombre",
"value": "Contacto de ejemplo"
},
{
"key": "intereses",
"label": "Intereses",
"value": [
"op_a",
"op_b"
]
},
{
"key": "comentarios",
"label": "Comentarios",
"value": null
}
],
"occurred_at": "2026-10-01T12:00:00Z"
}
}campaign.no_groups_available — Communities · construido
Una campaña no tiene grupos a los que dirigir a las personas que entran por su link.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_0f8e4b526c1d4c7a9a3e2b5d",
"type": "campaign.no_groups_available",
"version": 1,
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"campaign": {
"uuid": "xK9mQz",
"name": "Campaña de ejemplo"
},
"reason": "none_selectable"
}
}campaign.status_changed — Communities · construido
Una campaña se activó o se pausó.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_00000000000000000000000000000009",
"type": "campaign.status_changed",
"version": 1,
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"campaign": {
"uuid": "00000000-0000-4000-8000-000000000009",
"name": "Campaña de ejemplo"
},
"from": "active",
"to": "paused"
}
}daily_report.generated — Communities · construido
Se generó el reporte diario de la cuenta (clics, ingresos y salidas).
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_0f8e4b526c1d4c7a9a3e2b5d",
"type": "daily_report.generated",
"version": 1,
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"period": {
"date": "2026-10-01",
"timezone": "America/Argentina/Buenos_Aires"
},
"clicks": 120,
"joins": 80,
"leaves": 10,
"conversion_rate": 0.67
}
}group.blocked — Communities · construido
Un grupo quedó inoperable: sin administrador conectado, con el link de invitación inválido o suspendido por WhatsApp.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_00000000000000000000000000000005",
"type": "group.blocked",
"version": 1,
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"group": {
"uid": "120363000000000001@g.us",
"name": "Grupo de ejemplo"
},
"campaign": {
"uuid": "00000000-0000-4000-8000-000000000001"
},
"reason": "admin_access_lost"
}
}group.created — Communities · construido
Se creó o se importó un grupo dentro de una campaña de la cuenta.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_00000000000000000000000000000001",
"type": "group.created",
"version": 1,
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"group": {
"uid": "120363000000000001@g.us",
"name": "Grupo de ejemplo",
"type": "group"
},
"campaign": {
"uuid": "00000000-0000-4000-8000-000000000001",
"name": "Campaña de ejemplo"
},
"source": "created"
}
}group.full — Communities · construido
Un grupo pasó de no estar lleno a estarlo.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_0f8e4b526c1d4c7a9a3e2b5d",
"type": "group.full",
"version": 1,
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"group": {
"uid": "120363000000000000@g.us",
"name": "Grupo de ejemplo",
"type": "tipo_de_ejemplo"
},
"campaign": {
"uuid": "xK9mQz",
"name": "Campaña de ejemplo"
},
"trigger": "participants_limit",
"participants": 1024
}
}group.invite_link_down — Communities · construido
El enlace de invitación de un grupo quedó confirmado caído (WhatsApp respondió que no existe y la renovación no consiguió otro); no se publica por errores transitorios ni por grupos prohibidos o suspendidos, y se publica una sola vez por episodio de bloqueo.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_0000000000000000000000000000000d",
"type": "group.invite_link_down",
"version": 1,
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"group": {
"uid": "120363000000000001@g.us",
"name": "Grupo de ejemplo",
"type": "group"
},
"campaign": {
"uuid": "00000000-0000-4000-8000-000000000001",
"name": "Campaña de ejemplo"
},
"reason": "http_404",
"renewal_attempted": true
}
}group.invite_link_renewed — Communities · construido
El enlace de invitación de un grupo cambió por una renovación, automática al detectarse inválido o pedida por el usuario; en v0 no se publican los cambios que detecta la sincronización ni el enlace inicial al crear el grupo.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_0000000000000000000000000000000c",
"type": "group.invite_link_renewed",
"version": 1,
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"group": {
"uid": "120363000000000001@g.us",
"name": "Grupo de ejemplo",
"type": "group"
},
"campaign": {
"uuid": "00000000-0000-4000-8000-000000000001",
"name": "Campaña de ejemplo"
},
"invite_link": "https://chat.whatsapp.com/EjemploNuevo0000000000001",
"previous_invite_link": "https://chat.whatsapp.com/EjemploAnterior000000000001",
"trigger": "automatic",
"recovered": false
}
}group.message_received — Communities · construido
Una persona escribió un mensaje en un grupo.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_0f8e4b526c1d4c7a9a3e2b5d",
"type": "group.message_received",
"version": 1,
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"group": {
"uid": "120363000000000000@g.us",
"name": "Grupo de ejemplo"
},
"participant": {
"identity": "5491100000000",
"identity_type": "phone",
"name": "Ana Ejemplo"
},
"message": {
"id": "msg-ejemplo-01",
"type": "text",
"text": "Hola a todos"
}
}
}group.reaction_added — Communities · construido
Una persona reaccionó a un mensaje de un grupo.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_0f8e4b526c1d4c7a9a3e2b5d",
"type": "group.reaction_added",
"version": 1,
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"group": {
"uid": "120363000000000000@g.us",
"name": "Grupo de ejemplo"
},
"participant": {
"identity": "5491100000000",
"identity_type": "phone",
"name": "Ana Ejemplo"
},
"message": {
"id": "msg-ejemplo-01"
},
"reaction": "👍"
}
}group.recovered — Communities · construido
Un grupo que estaba bloqueado volvió a operar.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_00000000000000000000000000000006",
"type": "group.recovered",
"version": 1,
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"group": {
"uid": "120363000000000001@g.us",
"name": "Grupo de ejemplo"
},
"campaign": {
"uuid": "00000000-0000-4000-8000-000000000001"
},
"reason": "access_restored"
}
}group_action.completed — Communities · construido
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.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"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
}
]
}
}
}group_action.failed — Communities · construido
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.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"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"
}
}group_join_request.created — Communities · construido
Una persona pidió unirse a un grupo oficial que pide aprobación para entrar, y su solicitud quedó pendiente. Si el grupo es de una campaña, también llega a las suscripciones filtradas por esa campaña. Se aprueba o rechaza por API con el teléfono de la persona, cuando el número anuncia groups.join_requests en "list_and_decide"; el resultado por persona llega en group_action.completed.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_0f8e4b526c1d4c7a9a3e2b5d",
"type": "group_join_request.created",
"version": 1,
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"group": {
"uid": "120363000000000000@g.us",
"name": "Grupo de ejemplo"
},
"participant": {
"identity": "5491100000000",
"identity_type": "phone",
"name": "Ana Ejemplo"
}
}
}group_join_request.revoked — Communities · construido
Una persona retiró su solicitud pendiente para unirse a un grupo antes de que se aprobara o rechazara. Trae los mismos campos que group_join_request.created.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_0f8e4b526c1d4c7a9a3e2b5d",
"type": "group_join_request.revoked",
"version": 1,
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"group": {
"uid": "120363000000000000@g.us",
"name": "Grupo de ejemplo"
},
"participant": {
"identity": "5491100000000",
"identity_type": "phone",
"name": "Ana Ejemplo"
}
}
}group_participant.joined — Communities · construido
Una persona entró a un grupo de la cuenta; campaign es null si el grupo no es de una campaña.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"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": "00000000-0000-4000-8000-000000000001"
},
"participant": {
"identity": "+5491100000000",
"identity_type": "phone",
"name": "Ana Pérez"
}
}
}group_participant.left — Communities · construido
Una persona salió de un grupo de la cuenta; campaign es null si el grupo no es de una campaña.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"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": "00000000-0000-4000-8000-000000000001"
},
"participant": {
"identity": "+5491100000000",
"identity_type": "phone",
"name": "Ana Pérez"
}
}
}pipeline.finished — Communities · construido
Terminó un pipeline de operaciones sobre grupos, con su resultado agregado y la clave de idempotencia del pedido que lo originó, cuando la hay.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_0000000000000000000000000000000a",
"type": "pipeline.finished",
"version": 1,
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"campaign": {
"uuid": "00000000-0000-4000-8000-00000000000a"
},
"pipeline": {
"uuid": "00000000-0000-4000-8000-00000000000b",
"name": "Pipeline de ejemplo"
},
"outcome": "completed",
"actions": {
"total": 5,
"succeeded": 4,
"failed": 0,
"skipped": 1,
"cancelled": 0
},
"idempotency_key": "00000000-0000-4000-8000-00000000000d"
}
}poll.voted — Communities · construido
Un participante votó en una encuesta enviada a un grupo, o cambió su voto.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_0000000000000000000000000000000b",
"type": "poll.voted",
"version": 1,
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"poll": {
"uid": "3EB0000000000000000001"
},
"group": {
"uid": "120363000000000001@g.us"
},
"scheduled_message": {
"uuid": "00000000-0000-4000-8000-000000000004"
},
"participant": {
"identity": "+5491100000000",
"identity_type": "phone",
"name": null
},
"options": [
"Opción A"
]
}
}scheduled_message.finished — Communities · construido
Un envío programado terminó, con su resultado agregado.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_00000000000000000000000000000004",
"type": "scheduled_message.finished",
"version": 1,
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"scheduled_message": {
"uuid": "00000000-0000-4000-8000-000000000004",
"name": "Envío de ejemplo"
},
"outcome": "partially_failed",
"groups": {
"total": 10,
"failed": 1,
"partially_failed": 2
},
"occurrence": 1
}
}scheduled_message.group_delivery_failed — Communities · construido
Un envío programado falló en un grupo concreto, con el motivo desagregado.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_00000000000000000000000000000007",
"type": "scheduled_message.group_delivery_failed",
"version": 1,
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"scheduled_message": {
"uuid": "00000000-0000-4000-8000-000000000007"
},
"group": {
"uid": "120363000000000001@g.us",
"name": "Grupo de ejemplo"
},
"reason": "device_disconnected",
"partial": false,
"occurrence": 1
}
}scheduled_message.response_received — Communities · construido
Alguien respondió a un envío programado votando una encuesta o respondiendo a un evento.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_00000000000000000000000000000008",
"type": "scheduled_message.response_received",
"version": 1,
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"scheduled_message": {
"uuid": "00000000-0000-4000-8000-000000000008"
},
"group": {
"uid": "120363000000000001@g.us"
},
"participant": {
"identity": "+5491100000000",
"identity_type": "phone",
"name": "Ana Pérez"
},
"response": {
"type": "poll",
"options": [
"Opción A"
],
"rsvp": null
}
}
}account.blocked — Accounts · construido
La cuenta quedó bloqueada por consumo: terminó la gracia de 24 horas tras agotar los contactos activos mensuales sin que se regularizara.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_0f8e4b526c1d4c7a9a3e2b5d",
"type": "account.blocked",
"version": 1,
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"reason": "mac_grace_expired",
"grace_started_at": "2026-10-01T12:00:00Z",
"grace_expired_at": "2026-10-02T12:00:00Z"
}
}billing.payment_failed — Accounts · construido
Un cobro de la suscripción no pudo procesarse (solo suscripciones de Stripe). Se emite una vez por factura (el primer intento fallido); no se repite en los reintentos de cobro. No incluye las recargas de IA.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_0f8e4b526c1d4c7a9a3e2b5d",
"type": "billing.payment_failed",
"version": 1,
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"amount_cents": 2990,
"currency": "USD"
}
}billing.upcoming_charge — Accounts · construido
Se acerca el próximo cobro de la suscripción (solo suscripciones de Stripe); el aviso llega unos días antes de la fecha de cobro.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_0f8e4b526c1d4c7a9a3e2b5d",
"type": "billing.upcoming_charge",
"version": 1,
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"charge_date": "2026-11-05T00:00:00Z",
"amount_cents": 2990,
"currency": "USD"
}
}device.connected — Accounts · construido
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.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_0f8e4b526c1d4c7a9a3e2b5d",
"type": "device.connected",
"version": 1,
"occurred_at": "2026-10-05T03:00:00Z",
"data": {
"device": {
"id": 4521,
"name": "Ventas",
"number": "5491100000000"
},
"connected_at": "2026-10-05T03:00:00+00:00"
}
}device.disconnected — Accounts · construido
Uno de los números de WhatsApp de la cuenta se desconectó y dejó de poder enviar o recibir.
Solo números conectados por código QR: los de WhatsApp Cloud todavía no lo emiten.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_0f8e4b526c1d4c7a9a3e2b5d",
"type": "device.disconnected",
"version": 1,
"occurred_at": "2026-10-05T03:00:00Z",
"data": {
"device": {
"id": 4521,
"name": "Ventas",
"number": "5491100000000"
},
"disconnected_at": "2026-10-05T03:00:00+00:00"
}
}mac.expiring — Accounts · construido
Hay contactos activos mensuales que vencen en los próximos 7 días.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_0f8e4b526c1d4c7a9a3e2b5d",
"type": "mac.expiring",
"version": 1,
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"contacts_expiring": 1200,
"expires_at": "2026-10-08T03:00:00Z"
}
}mac.usage_100 — Accounts · construido
La cuenta agotó sus contactos activos mensuales del ciclo; se abre una gracia de 24 horas cuyo vencimiento viaja en grace_expires_at.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_0f8e4b526c1d4c7a9a3e2b5d",
"type": "mac.usage_100",
"version": 1,
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"used": 10000,
"limit": 10000,
"percentage": 100,
"cycle_started_at": "2026-10-01T00:00:00Z",
"grace_expires_at": "2026-10-02T12:00:00Z"
}
}mac.usage_80 — Accounts · construido
La cuenta alcanzó el 80% de sus contactos activos mensuales del ciclo.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_0f8e4b526c1d4c7a9a3e2b5d",
"type": "mac.usage_80",
"version": 1,
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"used": 8000,
"limit": 10000,
"percentage": 80,
"cycle_started_at": "2026-10-01T00:00:00Z"
}
}subscription.cancellation_confirmed — Accounts · construido
Quedó confirmada la cancelación de la suscripción (solo suscripciones de Stripe): se conserva el acceso hasta la fecha indicada.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_0f8e4b526c1d4c7a9a3e2b5d",
"type": "subscription.cancellation_confirmed",
"version": 1,
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"access_until": "2026-11-05T00:00:00Z"
}
}subscription.dormant_ending — Accounts · construido
El período de cuenta en reposo está por terminar (el aviso llega unos 7 días antes); en esa fecha se intenta el cobro indicado.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_0f8e4b526c1d4c7a9a3e2b5d",
"type": "subscription.dormant_ending",
"version": 1,
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"charge_date": "2026-10-08T00:00:00Z",
"amount_cents": 1990,
"currency": "USD"
}
}subscription.reactivated — Accounts · construido
Se revirtió la cancelación programada de la suscripción (solo suscripciones de Stripe): sigue vigente y se renueva en la fecha indicada.
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_0f8e4b526c1d4c7a9a3e2b5d",
"type": "subscription.reactivated",
"version": 1,
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"renews_at": "2026-11-05T00:00:00Z"
}
}subscription.trial_ending — Accounts · construido
El período de prueba está por terminar; el aviso llega entre 1 y 3 días antes del final, según cómo se contrató (en las suscripciones de Stripe, el aviso de Stripe).
Fuente: catálogo del dominio (GET …/webhooks/events); estado según dominio.
{
"id": "evt_0f8e4b526c1d4c7a9a3e2b5d",
"type": "subscription.trial_ending",
"version": 1,
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"trial_ends_at": "2026-10-04T00:00:00Z"
}
}Planificados (0) — todavía no se emiten
| Evento | Dominio | Descripción | Nota |
|---|
Suscribirse a un evento planificado
El catálogo (GET /api/v1/webhooks/events, con una clave con accounts:read) lista los eventos de las tres áreas. Cada entrada trae type, area (accounts, conversations o communities), label, description, status, subscribable y example con el cuerpo completo que vas a recibir; meta dice cuántos hay, cuántos se emiten y el formato de la firma.
status es active si el evento se emite y planned si se puede suscribir pero todavía no se emite. El alta de una suscripción acepta los planificados en events: suscribirte a uno no da error, pero no te llega nada hasta que se empiece a emitir.
- Antes de depender de un evento, mirá su
statusen el catálogo:activese emite;planned, todavía no. - No hay comodín para «todos»: elegís cada tipo, así que solo recibís lo que pediste.
- El ejemplo de un evento planificado puede cambiar antes de que se empiece a emitir.
webhook.testfigura en el catálogo consubscribable: false: llega solo cuando pedís una prueba.
identity_type
Los eventos de communities que traen un participante (participant) lo identifican con identity e identity_type. v0 documenta un solo valor de identity_type: phone, y en ese caso identity es un teléfono con + (cómo buscarlo en la API). Pueden aparecer otros valores sin aviso.
Qué hacer: procesá identity como teléfono solo si identity_type es phone. Si llega un valor que no conocés, respondé 2xx igual e ignorá ese participante (o registralo para revisarlo): no es un error de la entrega.
Otros eventos y notas
webhook.test: la entrega de prueba que mandaPOST /api/v1/webhooks/{id}/test, firmada igual que un evento real. No se puede suscribir a él.- Accounts anuncia además 5 tipos planificados que no están en el catálogo v0 (DECISIONES-2026-10-04) y por eso no se listan arriba:
billing.plan_blocked,subscription.expiring,ai_quota.low_balance,ai_quota.topup_succeeded,ai_quota.topup_failed.
Fuentes del catálogo por dominio: Conversations: catálogo del dominio (GET …/webhooks/events); Communities: catálogo del dominio (GET …/webhooks/events); Accounts: catálogo del dominio (GET …/webhooks/events).
message.status_changedse emite cuando cambia el estado de entrega de un mensaje que enviaste a un contacto, desde el chat, una automatización, un asistente de IA o con tu clave. No se emite para los mensajes de difusiones ni para los recibidos. Hay que pedirlo de forma explícita enevents. Ver Estados de mensaje.group.invite_link_downpuede repetirse: si después de un link caído una sincronización vuelve a habilitar el grupo aunque el link siga muerto, la validación siguiente emite otrodown. Tratá el evento como idempotente por grupo. (E32)device.connectedydevice.disconnected(accounts) se suscriben en/api/v1/webhooks, como el resto; también llegan por el sistema anterior de accounts. Sudata.device.numberva sin+, y un número de WhatsApp Cloud todavía no emitedevice.disconnected. (E29, E30, E37)- Datos planificados dentro de
message.received, no como eventos aparte: si el contacto llegó desde un anuncio (Click-to-WhatsApp) y si está respondiendo a una difusión. El ejemplo de hoy todavía no los trae. - Fuera de v0: puntaje de leads, pagos y redes sociales. (Q35)
- Un evento entra al catálogo si un integrador actúa sobre él, no es una manguera de cambios, no expone datos internos ni perfila personas, y el dominio lo emite con test. (Q33)