Umstellung von Dispatch auf Messages Failover

Dieses Handbuch vergleicht die Funktionalität der Dispatch API mit der Funktionalität der Failover-Funktion in der Messages APIund beschreibt einige Dinge, die bei der Migration von der Dispatch API zur Messages API Failover-Funktionalität zu beachten sind.

Allgemeine Concepts

Auf einer allgemeinen konzeptionellen Ebene sind die Dispatch API und die Failover-Funktion in der Messages API weitgehend ähnlich. Beide Dinge ermöglichen es Ihnen:

  • Geben Sie eine ursprüngliche Nachricht an, mit Ausweichnachricht(en), die gesendet werden soll(en), falls die ursprüngliche Nachricht nicht zugestellt werden kann.
  • Fail over zwischen verschiedenen Nachrichtentypen.
  • Failover zwischen verschiedenen Nachrichtenkanälen.

Es gibt jedoch einige wichtige Unterschiede, die beachtet werden müssen. Die nachstehende Tabelle gibt einen kurzen Überblick über einige dieser Unterschiede, die im weiteren Verlauf des Dokuments ausführlicher erläutert werden.

Dispatch API Messages API Failover
Failover-Logik basierend auf condition_status und expiry_time Eigenschaften Fail-Over-Logik basierend auf der Nachricht rejected
Bietet zwei Arten von Nachrichtenstatus-Webhook: einzelne Nachrichten und Abschlussbericht Bietet einen Typ von Nachrichtenstatus-Webhook
- Unterstützt zusätzliche Kanäle, wie RCS, sowie zusätzliche Nachrichtentypen
Verwendet Nachrichten v0.1 Implementiert in Nachrichten v1
In Server-SDKs nicht unterstützt Unterstützt in Server-SDKs

Wesentliche Unterschiede

Der Hauptunterschied zwischen Dispatch API und Messages API Failover ist die Logik, mit der der Failover ausgelöst wird.

  • Die Dispatch API definiert eine workflow Array, das ein Objekt für jede Nachricht in einem Workflow enthält, außer für die letzte. Innerhalb dieses Objekts wird ein condition_status Eigenschaft gesetzt ist, die den status der zurückzusendenden Nachricht innerhalb der angegebenen expiry_time. Wird der Status nicht innerhalb der expiry_timedann wird der Arbeitsablauf mit der nächsten Nachricht fortgesetzt.

  • Die Failover-Funktion der Messages API definiert die Eigenschaften für die erste Nachricht und enthält dann eine optionale failover Array, das die Nachrichtenobjekte für die verbleibenden Nachrichten des Workflows enthält. Es definiert keine separaten Bedingungen für jede Nachricht in einem Workflow; stattdessen geht der Workflow zur nächsten Nachricht über, wenn die aktuelle Nachricht einen Status von rejected.

Es gibt noch einige andere Unterschiede zwischen den beiden APIs, die zu beachten sind. Diese werden im Abschnitt Andere Überlegungen Abschnitt.

Einen Antrag stellen

Beide APIs erfordern die Erstellung einer HTTP POST Anfrage an ihre jeweiligen URLs (https://api.nexmo.com/v0.1/dispatch/ für die Dispatch API und https://api.nexmo.com/v1/messages für die Messages API).

Die Dispatch API verwendet die Messages API im Hintergrund (die Dispatch API ist im Wesentlichen eine Orchestrierungsschicht für die Messages API), so dass die Nachrichtenobjekte in Bezug auf die enthaltenen Eigenschaften ähnlich sind. Dispatch verwendet jedoch Messages v0.1 und die Funktion Messages Failover ist in Messages v1 implementiert (siehe Andere Überlegungen), daher ist die JSON-Struktur der Nachrichtenobjekte anders (v1 verwendet eine flachere Struktur).

Nachstehend finden Sie Beispiele für eine Anfrage mit beiden APIs.

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

Das obige Beispiel demonstriert einen Dispatch API-Workflow, der von einer MMS-Bildnachricht zu einer SMS-Textnachricht übergeht. Wenn eine delivered Status nicht für die MMS-Bildnachricht innerhalb von 600 Sekunden wird die SMS-Nachricht gesendet.

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!"
		}
	]
}

Das obige Beispiel demonstriert einen Messages API-Workflow, der von einer MMS-Bildnachricht zu einer SMS-Textnachricht übergeht. Wenn eine rejected Status für die MMS-Bildnachricht empfangen wird, wird die SMS-Textnachricht gesendet.

Antworten

Beide APIs geben bei erfolgreichen Anfragen ähnliche Antworten zurück.

Dispatch API

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

Die dispatch_uuid wird zur Identifizierung des Dispatch-Workflows im Kontext von Message Status Webhooks verwendet.

Messages API

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

Die message_uuid ist bei allen Anfragen vorhanden und wird zur Identifizierung der ursprünglichen Nachricht im Kontext von Nachrichtenstatus-Webhooks verwendet. Die workflow_id ist nur bei Anfragen vorhanden, die das failover Array und wird zur Identifizierung des gesamten Arbeitsablaufs verwendet.

