WABA API

Recibir mensajes y estados

Recibe en tu servidor los mensajes que llegan a tus líneas de WhatsApp Business API, descarga sus archivos y sigue la entrega de lo que envías.

Whapi te avisa por webhook de dos cosas que pasan en tus líneas de WhatsApp Business API:

Evento	Cuándo llega
`waba.message.received`	Un cliente escribió: texto, respuesta a un botón o lista, archivo o ubicación.
`waba.message.status`	Cambió el estado de un mensaje que enviaste con la API: `sent`, `delivered`, `read` o `failed`.

Para recibirlos, crea un webhook para cada evento en Whapi. Cómo configurarlo y verificar la firma: Configurar webhooks.

Flujo típico desde un CRM

Configura una vez: guarda la URL base, tu clave de API y el wabaPhoneNumberId de tu línea.
Prepara las plantillas: créalas con POST /templates y espera a que Meta las apruebe. Ver Plantillas.
Envía: un POST /messages/send por destinatario, con las variables de cada persona.
Escucha: guarda el wamid de cada envío y actualiza su estado con waba.message.status. Las respuestas de los clientes llegan por waba.message.received.

Mensajes recibidos

{
  "apiVersion": "2026-06-15",
  "id": "3b241101-e2bb-4255-8caf-4136c566a962",
  "type": "waba.message.received",
  "createdAt": "2026-10-14T15:04:05.000Z",
  "data": {
    "wabaPhoneNumberId": 3,
    "from": "51987654321",
    "contactName": "Ana Pérez",
    "messageId": "wamid.HBgLNTE5ODc2NTQzMjEVAgASGBQzQUYxRjQ",
    "type": "text",
    "text": "Hola, quiero una factura por 2 cajas",
    "reply": null,
    "location": null,
    "media": null,
    "context": null,
    "ticketId": 42,
    "contactId": 18
  }
}

El ejemplo omite algunos campos. Los más útiles según type:

`type`	Dónde está el contenido
`text`	`text`
`image`, `video`, `audio`, `document`, `sticker`	`media` (id, tipo, nombre, tamaño); el pie del archivo en `text`
`button`, `interactive`	`reply`: qué botón u opción de lista eligió el cliente
`location`	`location`: latitud, longitud, nombre y dirección

Si el cliente respondió citando un mensaje, context.replyToMessageId trae el id del mensaje citado.

Descargar un archivo recibido

Cuando el mensaje trae un archivo, descárgalo con su media.id:

curl https://api.whapi.chat/waba-api/media/1234567890123456 \
  --header 'Authorization: Bearer TU_CLAVE' \
  --output archivo

La respuesta es el archivo con su tipo original. El header Content-Disposition trae el nombre original, y X-Whapi-Media-Sha256 el hash para verificarlo.

Solo se descargan archivos que llegaron a tus líneas.
Meta los conserva unos 30 días; después la respuesta es 404 con code: waba_media_expired. Si los necesitas, descárgalos al recibir el webhook.
Tamaño máximo: 100 MB.

Estados de lo que envías

{
  "type": "waba.message.status",
  "data": {
    "wabaPhoneNumberId": 3,
    "messageId": "wamid.HBgMNTE5ODc2NTQzMjEVAgASGBQzQUYxRjQ",
    "status": "delivered",
    "timestamp": 1760454249,
    "recipient": "51987654321",
    "ticketId": 42,
    "errors": null
  }
}

Relaciona cada estado con tu envío por messageId, que es el wamid de la respuesta de POST /messages/send. Los estados pueden llegar desordenados: read puede llegar antes que delivered. Quédate con el más avanzado.

Si status es failed, errors trae el código y la descripción de Meta.

Este evento solo cubre mensajes enviados con la API. Los que envían tus agentes desde Whapi no lo generan.

Payloads completos: webhooks en la referencia.