Webhooks — Eventos de encuesta

Cinco eventos siguen el ciclo de vida de una encuesta de satisfacción, desde que se envía
hasta que se completa o vence.

Evento	Cuándo se dispara
`survey_sent`	La encuesta se envió al contacto
`survey_started`	El contacto empezó a responderla
`survey_response_received`	Llegó una respuesta
`survey_completed`	La encuesta se completó
`survey_expired`	Venció sin completarse

Los cinco se filtran por línea cuando la encuesta es de WhatsApp. Las de Instagram y
Messenger no tienen línea: llegan a todos sus webhooks de encuestas, y se distinguen por
channel_type.

Campos garantizados

Campo	Tipo	Notas
`session_id`	int	Id de la sesión de encuesta. Es la llave que une los cinco eventos
`survey_config_id`	int	Configuración de encuesta que la originó
`user_id`	int	Cuenta dueña
`whatsapp_number_id`	int	Línea por la que se envió
`contact_id`	int \| null	Id del contacto
`contact_wa_id`	string \| null	⚠️ Clave de conversación: teléfono o BSUID, igual que `wa_id` en los mensajes
`bsuid`	string \| null	Ver Identidad del contacto
`wa_username`	string \| null
`agent_id`	int \| null	Agente que atendió la conversación
`chat_bot_id`	int \| null	Bot que la originó, si aplica
`trigger_type`	string \| null	Qué disparó la encuesta
`status`	string	`pending`, `sent`, `in_progress`, `completed`, `expired`, `cancelled`
`channel_type`	string	`whatsapp`, `messenger` o `instagram`
`channel_uuid`	string \| null	El canal social de la encuesta. `null` en WhatsApp
`version`	int	`1`

Campos propios de cada evento

Además del piso, cada evento agrega los suyos:

Evento	Campos extra
`survey_sent`	`sent_at`, `lock_until`
`survey_started`	`started_at`
`survey_response_received`	`response_id`, `response_type`, `response_value`, `response_text`, `responded_at`, `current_step_id`, `session_status`
`survey_completed`	`completed_at`, `total_responses`, `responses` (el arreglo con todas)
`survey_expired`	`expired_at`, `previous_status`

Ejemplo — `survey_response_received`

{
  "event": "survey_response_received",
  "data": {
    "session_id": 7001,
    "survey_config_id": 12,
    "user_id": 1234,
    "whatsapp_number_id": 42,
    "contact_id": 987654,
    "contact_wa_id": "573001234567",
    "bsuid": null,
    "wa_username": null,
    "agent_id": 88,
    "chat_bot_id": null,
    "trigger_type": "conversation_closed",
    "status": "in_progress",
    "response_id": 30012,
    "response_type": "rating",
    "response_value": { "rating": 5, "text": "Excelente atención" },
    "response_text": "Excelente atención",
    "responded_at": "2026-08-07 15:22:40",
    "current_step_id": 1,
    "session_status": "in_progress",
    "version": 1
  }
}

Ejemplo — `survey_completed`

{
  "event": "survey_completed",
  "data": {
    "session_id": 7001,
    "survey_config_id": 12,
    "user_id": 1234,
    "whatsapp_number_id": 42,
    "contact_id": 987654,
    "contact_wa_id": "573001234567",
    "bsuid": null,
    "wa_username": null,
    "agent_id": 88,
    "chat_bot_id": null,
    "trigger_type": "conversation_closed",
    "status": "completed",
    "completed_at": "2026-08-07 15:23:02",
    "total_responses": 2,
    "responses": [ { "...": "cada respuesta de la sesión" } ],
    "version": 1
  }
}

Notas de comportamiento

Use `session_id` para unir el ciclo

Los cinco eventos de una misma encuesta comparten session_id. Es la llave para armar el
recorrido completo sin depender del orden de llegada — que no está garantizado.

`survey_completed` trae todo junto

Si solo le interesa el resultado final y no el recorrido, suscríbase únicamente a
survey_completed: trae responses con todas las respuestas de la sesión, así que no
necesita ir acumulando los survey_response_received.

Filtrar las encuestas por canal

Si su integración solo procesa WhatsApp, descarte los eventos con channel_type distinto de
whatsapp. En las encuestas de Instagram y Messenger, whatsapp_number_id, contact_wa_id,
bsuid y wa_username llegan en null.

Una encuesta puede terminar sin `survey_completed`

Si el contacto no responde, la sesión vence y llega survey_expired, no survey_completed.
Si su lógica espera un cierre, contemple los dos.

Ver también

Identidad del contacto — contact_wa_id puede ser un BSUID

Campos garantizados

Campos propios de cada evento

Ejemplo — survey_response_received

Ejemplo — survey_completed