Migration de la répartition vers le basculement des messages

Ce guide compare les fonctionnalités de l'API Dispatch avec celles de la fonctionnalité Failover de l'API Messages APIet souligne certains points à prendre en compte lors de la migration de l'API Dispatch vers la fonctionnalité de basculement de l'API Messages.

Concepts généraux

D'un point de vue conceptuel général, l'API Dispatch et la fonction Failover de l'API Messages sont largement similaires. Ces deux éléments vous permettent :

  • Spécifier un message initial, ainsi qu'un ou plusieurs messages de repli à envoyer si le message initial n'est pas délivré.
  • Basculement entre différents types de messages.
  • Basculement entre les différents canaux de messagerie.

Il existe cependant quelques différences importantes à connaître. Le tableau ci-dessous donne un bref aperçu de certaines de ces différences, qui sont expliquées plus en détail dans le reste du document.

Dispatch API Messages API Failover (basculement de l'API)
Logique de basculement basée sur condition_status et expiry_time propriétés Logique de basculement basée sur le message en cours rejected
Fournit deux types de webhook sur l'état des messages : les messages individuels et le rapport final. Fournit un type de webhook sur l'état des messages
- Prise en charge de canaux supplémentaires, tels que RCS, ainsi que de types de messages supplémentaires
Utilise les messages v0.1 Mis en œuvre dans Messages v1
Non pris en charge par les SDK du serveur Pris en charge dans les SDK du serveur

Principales différences

La principale différence entre le basculement de l'API Dispatch et de l'API Messages est la logique par laquelle le basculement est déclenché.

  • L'API Dispatch définit une fonction workflow contenant un objet pour chaque message du flux de travail, à l'exception du dernier. Dans cet objet, un objet condition_status est définie en spécifiant la propriété status du message à renvoyer dans le délai spécifié expiry_time. Si le statut n'est pas renvoyé dans le délai de expiry_timele flux de travail passe alors au message suivant.

  • La fonction de basculement de l'API Messages définit les propriétés du message initial, puis inclut une fonction facultative de failover qui contient les objets de message pour les messages restants dans le flux de travail. Il ne définit pas de conditions distinctes pour chaque message d'un flux de travail ; au lieu de cela, le flux de travail passe au message suivant si le message actuel renvoie un statut de rejected.

Il existe quelques autres différences entre les deux API. Elles sont abordées dans la section Autres considérations section.

Faire une demande

Les deux API nécessitent la création d'un fichier HTTP POST à leurs URL respectifs (https://api.nexmo.com/v0.1/dispatch/ pour l'API Dispatch et https://api.nexmo.com/v1/messages pour l'API Messages).

L'API Dispatch utilise l'API Messages en arrière-plan (l'API Dispatch est essentiellement une API couche d'orchestration pour l'API Messages), les objets message sont donc similaires en ce qui concerne les propriétés qu'ils contiennent. Cependant, Dispatch utilise Messages v0.1 et la fonctionnalité Messages Failover est implémentée dans Messages v1 (voir Autres considérations), de sorte que la structure JSON des objets de message est différente (la version 1 utilise une structure plus plate).

Vous trouverez ci-dessous des exemples de requêtes effectuées à l'aide des deux API.

Dispatch API

{
   "template":"failover",
   "workflow": [
		{
			"from": { "type": "mms", "number": "447900000000" },
			"to": { "type": "mms", "number": "447900000001" },
			"message": {
				"content": {
				"type": "img",
				"image": { "url": "https://example.com/image.jpg" }
				}
			},
			"failover":{
				"expiry_time": 600,
				"condition_status": "delivered"
			}
		},
		{
			"from": {"type": "sms", "number": "447900000000"},
			"to": { "type": "sms", "number": "447900000001"},
			"message": {
				"content": {
				"type": "text",
				"text": "This is an SMS sent via the Dispatch API"
				}
			}
		}
   ]
}

L'exemple ci-dessus montre un flux de travail Dispatch API qui passe d'un message image MMS à un message texte SMS. Si un delivered n'est pas reçu pour le message image MMS dans le délai de 600 secondes, le SMS est envoyé.

Messages API

{
	"to": "447700900000",
	"from": "447700900001",
	"channel": "mms",
	"message_type": "image",
	"image": {
		"url": "https://example.com/image.jpg"
	},
	"failover": [
		{
	"to": "447700900000",
	"from": "447700900001",
	"channel": "sms",
	"message_type": "text",
	"text": "Hello from Vonage!"
		}
	]
}

L'exemple ci-dessus montre un flux de travail de Messages API qui passe d'un message image MMS à un message texte SMS. Si un rejected est reçu pour le message image MMS, le message texte SMS est envoyé.

Réponses

Les deux API renvoient des réponses similaires lorsque les demandes aboutissent.

Dispatch API

{
	"dispatch_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
}

Les dispatch_uuid est utilisé pour identifier le flux de travail Dispatch dans le contexte des webhooks Message Status.

Messages API

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

Les message_uuid est présent pour toutes les demandes et est utilisé pour identifier le message initial dans le contexte des webhooks sur l'état des messages. L'élément workflow_id n'est présent que pour les demandes qui incluent l'option failover et sert à identifier le flux de travail dans son ensemble.

Webhooks sur l'état des messages

Les webhooks sur l'état des messages sont déclenchés par un changement d'état d'un message individuel et sont envoyés à un point de terminaison webhook défini dans les paramètres du compte Vonage ou dans les paramètres de l'application Vonage.

Comme pour les objets de message eux-mêmes, la structure JSON de la charge utile du webhook diffère d'une API à l'autre. En outre, l'API Dispatch envoie deux types de webhook d'état, alors que l'API Messages n'en envoie qu'un seul.

Dispatch API

L'API Dispatch envoie :

  • Crochets web d'état sont envoyés en relation avec des messages individuels au sein du flux de travail.
  • Un "rapport final statut webhook est envoyé si/quand l'état_de_condition spécifié pour un message dans le flux de travail est satisfait dans le délai d'expiration défini, ou si le message final dans un flux de travail n'a pas pu être livré.

Webhooks de messages individuels

Ceux-ci contiennent un message_uuid qui identifie le message individuel par rapport à l'API Messages. Ils contiennent également un workflow avec un objet dispatch_uuid La valeur de cette propriété correspond à ce qui est reçu en réponse à la demande initiale et identifie le flux de travail global de la répartition.

{
	"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
	"to": {
		"type": "sms",
		"number": "447700900001"
	},
	"from": {
		"type": "sms",
		"number": "447700900000"
	},
	"timestamp": "2020-01-01T14:00:00.000Z",
	"status": "rejected",
	"error": {
		"code": 1300,
		"reason": "Not part of the provider network"
	},
	"usage": {
		"currency": "EUR",
		"price": "0.0333"
	},
	"_links": {
		"workflow": {
				"dispatch_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
				"href": "/workflows/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
		}
	}
}

Message du rapport final Webhook

Il contient un dispatch_uuid La valeur de cette propriété correspond à ce qui est reçu en réponse à la demande initiale et identifie le flux de travail global de la répartition. Elle contient également un status de l'un ou l'autre completed si l'option condition_status pour un message dans le flux de travail est satisfait dans l'ensemble expiry_timeou error si le dernier message du flux de travail ne peut être délivré.

{
	"dispatch_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
	"template": "failover",
	"status": "completed",
	"timestamp": "2020-01-01T14:00:00.000Z",
	"usage": {
		"price": "0.02",
		"currency": "EUR"
	},
	"_links": {
		"messages": [
			{
				"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
				"href": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
				"channel": "mms",
				"usage": {
						"currency": "EUR",
						"price": "0.0333"
				},
				"status": "submitted"
			}
		]
	}
}

Messages API

L'API Messages envoie un statut webhook pour tout changement de statut. Pour les messages où le failover a été incluse, la charge utile JSON comprendra une propriété workflow objet. Cet objet contiendra trois propriétés :

  • workflow_id: ID unique pour le flux de travail de basculement. Correspond à la valeur de workflow_id renvoyée dans la réponse à la demande API initiale.
  • items_number: Indique le message spécifique au sein du flux de travail auquel le statut se rapporte ; par ex. 1 pour le message initial, 2 pour le premier message du failover et ainsi de suite.
  • items_total: Nombre total de messages définis dans le flux de travail.
{
	"message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
	"to": "447700900000",
	"from": "447700900001",
	"timestamp": "2025-02-03T12:14:25Z",
	"status": "delivered",
	"workflow": {
		"workflow_id": "3TcNjguHxr2vcCZ9Ddsnq6tw8yQUpZ9rMHv9QXSxLan5ibMxqSzLdx9",
		"items_number": "1",
		"items_total": "2"
	},
	"usage": {
		"currency": "EUR",
		"price": "0.0333"
	},
	"channel": "sms",
	"destination": {
		"network_code": "12345"
	},
	"sms": {
		"count_total": "2"
	}
}

Autres considérations

Outre les différences déjà évoquées, il y a quelques autres éléments à prendre en compte lors de la migration de Dispatch API vers la fonctionnalité de basculement de Message API.

Messages API Version

Comme indiqué ailleurs dans ce document, l'API Dispatch est essentiellement une couche d'orchestration au-dessus de l'API Messages. Il est important de noter que l'API Messages a actuellement deux versions : v0.1 et v1. L'API Dispatch utilise Messages v0.1 et la fonctionnalité Messages Failover est mise en œuvre dans la version v1. Outre une différence dans la structure de la charge utile JSON, il existe d'autres différences entre les versions qui méritent d'être mentionnées.

  • Messages La version 1 prend en charge des canaux et des types de messages supplémentaires par rapport à la version 0.1. Par exemple, la v1 prend en charge le canal RCS (un cas d'utilisation courant pour le basculement est le passage de RCS à SMS). Même au sein des canaux pris en charge par les deux versions, la v1 prend en charge des types de messages supplémentaires tels que le texte MMS, les fichiers et les types de messages de contenu.
  • Il y a un certain nombre d'autres caractéristiques supplémentaires fournies dans la v1 par rapport à la v0.1

SDK de serveur

L'API Messages (v1) est mise en œuvre dans le logiciel Vonage SDK de serveuralors que l'API DIspatch ne l'est pas. La mise en œuvre de l'API Messages dans les SDK de serveur inclut la fonctionnalité de basculement des messages. Il existe des SDK serveur pour Node JS, PHP, Python, Java, Kotlin, .NET et Ruby. Les SDK vous permettent d'intégrer facilement l'API Messages dans vos Applications sans avoir à mettre en œuvre votre propre wrapper pour le point de terminaison de l'API.

Ressources complémentaires

Pour plus d'informations sur les API Dispatch et Messages API, y compris la fonctionnalité Failover, vous pouvez vous référer aux pages de documentation ci-dessous :

Dispatch API

Messages API