# Catálogo de eventos

> Todos los eventos de webhook de watsi — mensajes, conversaciones, contactos, citas, campañas y acciones del agente — con el cuerpo real que envía cada uno.

Source: https://docs.watsi.ai/webhooks/events

Esta lista sale del catálogo de eventos de watsi al construir el sitio: un evento nuevo no puede publicarse sin aparecer aquí. Los cuerpos de ejemplo están transcritos del código que emite cada evento.

Antes de leerla, tres cosas que valen para todos:

- **El cuerpo es el evento, sin sobre.** El tipo llega en `X-Watsi-Event` y el id de entrega en `X-Watsi-Delivery-Id` ([encabezados](/webhooks#qué-recibes)).
- **Los ids son UUID** y las fechas, ISO 8601 en UTC, salvo donde se indica.
- **Lee las claves que existan.** Algunos eventos tienen más de una forma según de dónde vengan (el agente o la app) y lo dice su descripción. Ignora las claves que no conozcas: pueden aparecer campos nuevos.

Un evento marcado **Reservado** está en el catálogo pero todavía no se envía: puedes suscribirte, pero no recibirás nada hasta que lo anunciemos en [Novedades](/changelog).

### Mensajes

#### `message.received`

Llegó un mensaje de un cliente (WhatsApp, Instagram, Messenger o el widget web).

```json
{
  "message_id": "0b8f6c2e-4a51-4d0e-9a57-2f1d8c3e7b90",
  "conversation_id": "6d2a9e14-8f3b-4c7a-b1e5-90c4d7f2a318",
  "customer_id": "c41f7b8a-2e6d-4a93-8b05-1d7e9f3c6a24",
  "content": "Hola, ¿tienen citas para mañana?",
  "content_type": "text",
  "provider": "whatsapp",
  "external_message_id": "wamid.HBgNNTIxNTUxMjM0NTY3OBUCABIYIDNBMkY",
  "created_at": "2026-10-30T16:04:11.000Z"
}
```

#### `message.sent`

El agente de IA o una automatización envió un mensaje. Los mensajes que escribe tu equipo a mano no lo disparan.

```json
{
  "message_id": "0b8f6c2e-4a51-4d0e-9a57-2f1d8c3e7b90",
  "conversation_id": "6d2a9e14-8f3b-4c7a-b1e5-90c4d7f2a318",
  "provider": "whatsapp"
}
```

#### `message.status_changed`

WhatsApp reportó un cambio de estado de un mensaje enviado (`sent`, `delivered`, `read`, `failed`). `timestamp` es el de Meta, en segundos Unix.

```json
{
  "message_id": "0b8f6c2e-4a51-4d0e-9a57-2f1d8c3e7b90",
  "conversation_id": "6d2a9e14-8f3b-4c7a-b1e5-90c4d7f2a318",
  "external_message_id": "wamid.HBgNNTIxNTUxMjM0NTY3OBUCABIYIDNBMkY",
  "status": "delivered",
  "timestamp": "1761840251"
}
```

### Conversaciones

#### `agent.handoff_requested`

El agente de IA escaló la conversación a una persona. `trigger_text` son los primeros 200 caracteres del mensaje que lo provocó.

```json
{
  "conversation_id": "6d2a9e14-8f3b-4c7a-b1e5-90c4d7f2a318",
  "reason": "customer_requested_human",
  "rule_id": null,
  "trigger_text": "Quiero hablar con un asesor, por favor",
  "required_field_name": null
}
```

#### `conversation.created`

Empezó una conversación nueva. Es también la señal de un contacto nuevo que llegó escribiendo.

```json
{
  "conversation_id": "6d2a9e14-8f3b-4c7a-b1e5-90c4d7f2a318",
  "customer_id": "c41f7b8a-2e6d-4a93-8b05-1d7e9f3c6a24",
  "provider": "whatsapp",
  "created_at": "2026-10-30T16:04:11.000Z"
}
```

#### `conversation.assigned`

La conversación se asignó a un miembro del equipo. Desde la app llega también `assigned_by`.

```json
{
  "conversation_id": "6d2a9e14-8f3b-4c7a-b1e5-90c4d7f2a318",
  "assigned_user_id": "9e3b5d71-c2a8-4f60-8d14-7a6b2e9c0f53"
}
```

#### `conversation.stage_changed`

La conversación cambió de etapa del embudo. Desde la app llega también `changed_by`.

```json
{
  "conversation_id": "6d2a9e14-8f3b-4c7a-b1e5-90c4d7f2a318",
  "stage": "Cotización enviada",
  "previous_stage": "Interesado"
}
```

#### `conversation.cancelled`

La conversación se canceló: Watsi la canceló sola al detectar una queja sin interés de seguir, o la canceló alguien del equipo. `reason` es texto libre.

Cancelación automática:

```json
{
  "conversation_id": "6d2a9e14-8f3b-4c7a-b1e5-90c4d7f2a318",
  "reason": "Complaint + disengagement detected: Customer complaint; asked for a human",
  "trigger_text": "Pésimo servicio, ya no quiero nada"
}
```

Desde la app de Watsi:

```json
{
  "conversation_id": "6d2a9e14-8f3b-4c7a-b1e5-90c4d7f2a318",
  "cancelled_by": "9e3b5d71-c2a8-4f60-8d14-7a6b2e9c0f53",
  "cancelled_reason": "Duplicado"
}
```

#### `conversation.closed`

La conversación se cerró (resolvió). Desde la app llega también `resolved_by`.

```json
{
  "conversation_id": "6d2a9e14-8f3b-4c7a-b1e5-90c4d7f2a318",
  "resolved_at": "2026-10-30T18:20:45.000Z"
}
```

#### `conversation.reopened`

Una conversación cerrada se reabrió. Desde la app llega también `reopened_by`.

```json
{
  "conversation_id": "6d2a9e14-8f3b-4c7a-b1e5-90c4d7f2a318"
}
```

### Contactos

#### `contact.created`

Se creó un contacto por la API anterior (`watsi.ai/api/v1/contacts`, incluida su importación de hasta 50). Hoy no lo disparan `POST /v1/actions/contacts/create`, la app ni un contacto que llega escribiendo: para ese caso escucha `conversation.created`.

```json
{
  "contact_id": "c41f7b8a-2e6d-4a93-8b05-1d7e9f3c6a24",
  "name": "María García",
  "phone_number": "5215512345678",
  "email": "maria@example.com",
  "wa_id": "5215512345678"
}
```

Importación de hasta 50:

```json
{
  "contact_id": "c41f7b8a-2e6d-4a93-8b05-1d7e9f3c6a24",
  "source": "batch_import"
}
```

#### `contact.batch_created`

Una importación por la API anterior creó más de 50 contactos: un solo evento con todos los ids.

```json
{
  "contact_ids": [
    "c41f7b8a-2e6d-4a93-8b05-1d7e9f3c6a24",
    "5e8a2c71-9d04-4b3f-a6e1-7c2f9b5d3a80"
  ],
  "count": 2,
  "source": "batch_import"
}
```

#### `contact.updated`

Se actualizó un contacto por la API anterior (`watsi.ai/api/v1/contacts/{id}`). `updated_fields` dice qué cambió.

```json
{
  "contact_id": "c41f7b8a-2e6d-4a93-8b05-1d7e9f3c6a24",
  "updated_fields": [
    "name",
    "email"
  ]
}
```

#### `contact.tagged` (reservado, aún no se envía)

Reservado: un contacto recibió una etiqueta. Está en el catálogo pero todavía no se envía.

#### `contact.untagged` (reservado, aún no se envía)

Reservado: a un contacto se le quitó una etiqueta. Está en el catálogo pero todavía no se envía.

### Citas

#### `appointment.created`

Se agendó una cita nueva. Los campos van en camelCase.

```json
{
  "eventId": "a7c2e9f4-6b13-4d85-9e20-3f8b1c5d7a69",
  "startAt": "2026-11-04T16:00:00.000Z",
  "endAt": "2026-11-04T16:30:00.000Z",
  "assignedUserId": "9e3b5d71-c2a8-4f60-8d14-7a6b2e9c0f53",
  "customerId": "c41f7b8a-2e6d-4a93-8b05-1d7e9f3c6a24"
}
```

#### `appointment.updated`

Cambió una cita: horario, detalles, confirmación o rechazo. Tiene varias formas según de dónde venga; lee las claves que existan.

Desde la agenda (agente o reserva en línea):

```json
{
  "eventId": "a7c2e9f4-6b13-4d85-9e20-3f8b1c5d7a69",
  "startAt": "2026-11-04T17:00:00.000Z",
  "endAt": "2026-11-04T17:30:00.000Z",
  "updatedFields": [
    "startAt",
    "endAt"
  ]
}
```

Desde la app de Watsi:

```json
{
  "appointment_id": "a7c2e9f4-6b13-4d85-9e20-3f8b1c5d7a69",
  "updated_fields": [
    "status"
  ],
  "status": "confirmed"
}
```

#### `appointment.cancelled`

Se canceló una cita.

Desde la agenda (agente o reserva en línea):

```json
{
  "eventId": "a7c2e9f4-6b13-4d85-9e20-3f8b1c5d7a69",
  "reason": "Cliente pidió cancelar",
  "startAt": "2026-11-04T16:00:00.000Z",
  "customerId": "c41f7b8a-2e6d-4a93-8b05-1d7e9f3c6a24"
}
```

Desde la app de Watsi:

```json
{
  "appointment_id": "a7c2e9f4-6b13-4d85-9e20-3f8b1c5d7a69",
  "cancelled_by": "9e3b5d71-c2a8-4f60-8d14-7a6b2e9c0f53"
}
```

#### `appointment.rescheduled`

Una reserva nueva reemplazó a una cita existente. `replacedEventId` es la cita anterior.

```json
{
  "eventId": "a7c2e9f4-6b13-4d85-9e20-3f8b1c5d7a69",
  "replacedEventId": "f1d4b8e2-9a37-4c6e-b052-8e3a7c1d9b46",
  "startAt": "2026-11-05T15:00:00.000Z",
  "endAt": "2026-11-05T15:30:00.000Z",
  "assignedUserId": "9e3b5d71-c2a8-4f60-8d14-7a6b2e9c0f53",
  "customerId": "c41f7b8a-2e6d-4a93-8b05-1d7e9f3c6a24"
}
```

### Campañas

#### `campaign.completed`

Terminó un envío masivo con plantilla. No trae id de campaña; algunos envíos traen sólo `template_name`, `total`, `sent` y `completed_at`.

```json
{
  "template_name": "promo_noviembre",
  "template_language": "es_MX",
  "total": 120,
  "sent": 114,
  "failed": 4,
  "held": 2,
  "cancelled": 0,
  "completed_at": "2026-10-30T19:00:12.000Z"
}
```

### Acciones del agente

#### `action.succeeded`

El agente ejecutó una herramienta con éxito. `action` es el nombre de la herramienta; `args` y `result` llegan sin datos personales.

```json
{
  "action": "scheduling_book",
  "status": "success",
  "chat_id": "6d2a9e14-8f3b-4c7a-b1e5-90c4d7f2a318",
  "company_id": "3c8e1a5f-7d92-4b04-a6e3-5f9c2d8b1e70",
  "invocation_id": "d5a9c3e7-1f84-4b26-9c30-6e2d8a4f7b15",
  "agent_version_id": "e2b7f9a1-4c63-4d58-8a19-0c5e3d7b2f84",
  "actor": {
    "kind": "agent",
    "id": "e2b7f9a1-4c63-4d58-8a19-0c5e3d7b2f84"
  },
  "args": {
    "date": "2026-11-04",
    "time": "10:00",
    "service": "Consulta inicial"
  },
  "result": {
    "success": true,
    "appointmentId": "a7c2e9f4-6b13-4d85-9e20-3f8b1c5d7a69"
  },
  "error": null,
  "duration_ms": 842,
  "occurred_at": "2026-10-30T16:05:02.114Z"
}
```

#### `action.failed`

Una herramienta del agente falló. `error` explica por qué.

```json
{
  "action": "scheduling_book",
  "status": "failure",
  "chat_id": "6d2a9e14-8f3b-4c7a-b1e5-90c4d7f2a318",
  "company_id": "3c8e1a5f-7d92-4b04-a6e3-5f9c2d8b1e70",
  "invocation_id": "d5a9c3e7-1f84-4b26-9c30-6e2d8a4f7b15",
  "agent_version_id": "e2b7f9a1-4c63-4d58-8a19-0c5e3d7b2f84",
  "actor": {
    "kind": "agent",
    "id": "e2b7f9a1-4c63-4d58-8a19-0c5e3d7b2f84"
  },
  "args": {
    "date": "2026-11-04",
    "time": "10:00",
    "service": "Consulta inicial"
  },
  "result": null,
  "error": {
    "message": "Slot no longer available"
  },
  "duration_ms": 611,
  "occurred_at": "2026-10-30T16:05:02.114Z"
}
```

#### `action.scheduling_book.succeeded`

El mismo cuerpo que `action.succeeded`, sólo para esta herramienta. Llega además del evento genérico.

```json
{
  "action": "scheduling_book",
  "status": "success",
  "chat_id": "6d2a9e14-8f3b-4c7a-b1e5-90c4d7f2a318",
  "company_id": "3c8e1a5f-7d92-4b04-a6e3-5f9c2d8b1e70",
  "invocation_id": "d5a9c3e7-1f84-4b26-9c30-6e2d8a4f7b15",
  "agent_version_id": "e2b7f9a1-4c63-4d58-8a19-0c5e3d7b2f84",
  "actor": {
    "kind": "agent",
    "id": "e2b7f9a1-4c63-4d58-8a19-0c5e3d7b2f84"
  },
  "args": {
    "date": "2026-11-04",
    "time": "10:00",
    "service": "Consulta inicial"
  },
  "result": {
    "success": true,
    "appointmentId": "a7c2e9f4-6b13-4d85-9e20-3f8b1c5d7a69"
  },
  "error": null,
  "duration_ms": 842,
  "occurred_at": "2026-10-30T16:05:02.114Z"
}
```

#### `action.scheduling_book.failed`

El mismo cuerpo que `action.failed`, sólo para esta herramienta. Llega además del evento genérico.

```json
{
  "action": "scheduling_book",
  "status": "failure",
  "chat_id": "6d2a9e14-8f3b-4c7a-b1e5-90c4d7f2a318",
  "company_id": "3c8e1a5f-7d92-4b04-a6e3-5f9c2d8b1e70",
  "invocation_id": "d5a9c3e7-1f84-4b26-9c30-6e2d8a4f7b15",
  "agent_version_id": "e2b7f9a1-4c63-4d58-8a19-0c5e3d7b2f84",
  "actor": {
    "kind": "agent",
    "id": "e2b7f9a1-4c63-4d58-8a19-0c5e3d7b2f84"
  },
  "args": {
    "date": "2026-11-04",
    "time": "10:00",
    "service": "Consulta inicial"
  },
  "result": null,
  "error": {
    "message": "Slot no longer available"
  },
  "duration_ms": 611,
  "occurred_at": "2026-10-30T16:05:02.114Z"
}
```

#### `action.scheduling_reschedule.succeeded`

El mismo cuerpo que `action.succeeded`, sólo para esta herramienta. Llega además del evento genérico.

```json
{
  "action": "scheduling_reschedule",
  "status": "success",
  "chat_id": "6d2a9e14-8f3b-4c7a-b1e5-90c4d7f2a318",
  "company_id": "3c8e1a5f-7d92-4b04-a6e3-5f9c2d8b1e70",
  "invocation_id": "d5a9c3e7-1f84-4b26-9c30-6e2d8a4f7b15",
  "agent_version_id": "e2b7f9a1-4c63-4d58-8a19-0c5e3d7b2f84",
  "actor": {
    "kind": "agent",
    "id": "e2b7f9a1-4c63-4d58-8a19-0c5e3d7b2f84"
  },
  "args": {
    "date": "2026-11-04",
    "time": "10:00",
    "service": "Consulta inicial"
  },
  "result": {
    "success": true,
    "appointmentId": "a7c2e9f4-6b13-4d85-9e20-3f8b1c5d7a69"
  },
  "error": null,
  "duration_ms": 842,
  "occurred_at": "2026-10-30T16:05:02.114Z"
}
```

#### `action.scheduling_reschedule.failed`

El mismo cuerpo que `action.failed`, sólo para esta herramienta. Llega además del evento genérico.

```json
{
  "action": "scheduling_reschedule",
  "status": "failure",
  "chat_id": "6d2a9e14-8f3b-4c7a-b1e5-90c4d7f2a318",
  "company_id": "3c8e1a5f-7d92-4b04-a6e3-5f9c2d8b1e70",
  "invocation_id": "d5a9c3e7-1f84-4b26-9c30-6e2d8a4f7b15",
  "agent_version_id": "e2b7f9a1-4c63-4d58-8a19-0c5e3d7b2f84",
  "actor": {
    "kind": "agent",
    "id": "e2b7f9a1-4c63-4d58-8a19-0c5e3d7b2f84"
  },
  "args": {
    "date": "2026-11-04",
    "time": "10:00",
    "service": "Consulta inicial"
  },
  "result": null,
  "error": {
    "message": "Slot no longer available"
  },
  "duration_ms": 611,
  "occurred_at": "2026-10-30T16:05:02.114Z"
}
```

#### `action.scheduling_cancel.succeeded`

El mismo cuerpo que `action.succeeded`, sólo para esta herramienta. Llega además del evento genérico.

```json
{
  "action": "scheduling_cancel",
  "status": "success",
  "chat_id": "6d2a9e14-8f3b-4c7a-b1e5-90c4d7f2a318",
  "company_id": "3c8e1a5f-7d92-4b04-a6e3-5f9c2d8b1e70",
  "invocation_id": "d5a9c3e7-1f84-4b26-9c30-6e2d8a4f7b15",
  "agent_version_id": "e2b7f9a1-4c63-4d58-8a19-0c5e3d7b2f84",
  "actor": {
    "kind": "agent",
    "id": "e2b7f9a1-4c63-4d58-8a19-0c5e3d7b2f84"
  },
  "args": {
    "date": "2026-11-04",
    "time": "10:00",
    "service": "Consulta inicial"
  },
  "result": {
    "success": true,
    "appointmentId": "a7c2e9f4-6b13-4d85-9e20-3f8b1c5d7a69"
  },
  "error": null,
  "duration_ms": 842,
  "occurred_at": "2026-10-30T16:05:02.114Z"
}
```

#### `action.scheduling_cancel.failed`

El mismo cuerpo que `action.failed`, sólo para esta herramienta. Llega además del evento genérico.

```json
{
  "action": "scheduling_cancel",
  "status": "failure",
  "chat_id": "6d2a9e14-8f3b-4c7a-b1e5-90c4d7f2a318",
  "company_id": "3c8e1a5f-7d92-4b04-a6e3-5f9c2d8b1e70",
  "invocation_id": "d5a9c3e7-1f84-4b26-9c30-6e2d8a4f7b15",
  "agent_version_id": "e2b7f9a1-4c63-4d58-8a19-0c5e3d7b2f84",
  "actor": {
    "kind": "agent",
    "id": "e2b7f9a1-4c63-4d58-8a19-0c5e3d7b2f84"
  },
  "args": {
    "date": "2026-11-04",
    "time": "10:00",
    "service": "Consulta inicial"
  },
  "result": null,
  "error": {
    "message": "Slot no longer available"
  },
  "duration_ms": 611,
  "occurred_at": "2026-10-30T16:05:02.114Z"
}
```
