Llamadas de estado de la API de Messages

La API Messages envía devoluciones de llamada de estado a la URL de tu webhook para informarte cada vez que un evento cambie el estado de un mensaje, por ejemplo, cuando se envíe, se entregue o se rechace.

Estas retrollamadas proporcionan una visibilidad coherente del ciclo de vida de los mensajes en todos los canales admitidos, incluyendo SMS, MMS, RCSy aplicaciones: WhatsApp, Vibery Facebook Messenger.

Cada vez que cambia el estado de un mensaje, Messages API envía una devolución de llamada de estado al webhook configurado.
Esta llamada de retorno incluye información clave como el UUID del mensaje, el canal, la marca de tiempo, el estado de la entrega y, en su caso, los metadatos de precio y red.

Los distintos canales admiten eventos y niveles de información diferentes. Por ejemplo:

Estados de devolución de llamada

Llamadas de estado de lectura

Para los canales OTT como WhatsApp y Viber, la Messages API puede enviar un read cuando el proveedor indica que el usuario final ha leído el mensaje en su dispositivo.

Devoluciones de llamada de estado enviadas

Este estado significa que Messages API ha pasado un mensaje a un proveedor de mensajería.

Devoluciones de estado no entregadas

Este estado significa que Messages API no ha podido conectarse al proveedor de mensajería. Esto puede deberse a una interrupción del proveedor de mensajería u otro incidente.

Llamadas de Estado Rechazadas

Un mensaje puede ser rechazado por varias razones:

• Messages API no puede procesar el mensaje (por ejemplo, parámetros no válidos o medios no compatibles).
• El proveedor rechaza el mensaje, por ejemplo, al enviar MMS a un país no admitido.
• El tiempo de vida (TTL) del mensaje expira antes de que pueda ser entregado.

En estos casos, un rejected con un objeto de error que describe el fallo.

Ejemplo de devolución de llamada

SMS (mensaje multiparte)

{
  "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "to": "447700900000",
  "from": "447700900001",
  "timestamp": "2023-05-01T14:00:00.000Z",
  "status": "submitted",
  "usage": {
    "currency": "EUR",
    "price": "0.0333"
  },
  "client_ref": "string",
  "channel": "sms",
  "destination": {
    "network_code": "12345"
  },
  "sms": {
    "total_count": "2"
  }
}

RCS (Solicitud rechazada con fallo de SMS)

{
  "message_uuid": "001",
  "to": "447700900000",
  "from": "447700900001",
  "timestamp": "2024-01-01T14:00:00.000Z",
  "status": "rejected",
  "channel": "rcs",
  "destination": {
    "network_code": "12345"
  },
  "error": {
    "type": "https://developer.vonage.com/api-errors/messages#1260",
    "title": 1260,
    "detail": "Destination unreachable - The message could not be delivered to the phone number.",
    "instance": "abc102"
  },
  "workflow": {
    "id": "1001",
    "item_number": "1",
    "items_total": "2"
  }
}

Códigos de red

La API de Messages incluye una función network_code en las devoluciones de llamada para identificar al operador que gestiona el mensaje. Los códigos de red son combinaciones de códigos de país móvil (MCC) y códigos de red móvil (MNC) y se aplican a SMS, RCS y MMS, y representan los datos más precisos disponibles en el momento del evento de devolución de llamada de estado.