Presentación de la conmutación por error de mensajes en Messages API de Vonage

La conmutación por error de mensajes ya está disponible en la Mensajes API de Vonage. Antes de analizar qué es la conmutación por error y cómo usarla, hagamos una breve descripción de la Messages API para quienes no estén familiarizados con ella.

Descripción de la API de Messages

Messages API es una API de mensajería multicanal que permite a las empresas enviar y recibir varios tipos de mensajes a través de múltiples canales de mensajería, incluyendo SMS, MMS, RCS, WhatsApp, etc.

La estructura JSON exacta de la carga útil de la solicitud API varía en función del canal y/o del tipo de mensaje, pero todos los mensajes siguen los mismos principios básicos. El JSON de todos los mensajes tendría propiedades para a, de, canaly tipo_mensajeasí como una propiedad para el propio mensaje, que variará en función del tipo de mensaje. También hay propiedades opcionales adicionales, algunas de las cuales se refieren a características específicas soportadas por un determinado canal o tipo de mensaje.

Por ejemplo, ésta sería la estructura JSON para enviar un mensaje básico de texto básico a través de sms :

{
   "to": "447700900001",
   "from": "Vonage",
   "channel": "sms",
   "message_type": "text",
   "text": "Hello from Vonage!"
}

Una imagen imagen básico enviado a través de rcs utilizaría una estructura JSON similar a ésta:

{
   "to": "447700900001",
   "from": "Vonage-RCS-Agent",
   "channel": "rcs",
   "message_type": "image",
   "image": {
     "url": "https://example.com/image.jpg"
    }
}

La respuesta a la solicitud API contendrá un cuerpo de respuesta con un mensaje_uuid que identifica de manera única el objeto de mensaje en los servidores de Vonage. Este UUID puede utilizarse para rastrear el estado del mensaje.

{
  "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab"
}

Estado del mensaje

Una vez realizada la solicitud inicial de la API, el objeto de mensaje progresará a través de varios estadoscomo enviado y entregadomientras la API de Messages intenta entregarlo al destinatario especificado a través de la red descendente del canal requerido.

Un cambio de estado provocará el envío de una petición HTTP al endpoint punto final de webhook de estado definido en la configuración de tu aplicación de Vonage. El cuerpo de la solicitud tendrá una carga útil JSON estructurada de esta manera (aunque puede haber propiedades adicionales según el canal y el estado):

{
   "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
   "to": "447700900000",
   "from": "Vonage",
   "channel": "sms",
   "timestamp": "2025-02-03T12:14:25Z",
   "status": "delivered"
}

Los estados específicos pueden variar ligeramente en función del canal. Por ejemplo, canales como RCS y WhatsApp tienen un estado leído que indica que el destinatario ha leído el mensaje entregado, mientras que los mensajes SMS y MMS no tienen la capacidad de proporcionar un estado de lectura. leer de lectura.

Un estado de mensaje que todos los canales tienen en común es el de rechazado rechazado. Dependiendo del canal y/o del tipo de mensaje, puede haber varias razones por las que un mensaje haya sido rechazado. En cualquier caso, un mensaje rechazado significa que el mensaje no será entregado al destinatario.

Qué es la conmutación por error de mensajes

Antes de que se implementara la conmutación por error en la API de mensajes de Vonage, si querías crear cierta capacidad de recuperación en tu aplicación de mensajería a fin de lidiar con situaciones en las que los mensajes eran rechazados, habrías tenido que implementar la lógica comercial para esto tú mismo. Por ejemplo, podrías orquestar un sistema para rastrear el estado de una solicitud de mensaje individual mediante los mensajes de webhook de estado de mensaje con el parámetro mensaje_uuid devuelto en el HTTP inicial, y si un mensaje rechazado para un objeto de mensaje, solicitar el envío de un mensaje alternativo.

Con la función de conmutación por error, este tipo de lógica puede incorporarse a la propia solicitud de mensaje inicial. Averigüemos cómo.

Uso de la conmutación por error en la Messages API

Para utilizar failover en la Messages API es necesario incluir una propiedad failover adicional en la carga JSON que define el mensaje. El valor de esta propiedad es un array que contiene uno o más objetos de mensaje.

{
   "to": "447700900001",
   "from": "Vonage",
   "channel": "sms",
   "message_type": "text",
   "text": "Hello from Vonage!",
   "failover": [
     // message objects
   ]
}

Si se rechaza el mensaje inicial, la Messages API enviará automáticamente el primer objeto de mensaje de la carpeta conmutación por error de conmutación por error. Si ese mensaje también es rechazado, entonces se enviará el segundo objeto (si hay uno definido), y así sucesivamente.

Cuando se incluye el conmutación por error en la solicitud de API, un mensaje_uuid se recibe en la respuesta HTTP como de costumbre, pero una propiedad adicional workflow_id también se incluye:

{
   "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
   "workflow_id": "3TcNjguHxr2vcCZ9Ddsnq6tw8yQUpZ9rMHv9QXSxLan5ibMxqSzLdx9"
}

