Llamadas de estado de la API de Messages

La Messages API envía llamadas de retorno 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, RCS, y 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 las devoluciones de llamada

Llamadas de estado de lectura

Para los canales OTT como WhatsApp y Viber, la Messages API puede enviar un read llamada de retorno cuando el proveedor indique 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 retorno de estado rechazadas

Un mensaje puede ser rechazado por varias razones:

• La Messages API no puede procesar el mensaje (por ejemplo, parámetros no válidos o archivos multimedia no compatibles).
• El proveedor rechaza el mensaje; por ejemplo, al enviar un MMS a un país en el que no se admite este servicio.
• 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.

Ejemplos de funciones de devolución de llamada

SMS (mensaje de varias partes)

{
  "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 conmutación por error a 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

The Messages API includes a 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.