Nachrichtenstatus-Webhooks

Nachrichtenstatus-Webhooks werden durch eine Statusänderung einer einzelnen Nachricht ausgelöst und an einen Webhook-Endpunkt gesendet, der in den Vonage Account-Einstellungen oder den Vonage Applications-Einstellungen definiert ist.

Wie bei den Nachrichtenobjekten selbst unterscheidet sich auch die JSON-Struktur der Webhook-Nutzdaten zwischen den APIs. Außerdem sendet die Dispatch API zwei Typen von Status-Webhooks, während die Messages API nur einen Typ sendet.

Dispatch API

Die Dispatch API sendet:

  • Status-Webhooks werden in Bezug auf einzelne Nachrichten innerhalb des Workflows gesendet.
  • Ein "Abschlussbericht Status-Webhook wird gesendet, wenn der angegebene condition_status für eine Nachricht innerhalb des Workflows innerhalb der festgelegten expiry_time erfüllt ist oder wenn die letzte Nachricht in einem Workflow nicht zugestellt werden kann.

Einzelne Nachrichten-Webhooks

Diese enthalten eine message_uuid die die einzelne Nachricht in Bezug auf die Messages API identifiziert. Sie enthalten auch eine workflow Objekt mit einer dispatch_uuid Der Wert dieser Eigenschaft stimmt mit dem überein, was in der Antwort auf die ursprüngliche Anfrage enthalten ist, und kennzeichnet den gesamten Dispatch-Workflow.

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

Endbericht Nachricht Webhook

Diese enthält eine dispatch_uuid Der Wert dieser Eigenschaft stimmt mit dem überein, was in der Antwort auf die ursprüngliche Anfrage empfangen wurde, und kennzeichnet den gesamten Dispatch-Workflow. Sie enthält außerdem eine status entweder von completed wenn die angegebene condition_status für eine Nachricht innerhalb des Arbeitsablaufs innerhalb der Menge erfüllt ist expiry_time, oder error wenn die letzte Nachricht des Workflows nicht zugestellt werden kann.

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

Die Messages API sendet eine Status-Webhook für jede Änderung des Status. Für Meldungen, bei denen die failover Eigenschaft enthalten war, enthält die JSON-Nutzlast eine workflow Objekt. Dieses Objekt wird drei Eigenschaften enthalten:

  • workflow_id: Eindeutige ID für den Failover-Workflow. Entspricht dem Wert der in der Antwort auf die erste API-Anforderung zurückgegebenen workflow_id.
  • items_number: Gibt die spezifische Nachricht innerhalb des Arbeitsablaufs an, auf die sich der Status bezieht, z. B. 1 für die erste Nachricht, 2 für die erste Nachricht in der failover Array, und so weiter.
  • items_total: Gesamtzahl der im Workflow definierten Nachrichten.
{
	"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"
	}
}

Andere Überlegungen

Neben den bereits erwähnten Unterschieden sind bei der Migration von Dispatch API auf die Failover-Funktionalität von Message API noch einige weitere Dinge zu beachten.

Messages API Version

Wie an anderer Stelle in diesem Dokument erwähnt, ist die Dispatch API im Wesentlichen eine Orchestrierungsschicht, die auf der Messages API aufbaut. Es ist jedoch wichtig zu wissen, dass die Messages API derzeit in zwei Versionen vorliegt: v0.1 und v1. Die Dispatch API verwendet Messages v0.1 und die Messages Failover-Funktionalität ist in v1 implementiert. Neben einem Unterschied in der Struktur der JSON-Nutzlast gibt es einige andere erwähnenswerte Unterschiede zwischen den Versionen.

  • Messages v1 unterstützt im Vergleich zu v0.1 zusätzliche Kanäle und Nachrichtentypen. So unterstützt v1 beispielsweise den RCS-Kanal (ein häufiger Anwendungsfall für Failover ist der Wechsel von RCS zu SMS). Selbst innerhalb der von beiden unterstützten Kanäle unterstützt v1 einige zusätzliche Nachrichtentypen wie MMS-Text-, Datei- und Inhaltsnachrichten.
  • Es gibt eine Reihe von anderen zusätzliche Eigenschaften in v1 im Vergleich zu v0.1 bereitgestellt

Server-SDKs

Die Messages API (v1) ist in der Vonage Server-SDKsDie DIspatch API hingegen nicht. Die Messages API-Implementierung in den Server-SDKs umfasst die Messages Failover-Funktionalität. Es gibt Server-SDKs für Node JS, PHP, Python, Java, Kotlin, .NET und Ruby. Mit den SDKs können Sie die Messages API einfach in Ihre Applikationen integrieren, ohne einen eigenen Wrapper für den API-Endpunkt implementieren zu müssen.

Zusätzliche Ressourcen

Weitere Informationen zur Dispatch API und Messages API, einschließlich der Failover-Funktionalität, finden Sie auf den unten verlinkten Dokumentationsseiten:

Dispatch API

Messages API