Verbessern Sie die Zustellbarkeit von Nachrichten mit Failover in der Vonage Messages API

Nachrichten-Failover ist jetzt in der Vonage-Nachrichten-API. Bevor wir uns damit beschäftigen, was Failover ist und wie man es verwendet, lassen Sie uns einen kurzen Überblick über die Nachrichten-API für alle, die damit vielleicht nicht vertraut sind.

Übersicht über die Nachrichten-API

Die Messages-API ist eine Multi-Channel-Messaging-API, die es Unternehmen ermöglicht, verschiedene Nachrichtentypen über mehrere Messaging-Kanäle zu senden und zu empfangen, darunter SMS, MMS, RCS, WhatsApp und andere.

Die genaue JSON-Struktur der API-Anforderungsnutzdaten variiert je nach Kanal und/oder Nachrichtentyp, aber alle Nachrichten folgen den gleichen Grundprinzipien. Das JSON für alle Nachrichten hat Eigenschaften für an, von, Kanalund message_typesowie eine Eigenschaft für die Nachricht selbst, die je nach Nachrichtentyp variieren kann. Darüber hinaus gibt es weitere optionale Eigenschaften, von denen sich einige auf spezifische Merkmale beziehen, die von einem bestimmten Kanal oder Nachrichtentyp unterstützt werden.

Dies wäre zum Beispiel die JSON-Struktur für das Senden eines einfachen Text Nachricht über die sms Kanal:

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

Ein grundlegendes Bild Nachricht, die über die rcs Kanal gesendet wird, würde JSON verwenden, das etwa so strukturiert ist:

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

Die Antwort auf die API-Anforderung enthält einen Antwortkörper mit einer message_uuid Eigenschaft, die das Nachrichtenobjekt auf den Servern von Vonage eindeutig identifiziert. Diese UUID kann dann für die Verfolgung des Status der Nachricht verwendet werden.

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

Status der Nachricht

Sobald die erste API-Anforderung gestellt wurde, durchläuft das Nachrichtenobjekt verschiedene Zuständewie zum Beispiel übermittelt und zugestelltwährend die Nachrichten-API versucht, sie über das nachgelagerte Netz des gewünschten Kanals an den angegebenen Empfänger zuzustellen.

Eine Statusänderung löst eine HTTP-Anfrage aus, die an den Status-Webhook-Endpunkt gesendet, der in den Einstellungen Ihrer Vonage-Anwendung definiert ist. Der Request Body hat einen JSON-Payload, der in etwa wie folgt strukturiert ist (je nach Kanal und Status können jedoch zusätzliche Eigenschaften vorhanden sein):

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

Spezifische Status können je nach Kanal leicht variieren. Zum Beispiel können Kanäle wie RCS und WhatsApp haben einen gelesen Status, der anzeigt, dass eine zugestellte Nachricht nun vom Empfänger gelesen wurde, während SMS und MMS-Kanäle nicht über die Möglichkeit verfügen, einen lesen Status zu liefern.

Ein Nachrichtenstatus, den alle Kanäle gemeinsam haben, ist der abgelehnt Status. Je nach Kanal und/oder Nachrichtentyp kann es verschiedene Gründe geben, warum eine Nachricht abgelehnt wurde. In allen Fällen ist jedoch ein abgelehnt Status bedeutet, dass die Nachricht dem Empfänger nicht zugestellt wird.

Bevor Failover in die Vonage Messages API implementiert wurde, mussten Sie die Geschäftslogik für den Fall, dass Nachrichten abgelehnt werden, selbst implementieren, wenn Sie eine gewisse Ausfallsicherheit in Ihre Messaging-Anwendung einbauen wollten. Sie könnten zum Beispiel ein System orchestrieren, um den Status einer einzelnen Nachrichtenanforderung zu verfolgen, indem Sie die Nachrichtenstatus-Webhook-Nachrichten mit der message_uuid Wert, der in der anfänglichen HTTP zurückgegeben wird, und wenn eine abgelehnt Status für ein Nachrichtenobjekt empfangen wurde, eine Rückfallnachricht anfordern, die gesendet werden soll.

Mit der Failover-Funktion kann diese Art von Logik in die ursprüngliche Nachrichtenanforderung selbst integriert werden. Lassen Sie uns herausfinden, wie!

Verwendung von Failover in der Nachrichten-API

Zur Verwendung von Ausfallsicherung in der Nachrichten-API zu verwenden, müssen Sie eine zusätzliche failover Eigenschaft in die JSON-Nutzlast aufnehmen, die die Nachricht definiert. Der Wert dieser Eigenschaft ist ein Array, das ein oder mehrere Nachrichtenobjekte enthält.

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

Wenn die erste Nachricht abgelehnt wird, sendet die Nachrichten-API automatisch das erste Nachrichtenobjekt im Ausfallsicherung Array. Wird auch diese Nachricht abgelehnt, wird das zweite Objekt (sofern eines definiert ist) gesendet usw.