Al recibir solicitudes de webhook de estado de mensaje para objetos de mensaje que se enviaron con una conmutación por error la carga útil JSON incluirá una propiedad flujo de trabajo con la propiedad workflow_id cuyo valor coincidirá con la propiedad workflow_id recibido en la respuesta a la solicitud inicial de la API. En este contexto, un "flujo de trabajo" representa la serie de mensajes: el mensaje inicial y el mensaje o mensajes de conmutación por error definidos.

Además, el flujo de trabajo contendrá un número_de_artículos y una propiedad total_artículos y una propiedad La propiedad número_artículos indica a qué "ítem" o mensaje dentro del flujo de trabajo global se refiere esta solicitud de Estado de Mensaje. En número_artículo de 1 indica el mensaje inicial, y número_artículos de 2 indica el primer objeto de mensaje en conmutación por error y así sucesivamente. La dirección items_total indica el número total de "elementos" o mensajes en el flujo de trabajo global; por ejemplo, una propiedad items_total de 3 indicaría un mensaje inicial con dos mensajes definidos en el flujo de trabajo de conmutación por error de conmutación por error.

{
   "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
   "to": "447700900001",
   "from": "Vonage",
   "channel": "sms",
   "timestamp": "2025-02-03T12:14:25Z",
   "status": "delivered",
   "workflow": {
      "workflow_id": "3TcNjguHxr2vcCZ9Ddsnq6tw8yQUpZ9rMHv9QXSxLan5ibMxqSzLdx9",
      "items_number": "1",
      "items_total": "2"
   }
}

La API Messages enviará solicitudes de Estado de Mensaje según sea necesario para cada mensaje en un flujo de trabajo. Así, por ejemplo, podría recibir una solicitud de estado de rechazado para número_artículos 1, y luego un estado de entregado (con el mismo mensaje_uuid y workflow_id) para items_number 2. Si, por el contrario número_artículos 1 fue entregado entonces el flujo de trabajo estaría completo y cualquier mensaje posterior en el flujo de trabajo no desencadenaría solicitudes de Estado de Mensaje.

Cuándo utilizar la conmutación por error

Ahora que hemos cubierto qué es conmutación por error y cómo y cómo utilizarla, veamos un par de formas en las que se puede utilizar.

Conmutación por error entre canales

Puedes aprovechar la capacidad multicanal de Messages API de Vonage al intentar enviar un mensaje a un canal y, si el mensaje inicial es rechazado, pasar a otro canal.

Un caso de uso común sería pasar de RCS a SMS. Aunque RCS está ampliamente soportado ahora (mensajería RCS es compatible con iOS desde v18), todavía no está tan extendida en términos de soporte de dispositivos y la cobertura de red como SMS. Además, algunos dispositivos requieren que habilites la mensajería RCS en el dispositivo (es decir, no está habilitada por defecto). Si envías un mensaje a un dispositivo que no admite RCS, el mensaje será rechazado. En este caso, puedes utilizar un mensaje SMS.

{
   "to": "447700900001",
   "from": "Vonage-RCS-Agent",
   "channel": "rcs",
   "message_type": "text",
   "text": "Hello from Vonage!",
   "failover": [
     {
       "to": "447700900001",
       "from": "Vonage",
       "channel": "sms",
       "message_type": "text",
       "text": "Hello from Vonage!"
     }
   ]
}

Conmutación por error múltiple

La idea general es similar a la del ejemplo anterior, pero con más canales utilizados para proporcionar un fallback apropiado basado en el tipo de mensaje. Por ejemplo, es posible que desee enviar un mensaje de producto con una imagen a través de RCS que pasa a una imagen MMS si el dispositivo del destinatario no es compatible con RCS, y luego pasa a SMS si la red del destinatario no es compatible con MMS.

{
   "to": "447700900001",
   "from": "Vonage-RCS-Agent",
   "channel": "rcs",
   "message_type": "image",
   "image": {
     "url": "https://example.com/image.jpg"
    },
   "failover": [
     {
      "to": "447700900001",
      "from": "447700900000",
      "channel": "mms",
      "message_type": "image",
      "image": {
         "url": "https://example.com/image.jpg"
      }
    },
    {
       "to": "447700900001",
       "from": "Vonage",
       "channel": "sms",
       "message_type": "text",
       "text": "Check out this image https://example.com/image.jpg"
     }
   ]
}

Conclusión y próximos pasos

En esta publicación, hemos explorado la funcionalidad de conmutación por error en Messages API de Vonage. Hemos visto qué es la conmutación por error, cómo usarla y algunas situaciones en las que puede ser útil.

Si desea explorar más a fondo la conmutación por error, puede consultar la guía en nuestra documentación para desarrolladores, ejemplos de fragmentos de código que demuestran el uso de la conmutación por error en nuestros SDK de servidor, y la especificación completa de la API de mensajes especificación de la Messages API.

¿Estás creando algo increíble con Messages API de Vonage, planeas usar la función de conmutación por error o simplemente tienes preguntas sobre la función o la API en general? Cuéntanos en nuestro espacio de trabajo Slack de la comunidad de Vonage¡!