Introduction du basculement des messages dans l'API Messages de Vonage

Le basculement des messages est désormais disponible dans l Vonage Messages API. Avant de nous plonger dans ce qu'est le basculement et comment l'utiliser, faisons un bref tour d'horizon de l'API Messages API pour ceux qui ne la connaîtraient pas.

Aperçu de l'API Messages

L'API Messages est une API de messagerie multicanal qui permet aux entreprises d'envoyer et de recevoir divers types de messages sur plusieurs canaux de messagerie, notamment SMS, MMS, RCS, WhatsApp, etc.

La structure JSON exacte de la charge utile de la demande API varie en fonction du canal et/ou du type de message, mais tous les messages suivent les mêmes principes de base. Le JSON de tous les messages comporte les propriétés suivantes à, de, canalet type_de_messageainsi qu'une propriété pour le message lui-même, qui varie en fonction du type de message. Il existe également d'autres propriétés facultatives, dont certaines se rapportent à des caractéristiques spécifiques prises en charge par un canal ou un type de message donné.

Par exemple, voici la structure JSON pour l'envoi d'un simple texte par l'intermédiaire de la fonction sms par l'intermédiaire du canal sms :

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

Une image image envoyé par l'intermédiaire de l'interface rcs utiliserait une structure JSON semblable à celle-ci :

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

La réponse à la demande de l'API contiendra un corps de réponse avec un message_uuid qui identifie de manière unique l'objet message sur les serveurs de Vonage. Cet UUID peut ensuite être utilisé pour suivre le statut du message.

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

Statut du message

Une fois la demande API initiale effectuée, l'objet message passera par différents statutstels que soumis et délivréL'API Messages tente de livrer le message au destinataire spécifié via le réseau en aval du canal requis.

Un changement de statut déclenche l'envoi d'une requête HTTP au point de terminaison webhook point de terminaison du webhook de l'état défini dans les paramètres de votre application Vonage. Le corps de la demande aura une charge utile JSON structurée comme suit (bien qu'il puisse y avoir des propriétés supplémentaires en fonction du canal et de l'état) :

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

Les statuts spécifiques peuvent varier légèrement en fonction du canal. Par exemple, les canaux tels que le RCS et WhatsApp ont un statut lu indiquant qu'un message délivré a été lu par le destinataire, alors que les SMS et MMS n'ont pas la capacité de fournir un statut de lecture. lecture de lecture.

Un statut de message que tous les canaux ont en commun est le statut rejeté est l'état rejeté. Selon le canal et/ou le type de message, il peut y avoir plusieurs raisons pour lesquelles un message a été rejeté. Dans tous les cas, un message rejeté signifie que le message ne sera pas remis au destinataire.

Qu'est-ce que le basculement de message ?

Avant que le basculement ne soit mis en œuvre dans l'API Messages de Vonage, si vous souhaitiez intégrer une certaine résilience à votre application de messagerie afin de faire face aux situations où les messages sont rejetés, vous auriez dû mettre en œuvre vous-même la logique commerciale nécessaire. Par exemple, vous pourriez orchestrer un système de suivi de l'état d'une demande de message individuelle à l'aide des messages du webhook sur l'état des messages en utilisant l'attribut message_uuid renvoyée dans la requête HTTP initiale, et si un message rejeté a été reçu pour un objet de message, demander l'envoi d'un message de repli.

Avec la fonction de basculement, ce type de logique peut être incorporé dans la demande de message initiale elle-même. Voyons comment !

Utilisation du basculement dans l'API Messages

Pour utiliser le basculement dans l'API Messages vous devez inclure une propriété failover dans la charge utile JSON qui définit le message. La valeur de cette propriété est un tableau qui contient un ou plusieurs objets message.

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

Si le message initial est rejeté, l'API Messages enverra automatiquement le premier objet de message dans la zone de basculement . Si ce message est également rejeté, le deuxième objet (s'il en existe un) sera envoyé, et ainsi de suite.