Wenn Sie die Ausfallsicherung Eigenschaft in die API-Anforderung, wird eine message_uuid in der HTTP-Antwort wie üblich empfangen, aber eine zusätzliche Eigenschaft, workflow_id ist ebenfalls enthalten:

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

Beim Empfang von Nachrichtenstatus-Webhook-Anfragen für Nachrichtenobjekte, die mit einer Ausfallsicherung Eigenschaft gesendet wurden, enthält die JSON-Nutzlast eine Workflow Objekt mit der Eigenschaft workflow_id Eigenschaft, deren Wert mit der workflow_id entspricht, die in der Antwort auf die ursprüngliche API-Anforderung enthalten ist. In diesem Zusammenhang steht ein "Workflow" für eine Reihe von Nachrichten - die Ausgangsnachricht und die definierte(n) Failover-Nachricht(en).

Darüber hinaus ist der Workflow Objekt eine items_number Eigenschaft und eine items_total Eigenschaft. Die items_number gibt an, auf welches "Item" oder welche Nachricht innerhalb des gesamten Arbeitsablaufs sich diese Anfrage zum Nachrichtenstatus bezieht. Eine items_number von 1 gibt die ursprüngliche Nachricht an, und items_number von 2 steht für das erste Nachrichtenobjekt in der Ausfallsicherung Array an, und so weiter. Die items_total Eigenschaft gibt die Gesamtzahl der "Items" oder Nachrichten im gesamten Workflow an; zum Beispiel kann eine items_total von 3 würde eine ursprüngliche Nachricht mit zwei Nachrichten in der Ausfallsicherung Array definiert sind.

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

Die Nachrichten-API sendet bei Bedarf Anfragen zum Nachrichtenstatus für jede Nachricht in einem Workflow. So könnten Sie zum Beispiel eine Status von abgelehnt für Artikel_Anzahl 1, und dann einen Status von geliefert (mit der gleichen message_uuid und workflow_id) für items_number 2. Wenn hingegen items_number 1 wurde zugestellt wäre der Workflow abgeschlossen, und alle nachfolgenden Nachrichten im Workflow würden keine Nachrichtenstatusanfragen auslösen.

Wann wird Failover verwendet?

Jetzt, wo wir uns damit befasst haben was Ausfallsicherung ist und wie wollen wir uns nun einige Anwendungsmöglichkeiten ansehen.

Ausfallsicherung über Kanäle hinweg

Sie können die Multi-Channel-Fähigkeit der Vonage Messages-API nutzen, indem Sie versuchen, eine Nachricht an einen Kanal zu übermitteln, und wenn die ursprüngliche Nachricht abgelehnt wird, zu einem anderen Kanal überwechseln.

Ein gängiger Anwendungsfall wäre der Wechsel von RCS zu SMS. Obwohl RCS weithin unterstützt wird unterstützt wird (RCS-Messaging wird unter iOS seit Version 18 unterstützt), ist es in Bezug auf Geräteunterstützung und Netzabdeckung immer noch nicht so weit verbreitet wie SMS. Außerdem müssen Sie bei einigen Geräten RCS-Messaging auf dem Gerät aktivieren (d. h. es ist nicht standardmäßig aktiviert). Das Senden einer Nachricht an ein Gerät, das RCS nicht unterstützt, würde dazu führen, dass die Nachricht zurückgewiesen. In diesem Fall können Sie stattdessen auf eine SMS-Nachricht ausweichen.

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

Mehrfache Ausfallsicherung

Der Grundgedanke ist ähnlich wie beim vorherigen Beispiel, jedoch werden mehr Kanäle verwendet, um je nach Nachrichtentyp einen geeigneten Fallback zu ermöglichen. Sie könnten zum Beispiel eine Produktnachricht mit einem Bild über RCS senden, die zu einem MMS-Bild übergeht, wenn das Gerät des Empfängers RCS nicht unterstützt, und dann zu SMS übergeht, wenn das Netz des Empfängers MMS nicht unterstützt.

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

Schlussfolgerung und nächste Schritte

In diesem Beitrag haben wir uns mit der Failover-Funktionalität in der Vonage Messages API beschäftigt. Wir haben uns angesehen, was Failover ist, wie man es verwendet und in welchen Situationen es nützlich sein könnte.

Wenn Sie sich eingehender mit Failover beschäftigen möchten, können Sie sich den Leitfaden in unserer Entwicklerdokumentation nachlesen, Code-Schnipsel-Beispiele die die Verwendung von Failover in unseren Server-SDKs demonstrieren, sowie die vollständige Nachrichten-API-Spezifikation.

Bauen Sie etwas Tolles mit der Vonage Messages API, planen Sie die Nutzung der Failover-Funktionalität oder haben Sie einfach nur Fragen zu diesem Feature oder der API im Allgemeinen? Lassen Sie es uns in unserem Vonage Community Slack-Arbeitsbereich!