## Visión general

Varios módulos de la plataforma emiten **eventos** cuando algo cambia — se crea una conversación, se
confirma un pago, un negocio cambia de etapa, etc. Puedes reaccionar a estos eventos vía **webhooks** o
mediante las **reglas de automatización** internas.

## Requisitos previos

- Webhooks configurados (para consumo externo) o acceso a Automatización (para reacciones internas).

## Paso a paso

1. Identifica el evento del módulo que quieres consumir (ej.: conversación creada, pago pagado).
2. Para consumo externo: suscríbete al evento en el webhook y maneja el payload en tu endpoint.
3. Para reacciones internas: crea una regla de automatización con el disparador correspondiente.
4. Valida y procesa el payload de forma idempotente.

## Configuración y opciones

- **Webhooks**: suscripción por bandeja/cuenta.
- **Automatización**: disparadores por evento, con condiciones y acciones.
- **Payload**: contiene el contexto del evento (ids y datos relevantes).

### Nuevos eventos por módulo (payloads reales)

Los campos siguientes provienen de la fuente real de cada evento — no inventes el formato. Todos se
entregan a **webhooks de cuenta**; las llamadas y respuestas de Flow también van al webhook del
**canal de API**. La entrega de cada grupo requiere la **función del módulo habilitada** en la cuenta
(la suscripción funciona aunque la función esté apagada, pero no se entrega nada).

### Gestión de Equipo — función: Gestión de Equipo

- `wfm_status_changed`, `wfm_break_started` — el agente cambió de estado / entró en pausa. Campos:
  `account_id`, `account_user_id`, `user_id`, `status_key`, `status_event_id`, `base_availability`, `family`.
- `wfm_break_breached` — la pausa superó el límite. Campos: los anteriores más `expected_seconds` y `over_by_seconds`.
- `wfm_break_ended` — el agente salió de una pausa (cualquier vía: cambio manual, selector nativo o auto-offline).
  Campos: los del inicio de pausa más `duration_seconds`, `within_limit` y, si se excedió, `over_by_seconds`.
- `wfm_shift_started`, `wfm_shift_ended` — la ventana del turno planificado del agente se abrió/cerró (evaluado en el
  servidor cada minuto). Campos: `account_id`, `account_user_id`, `user_id`, `shift_id`, `schedule_id` (cuando se
  genera desde una plantilla), `date`, `starts_at`, `ends_at`. Cada evento del ciclo se dispara exactamente una vez por turno.

### Difusiones del WhatsApp Hub — función: WhatsApp Hub

- `whatsapp_broadcast_started`, `whatsapp_broadcast_completed`, `whatsapp_broadcast_failed` — la difusión
  cambió de estado. Campos (sin contenido de mensaje): `account_id`, `inbox_id`, `broadcast_id`, `display_id`,
  `title`, `status`, `target_type`, `recipients_count`. Funciona en bandejas Cloud y WazMeow (WhatsApp Web).

### Bienvenidas y despedidas de grupo de WhatsApp — función: WhatsApp Hub

- `whatsapp_group_member_welcomed`, `whatsapp_group_member_farewelled` — se disparan **solo cuando** el mensaje
  de bienvenida/despedida se envió realmente (idempotente, una vez por participante por ventana de
  deduplicación). Campos: `account_id`, `inbox_id`, `whatsapp_group_id`, `group_jid`, `participant_jid`,
  `participant_phone`, `trigger` (`welcome` o `farewell`). Sin contenido de mensaje.

### Ads Manager — función: Growth Ads o Ads Manager

- `ads_campaign_status_changed` — el estado efectivo de una campaña reflejada cambió. Campos: `account_id`,
  `ad_account_id`, `campaign_id`, `remote_id`, `status`, `effective_status`, `previous_effective_status`.
- `ctwa_conversation_started` — empezó una conversación por Clic-a-WhatsApp (se emite con el mensaje del cliente). En ese momento la ventana del anuncio queda esperando la primera respuesta, y `expires_at` es el **plazo de 24 horas para responder**. Si la empresa responde dentro de ese plazo, la ventana gratuita se abre por hasta 7 días, o hasta el cierre exacto que informe Meta. Campos:
  `account_id`, `conversation_id`, `contact_id`, `inbox_id`, `window_id`, `expires_at`.
- `ad_window_expiring` — esa ventana está por expirar. Mismos campos.

### Llamadas y respuestas de Flow de WhatsApp — función: WhatsApp Inbox Suite

- `whatsapp_call_started`, `whatsapp_call_ended`, `whatsapp_call_recording_ready` — el ciclo de vida de la
  llamada. Campos (los presentes varían según la etapa): `provider_call_id`, `conversation_id`, `realtime`,
  `status`, `recording_url`. Entregado a webhooks de cuenta y de canal de API.
  Para la grabación del navegador, `whatsapp_call_recording_ready` se emite después de habilitar la
  grabación en la bandeja y guardar el audio subido en el almacenamiento. Finalizar la llamada no basta.
  El webhook debe suscribirse a este evento; `recording_url` apunta a la grabación disponible.
- `whatsapp_flow_response_received` — el cliente completó un WhatsApp Flow. Campos: el objeto `flow_response`
  (`id`, `whatsapp_flow_id`, `screen`, `response`, `contact_id`, `conversation_id`) y el objeto `conversation`.
  Entregado a webhooks de cuenta y de canal de API.

### Sesiones del FlowBuilder — función: Flow Builder

- `flow_session_started`, `flow_session_updated`, `flow_session_completed`, `flow_session_failed` — la sesión del
  flujo se inició, se pausó, se completó o falló. Campos: `id`, `flow_id`, `status`, `current_node_id`,
  `conversation_id`, `account_id`.

## Casos de uso

- Actualizar un sistema externo cuando se confirma un pago.
- Disparar una cadencia de follow-up cuando un negocio cambia de etapa.

## Consejos, límites y buenas prácticas

- Consulta siempre la fuente real del payload antes de mapear campos (no inventes el formato).
- Garantiza idempotencia por identificador del evento.

## Solución de problemas

- **El evento no llega**: confirma la suscripción y el estado del endpoint.
- **Campos inesperados**: revisa el payload real recibido y ajusta el mapeo.

## Ver también

- [API REST, tokens y webhooks](/hc/ajuda/articles/api-developers-rest-tokens-webhooks-es)
- [Reglas de automatización](/hc/ajuda/articles/automation-flows-regras-de-automacao-es)
- [Canal API: el contrato estructurado de eventos](/hc/ajuda/articles/api-developers-api-channel-contract-es)