Estados de mensajes WhatsApp API: sent, delivered, read

No diseñes un GET /message-status imaginario. En Cloud API el patrón documentado es asíncrono: el POST de envío devuelve un wamid y los cambios posteriores llegan mediante webhooks del campo messages.

Estados que normalmente debes modelar

sent

Meta ha aceptado/procesado el mensaje en una etapa de envío. No implica entrega al dispositivo.

delivered

El evento indica entrega al destinatario en el flujo reportado por WhatsApp.

read

El mensaje fue marcado como leído cuando el ecosistema y privacidad permiten reportarlo.

failed

La entrega falló; conserva la información de error disponible para diagnóstico.

Ejemplo mínimo de payload de estados

{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "{WABA_ID}",
    "changes": [{
      "field": "messages",
      "value": {
        "metadata": {"phone_number_id": "{PHONE_NUMBER_ID}"},
        "statuses": [{
          "id": "wamid....",
          "status": "delivered",
          "timestamp": "...",
          "recipient_id": "..."
        }]
      }
    }]
  }]
}

El payload real puede incluir campos adicionales como conversación, pricing o errores. Normaliza solo lo que tu dominio necesita y conserva el evento original de forma controlada si es necesario para auditoría técnica.

No sobrescribas la historia

Una sola columna status es útil para el estado más reciente, pero conserva también una tabla de eventos. Así puedes saber cuándo se envió, cuándo se entregó, cuánto tardó y por qué falló. Si recibes eventos fuera de orden, utiliza el timestamp y reglas de precedencia para no retroceder accidentalmente de read a sent.

Modelo recomendado

messages(id, internal_id, wamid, to, type, current_status, created_at)
message_status_events(id, message_id, status, occurred_at, error_code, raw_event_key)

UNIQUE(messages.wamid)
UNIQUE(message_status_events.raw_event_key)

Métricas útiles

Delivery rate por campaña/plantilla.
Tiempo sent → delivered.
Read rate cuando sea relevante y disponible.
Errores por código/categoría.
Deterioro súbito por país, número o plantilla.

¿Tu empresa no necesita desarrollar esto?

Optimify ya integra la capa empresarial sobre WhatsApp API

Esta sección existe para equipos que realmente quieren construir o integrar. Si la empresa solo necesita CRM, multiagente, campañas, automatización e IA, MensajAPI recomienda comparar el costo de desarrollo y mantenimiento frente a usar Optimify, que ofrece una plataforma lista y soporte en español.

Ver alternativa gestionada con Optimify

Documentación oficial para mantener la integración actualizada

Versionado: los ejemplos usan {VERSION} en lugar de fijar una versión de Graph API. Sustituye esa variable por una versión vigente y soportada en tu aplicación y revisa cambios antes de actualizar producción.

Estados de mensajes en WhatsApp API: no uses polling, procesa webhooks