Webhooks de estado de WhatsApp: sent, delivered, read y failed
Los webhooks de estado informan de lo que pasó con un mensaje que una empresa envió a través de la Cloud API de WhatsApp. Llegan por el campo messages, con un array statuses en lugar de un array messages: sent (un check), delivered (dos checks), read (dos checks azules), played en mensajes de voz y failed con un array errors. Cruza statuses[].id con el wamid que devolvió tu petición de envío.
easyCoexistence conecta el número de la app de WhatsApp Business que ya usas con la Cloud API de Meta mediante Coexistencia.
Valores de estado que envía Meta: sent, delivered, read, played (primera reproducción de mensajes de voz) y failed.
Webhooks de estado distintos que puede generar un mensaje saliente: sent, delivered y read.
Desde esta versión de la Graph API se omite el objeto conversation, salvo en mensajes dentro de una ventana de punto de entrada gratuito.
APIs para obtener datos pasados de webhooks; Meta pide capturar y guardar los payloads a medida que llegan.
La cabecera X-EC-Event en un estado reenviado: los estados viajan dentro de eventos messages, bajo value.statuses.
¿Por dónde llegan los webhooks de estado de WhatsApp?
Por el mismo campo messages que transporta lo que envían los clientes, dentro del mismo envoltorio object, entry y changes. La diferencia está dentro de value: un mensaje entrante tiene un array messages y un estado tiene un array statuses. Un handler que solo lee value.messages descarta todos los estados sin dar ningún error. metadata.phone_number_id indica cuál de tus números envió el mensaje, y se incluye un array contacts con el nombre de perfil del cliente, su wa_id y su BSUID, salvo en los estados failed y en el estado sent de los mensajes de grupo. Este es el ejemplo de Meta de una plantilla de marketing que salió de los servidores de Meta:
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "102290129340398",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "15550783881",
"phone_number_id": "106540352242922"
},
"contacts": [
{
"profile": {
"name": "Pablo M."
},
"wa_id": "16505551234",
"user_id": "US.13491208655302741918"
}
],
"statuses": [
{
"id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=",
"status": "sent",
"timestamp": "1750030073",
"recipient_id": "16505551234",
"recipient_user_id": "US.13491208655302741918",
"conversation": {
"id": "72b14d6bd5407799e66f64d1b338e567",
"expiration_timestamp": "1750116480",
"origin": {
"type": "marketing"
}
},
"pricing": {
"billable": true,
"pricing_model": "PMP",
"type": "regular",
"category": "marketing"
}
}
]
},
"field": "messages"
}
]
}
]
}¿Qué significa cada valor de estado?
Cada valor corresponde a una marca que el cliente vería en WhatsApp. Un estado solo cuenta como read después de haber sido delivered, y cuando un cliente recibe un mensaje con el chat ya abierto, Meta envía read sin un webhook delivered previo, como optimización interna. Por eso un sistema de seguimiento debe aceptar read aunque delivered nunca haya llegado, y debe ordenar los estados por rango en lugar de esperarlos uno a uno en una secuencia fija.
¿Qué campos tiene un objeto de estado?
Menos que un mensaje, y varios son condicionales. La referencia de Meta indica cuándo está presente cada uno:
- id: el wamid del mensaje que enviaste, la clave para cruzarlos.
- status y timestamp: el valor y la hora Unix en que se disparó el webhook, como string.
recipient_id: el número de teléfono o el id del grupo; se omite cuando enviaste a un BSUID y el número no está disponible.recipient_user_id: el BSUID del cliente; se omite en un estado failed cuando enviaste a un número de teléfono.recipient_typeyrecipient_participant_id: solo en mensajes enviados a un grupo.biz_opaque_callback_data: solo si lo configuraste en la petición de envío.- pricing: solo en sent y en uno de delivered o read. errors: solo en failed.
¿Cómo se cruza un estado con el mensaje que enviaste?
Por el wamid. La petición de envío responde con messages[0].id, y cada estado de ese mensaje lleva el mismo valor en statuses[].id. Guárdalo junto a tu propio registro al enviar y actualiza ese registro cuando lleguen los estados, conservando el estado más alto alcanzado, para que un delivered tardío no sobrescriba un read. Un estado con un wamid que no conoces corresponde a algo que envió otro sistema desde el número, como una automatización, y puedes ignorarlo o registrarlo.
// statuses.mjs: apply Meta status webhooks to the messages your system sent
const RANK = { sent: 1, delivered: 2, read: 3, played: 4 };
// value: change.value of a "messages" webhook; sends: Map of wamid -> your record
export function applyStatuses(value, sends) {
for (const s of value.statuses ?? []) {
const rec = sends.get(s.id); // the wamid your send request returned
if (!rec) continue; // sent by something else, such as an automation
if (s.status === "failed") {
rec.status = "failed";
rec.error = s.errors?.[0]?.code; // for example 131049, 131050 or 131026
} else if ((RANK[s.status] ?? 0) > (RANK[rec.status] ?? 0)) {
rec.status = s.status; // read arriving before delivered is fine; never step back
}
rec.updatedAt = Math.max(rec.updatedAt ?? 0, Number(s.timestamp));
}
}¿Qué cambia en un número con Coexistencia?
Los estados describen lo enviado a través de la API: respuestas de tus automatizaciones, mensajes que tu IA envió mediante un conector MCP y todo lo que envió tu propio código. Lo que el dueño escribe en la app de WhatsApp Business llega al software de otra forma, como smb_message_echoes, que Meta documenta como el reflejo de los mensajes enviados desde la app. Los mensajes que llegaron con la importación única del historial traen su propio estado dentro del webhook de historial, con valores como delivered, read, played, pending y error.
Los estados van a donde vaya el campo messages del número. Con un destino directo, Meta los envía directamente a tu endpoint, porque messages es un campo que Meta permite sobrescribir con un destino. Con las automatizaciones activadas y una Forward URL configurada, llegan a esa URL como eventos messages.
¿Cómo sabe tu IA o tu automatización si un mensaje se entregó?
A través de tu destino, no del envío. Cuando un asistente llama a send_template o send_message, el resultado de la herramienta trae el wamid e indica que Meta aceptó el mensaje; la entrega se confirma después, en el dispositivo del cliente, y se informa como un estado. easyCoexistence no guarda un historial de estados que se pueda consultar y ninguna herramienta MCP lee estados, así que un agente que necesite confirmación de entrega debe enviar a través de tu sistema o leer los estados que recibe tu Forward URL.
Lo mismo ocurre con las automatizaciones: una ejecución en la pestaña Runs muestra el paso de respuesta como completado en cuanto Meta acepta el mensaje, y un fallo informado después solo aparece como un estado failed en tu destino.
Errores comunes
- Buscar un campo statuses aparte. Los estados llegan en messages, así que un handler que solo lee value.messages los pierde sin dar ningún error.
- Exigir delivered antes de read. Meta omite el webhook delivered cuando el mensaje se lee en el mismo momento en que llega.
- Tomar la respuesta de envío como entrega. Un wamid significa que Meta aceptó la petición; un fallo puede llegar minutos después como un estado failed.
- Identificar a los clientes solo por recipient_id. Se omite cuando enviaste a un BSUID y el número de teléfono no está disponible; recipient_user_id lleva el BSUID.
Los estados de lo que envían tus automatizaciones, tu IA o tu código llegan a tu servidor: directamente desde Meta en modo directo, o reenviados a tu Forward URL y firmados con X-EC-Signature cuando las automatizaciones están activadas, y no se guardan por defecto. De US$ 9 a US$ 0.75 por número al mes, un precio que baja a medida que sumas números, con los primeros 3 días gratis.
Preguntas frecuentes
¿Los webhooks de estado incluyen el texto del mensaje?
No. Un estado trae el wamid, el status, el destinatario, las marcas de tiempo y, cuando corresponde, pricing y errors. Si necesitas mostrar lo que enviaste junto a su estado, guarda tu propia copia indexada por el wamid.
¿Puedo recuperar de Meta los estados pasados más adelante?
No. La guía de webhooks de Meta indica que no hay APIs para obtener datos históricos de webhooks, así que un estado que tu endpoint no capturó se pierde cuando Meta deja de reintentar, tras un máximo de 7 días.
¿Para qué sirve biz_opaque_callback_data?
Es una cadena que defines al enviar, como el id de tu pedido o de tu ticket. Meta la devuelve en los statuses de ese mensaje, para que puedas cruzar un estado con tu registro sin tener que buscar antes el wamid.
¿Tengo que responder a los webhooks de estado con un 200?
Sí, como en cualquier POST de webhook. Meta trata cualquier otra respuesta como una entrega fallida y la reintenta, y esa es una de las razones por las que el mismo estado puede llegarte dos veces.
Sigue leyendo
¿Listo para empezar?
Configura WhatsApp Coexistence en minutos, no en meses. La app sigue funcionando en el teléfono.
Empezar prueba gratisVerificado el