Lorsque l'on inclut le basculement dans la demande d'API, un message_uuid est reçu dans la réponse HTTP comme d'habitude, mais une propriété supplémentaire, workflow_id est également incluse :

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

Lors de la réception de demandes de webhook sur l'état des messages pour des objets de message qui ont été envoyés avec un basculement la charge utile JSON comprendra une propriété workflow avec l'objet workflow_id dont la valeur correspondra à la propriété workflow_id reçu dans la réponse à la demande API initiale. Dans ce contexte, un "flux de travail" représente la série de messages - le message initial et le(s) message(s) de basculement défini(s).

En outre, le workflow contiendra un objet nombre_d'articles et une propriété items_total et une propriété items_total. L'objet nombre_d'éléments indique à quel "élément" ou message du flux de travail global cette demande de statut de message se rapporte. Un nombre_d'items de 1 indique le message initial, et nombre_d'items de 2 indique le premier objet de message dans le basculement et ainsi de suite. Le items_total indique le nombre total d'"éléments" ou de messages dans le flux de travail global ; par exemple, une propriété items_total de 3 indique un message initial et deux messages définis dans l'élément basculement de basculement.

{
   "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"
   }
}

L'API Messages enverra des demandes d'état des messages si nécessaire pour chaque message d'un flux de travail. Ainsi, par exemple, vous pourriez recevoir une demande de statut de rejeté pour nombre_d'articles 1, et ensuite un statut de livré (avec le même message_uuid et workflow_id) pour nombre_d'articles 2. En revanche, si numéro_article 1 a été livré le flux de travail est terminé et les messages suivants du flux de travail ne déclenchent pas de demande d'état du message.

Quand utiliser le basculement

Maintenant que nous avons abordé ce qu'est le basculement et comment l'utiliser, examinons quelques façons de l'utiliser.

Basculement d'une voie à l'autre

Vous pouvez tirer parti de la capacité multicanal de l'API Messages de Vonage en tentant de transmettre un message à un canal et, si le message initial est rejeté, en passant à un autre canal.

Un cas d'utilisation courant serait le passage de RCS à SMS. Bien que le RCS soit désormais largement supporté (la messagerie RCS est prise en charge sur iOS depuis la version 18), elle n'est pas encore aussi répandue que le SMS en termes de prise en charge des appareils et de couverture réseau. En outre, certains appareils nécessitent que vous activiez la messagerie RCS sur l'appareil (c'est-à-dire qu'elle n'est pas activée par défaut). L'envoi d'un message à un appareil qui ne prend pas en charge le RCS aurait pour conséquence que ce message serait rejeté. Dans ce cas, vous pouvez passer à un message 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!"
     }
   ]
}

Basculement multiple

L'idée générale est similaire à l'exemple précédent, mais avec plus de canaux utilisés pour fournir une solution de repli appropriée en fonction du type de message. Par exemple, vous pouvez envoyer un message de produit avec une image via RCS qui bascule vers une image MMS si l'appareil du destinataire ne prend pas en charge RCS, puis vers un SMS si le réseau du destinataire ne prend pas en charge les 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"
     }
   ]
}

Conclusion et prochaines étapes

Dans ce billet, nous avons exploré la fonctionnalité de basculement dans l'API Messages de Vonage. Nous avons examiné ce qu'est le basculement, comment l'utiliser et quelques situations où il peut être utile.

Si vous souhaitez approfondir la question du basculement, vous pouvez consulter le guide dans notre documentation pour les développeurs, les exemples d'extraits de code démontrant l'utilisation du basculement dans nos SDK serveur, et la spécification complète de l'API Messages API.

Vous construisez quelque chose de génial avec l'API Messages de Vonage, vous prévoyez d'utiliser la fonctionnalité de basculement, ou vous avez simplement des questions sur cette fonctionnalité ou sur l'API en général ? Faites-le nous savoir sur notre espace de travail Slack de la espace de travail Slack de la communauté Vonage!