Envío de un mensaje con Failover

Al enviar mensajes con la API de Messages API de Vonage, es posible que sean rechazados. En una sola solicitud de API, se pueden definir mensajes de conmutación por error para que se envíen en su lugar. Por ejemplo, si el dispositivo de un cliente no admite tu canal principal, como RCS, seguirá recibiendo tus mensajes a través de canales alternativos.

Esta guía le explica cómo configurar la conmutación por error de mensajes en su solicitud y cómo supervisar el estado de la entrega mediante retrollamadas.

Envío de una solicitud con conmutación por error de mensajes

En este ejemplo, se envía primero un mensaje de texto RCS, seguido de un mensaje SMS si ese mensaje falla. La estructura de la solicitud es la misma que la del envío de un mensaje estándar para el canal primario; a continuación, el mensaje de conmutación por error se define en un campo failover de la siguiente manera:

{
  "to": "447700900000",
  "from": "Vonage",
  "channel": "rcs",
  "message_type": "image",
  "image": {
    "url": "https://example.com/image.jpg",
    "caption": "This is an image sent via RCS using the Vonage Messages API."
  },
  "failover": [
    {
      "to": "447700900000",
      "from": "447700900001",
      "channel": "sms",
      "message_type": "text",
      "text": "This is an SMS sent using the Vonage Messages API."
    }
  ]
}

Puede definir tantos canales de conmutación por error como necesite; los mensajes de conmutación por error se enviarán en el orden en que estén definidos en la matriz.

Cada mensaje dentro de la matriz de conmutación por error requiere su propio channel, message_type from, toy el contenido del mensaje; puede encontrar más información sobre cada canal y sus parámetros necesarios en la sección Especificación API. También debe asegurarse de que el contenido del mensaje se adapta a las capacidades de cada canal alternativo.

Encontrará ejemplos de solicitudes con cURL y los SDK de Vonage en la página Enviar un mensaje con Failover página de fragmentos de código.

Supervisión del estado y devoluciones de llamada

Cuando se envía el mensaje, la API devuelve devoluciones de llamada de estado a la URL de su webhook. Estos rastrean el progreso y el resultado de cada mensaje en la secuencia de conmutación por error. Un ejemplo de flujo para RCS fallando a SMS sería:

  1. RCS Presentado → Mensaje enviado al canal primario (en este caso RCS).
  2. RCS Rechazado → Error en la entrega del mensaje.
  3. Envío de SMS → Mensaje de conmutación por error enviado por SMS.
  4. SMS entregados → Mensaje entregado con éxito.

Ejemplo de devolución de llamada

Los siguientes ejemplos de devolución de llamada muestran actualizaciones de estado para un mensaje RCS rechazado y un mensaje SMS entregado. En ambas retrollamadas, verá estos campos:

  • workflow.workflow_id - ID único para el flujo de trabajo de conmutación por error.
  • workflow.items_number - Indica la secuencia de los mensajes enviados (por ejemplo, "1" para el primario, "2" para la primera conmutación por error).
  • workflow.items_total - Número total de mensajes intentados en este flujo de trabajo.
  • status - Indica el estado de la entrega. Estos valores variarán en función del canal, pero serán uno de los siguientes submitted, delivered, rejected, undeliverableo read. Encontrará información específica sobre cada canal en la sección Especificación API.

RCS Rechazado

{
  "messageuuid": "001",
  "to": "447700900000",
  "from": "Vonage",
  "timestamp": "2024-01-01T14:00:02.000Z",
  "status": "rejected",
  "channel": "rcs",
  "workflow": {
    "workflow_id": "3TcNjguHxr2vcCZ9Ddsnq6tw8yQUpZ9rMHv9QXSxLan5ibMxqSzLdx9",
    "items_number": "1",
    "items_total": "2"
  }
}

SMS entregados

{
  "messageuuid": "002",
  "to": "447700900000",
  "from": "447700900001",
  "timestamp": "2024-01-01T14:00:04.000Z",
  "status": "delivered",
  "channel": "sms",
  "workflow": {
    "workflow_id": "3TcNjguHxr2vcCZ9Ddsnq6tw8yQUpZ9rMHv9QXSxLan5ibMxqSzLdx9",
    "items_number": "2",
    "items_total": "2"
  }
}

Utilice estas retrollamadas para realizar un seguimiento de dónde y cómo se entregan los mensajes, y para activar las siguientes acciones o registros.

Lecturas complementarias