Webhooks — Eventos de contacto

Cuatro eventos comparten el mismo payload: el contacto completo.

Evento	Cuándo se dispara
`create_contact`	Se crea un contacto — desde la plataforma, la API, una importación o al recibir el primer mensaje de alguien nuevo
`update_contact`	Se modifica un contacto: datos, etiquetas, campos personalizados, agente asignado
`delete_contact`	Se borra un contacto
`status_bot_contact`	Se activa o desactiva el chatbot para ese contacto

⚠️ Ojo con el filtro por línea, que no es igual para los cuatro:

Evento	Filtro
`create_contact`, `update_contact`, `delete_contact`	No se filtran. Aplican a toda la cuenta
`status_bot_contact`	Sí se filtra por línea. Si no marcó ningún número al configurarlo, no va a recibir nada

Campos

Campo	Tipo	Notas
`id`	int	Id interno del contacto
`user_id`	int	Cuenta dueña del contacto
`uuid`	string	Identificador estable. Úselo como llave primaria
`first_name`	string \| null
`last_name`	string \| null
`email`	string \| null
`country_code`	string \| null	ISO alpha-2 en minúscula (`co`, `ar`, `mx`)
`phone`	string \| null	Solo dígitos, sin `+`. `null` si el contacto oculta su número
`bsuid`	string \| null	Ver Identidad del contacto
`wa_username`	string \| null	Username público de WhatsApp
`notes`	string \| null
`blocked`	bool \| null	`null` únicamente en `delete_contact`
`unsubscribed`	bool	El contacto pidió no recibir más mensajes
`created_at`	string
`updated_at`	string
`possible_invalid`	bool \| null	⚠️ Ver la advertencia abajo
`labels`	array	Etiquetas. Siempre presente; `[]` si no tiene
`custom_fields`	array	Campos personalizados. Siempre presente; `[]` si no tiene
`version`	int	`1`

status_bot_contact agrega además bot_disabled, permanent y from_id.

⚠️
No construya lógica sobre possible_invalid. Es una bandera heurística interna sobre si el teléfono parece inválido. No refleja ninguna verificación real contra Meta y es candidata a desaparecer en una v2.

`labels`

"labels": [
  {
    "id": 812,
    "user_id": 1234,
    "title": "Cliente frecuente",
    "description": null,
    "color": "#4CAF50",
    "created_at": "2026-03-11T14:22:05.000000Z",
    "updated_at": "2026-03-11T14:22:05.000000Z",
    "pivot": { "contact_id": 987654, "label_id": 812 }
  }
]

`custom_fields`

"custom_fields": [
  {
    "id": 5001,
    "contact_id": 987654,
    "contacts_custom_field_id": 47,
    "field_value": "alta",
    "field_name": "intencion_compra"
  }
]

Cada elemento trae el nombre del campo (field_name) además de su id, así que no hace
falta cruzar contra otra tabla.

Ejemplo completo — `create_contact`

{
  "event": "create_contact",
  "data": {
    "id": 987654,
    "user_id": 1234,
    "uuid": "9f8c1e3a-4b21-4d77-9a10-2c5e6f0b1d34",
    "first_name": "Ana",
    "last_name": "Gómez",
    "email": null,
    "country_code": "co",
    "phone": "573001234567",
    "bsuid": null,
    "wa_username": null,
    "notes": null,
    "blocked": false,
    "unsubscribed": false,
    "created_at": "2026-08-07T15:04:11.000000Z",
    "updated_at": "2026-08-07T15:04:11.000000Z",
    "possible_invalid": false,
    "labels": [],
    "custom_fields": [],
    "version": 1
  }
}

Ejemplo — `status_bot_contact`

{
  "event": "status_bot_contact",
  "data": {
    "id": 987654,
    "uuid": "9f8c1e3a-4b21-4d77-9a10-2c5e6f0b1d34",
    "phone": "573001234567",
    "bsuid": null,
    "wa_username": null,
    "bot_disabled": true,
    "permanent": false,
    "from_id": 42,
    "labels": [],
    "custom_fields": [],
    "version": 1
  }
}

bot_disabled: true significa que el bot quedó apagado para ese contacto.
permanent: false indica que es un bloqueo temporal (por ejemplo, porque lo atendió un
agente); true, que se desactivó de forma indefinida.

Notas de comportamiento

El payload es siempre el contacto completo

Los cuatro eventos mandan la misma forma, con todos los campos de la tabla y las dos
relaciones. No depende de qué haya hecho el usuario: un update_contact disparado al
cambiar solo una etiqueta trae igual el contacto entero.

`delete_contact` en borrados masivos

Un borrado de muchos contactos dispara un evento por contacto, no uno agregado. Si borra
5.000 contactos, su endpoint va a recibir 5.000 llamadas. Téngalo en cuenta al dimensionar.

El payload se captura antes de borrar, así que trae los datos completos del contacto que
dejó de existir, incluidas etiquetas y campos personalizados. blocked llega en null
porque ya no se puede releer.

`create_contact` no siempre es una alta manual

Se dispara también cuando alguien le escribe por primera vez y Wasapi crea la ficha
automáticamente. Es el caso más frecuente.

Ver también

Identidad del contacto — qué hacer cuando phone es null

Campos

labels

custom_fields

Ejemplo completo — create_contact

Ejemplo — status_bot_contact

Notas de comportamiento

El payload es siempre el contacto completo

delete_contact en borrados masivos

create_contact no siempre es una alta manual

Ver también

`labels`

`custom_fields`

Ejemplo completo — `create_contact`

Ejemplo — `status_bot_contact`

`delete_contact` en borrados masivos

`create_contact` no siempre es una alta manual