Migration von SMS API zu Messages API

Die Vonage Messages API ist die empfohlene Methode zum Senden und Empfangen von SMS. Sie unterstützt mehrere Kanäle wie SMS, MMS, RCS und WhatsApp über eine einzige, einheitliche Schnittstelle. Dieser Leitfaden vergleicht die HTTP-basierte SMS API und die Messages API für SMS-Nutzungsfälle und führt Sie durch die Einrichtung des Accounts, ausgehende Anfragen, eingehende Nutzdaten und Statusverfolgungsänderungen, die Sie während einer Migration vornehmen müssen. SMPP-Integrationen werden hier nicht behandelt.

Einrichten Ihres Vonage Accounts für die Verwendung der Messages API

Wählen Sie die Messages API im Dashboard

Der erste Schritt bei der Migration von der alten SMS API zur Messages API ist die Aktualisierung der Messaging API-Typ Einstellung auf der API-Einstellungen Seite des Vonage Developer Dashboards. Wählen Sie Messages API als die API-Typ hier.

Wenn Sie diese Einstellung nicht von SMS API (Legacy) ändern, werden eingehende Nachrichten und Zustellungsbestätigungen weiterhin die SMS API-Konfiguration im Dashboard verwenden.

Einstellungen auf Account-Ebene vs. Vonage-Applikationen

Nachdem Sie Ihren Account für die Verwendung der Messages API eingerichtet haben, müssen Sie entscheiden, wie Sie Ihre Messages API-Einstellungen konfigurieren möchten. Es gibt zwei Möglichkeiten, dies zu tun:

• Einstellungen auf Account-Ebene
• Eine Vonage-Applikation

Die Hauptunterschiede zwischen den beiden bestehen darin, wo Sie Webhooks und die für die Authentifizierung verwendeten Anmeldedaten (und damit die verfügbaren Authentifizierungsmethoden) konfigurieren. Die Verwendung der Messages API mit Einstellungen auf Kontoebene ist in Bezug auf die Konfiguration näher an der Konfiguration der Einstellungen für die SMS API. In der nachstehenden Tabelle werden die Unterschiede im Detail verglichen.

1. Sowohl die SMS API als auch die Messages API unterstützen auch das Überschreiben der konfigurierten DLR/Status-Webhook-URL auf Basis einer einzelnen Anfrage.
2. Wir empfehlen dringend, Messages API v1 für Ihre Migration zu verwenden. Stellen Sie sicher, dass die Version wird eingestellt auf v1 entweder in Ihren Account-Einstellungen oder in jeder von Ihnen erstellten Vonage-Applikation (je nachdem, welchen Konfigurationsansatz Sie verwenden). Dies ist die Standardeinstellung für alle neuen Vonage-Accounts, kann aber auch eingestellt werden auf v0.1 auf älteren Accounts aus Gründen der Abwärtskompatibilität.

Im Allgemeinen empfehlen wir die Verwendung von Vonage Applications für Ihre Messages API-Integration aufgrund ihrer größeren Flexibilität und der Verwendung von JWTs für die Authentifizierung. Da die Einstellungen auf Account-Ebene jedoch näher an dem von der SMS API verwendeten Ansatz liegen, sollten Sie für Ihre Migration einen zweistufigen Ansatz in Erwägung ziehen, bei dem Sie zunächst zu Einstellungen auf Account-Ebene und zur Basisauthentifizierung für die Messages API wechseln und dann Vonage Applications verwenden.

Was ist eine Vonage Application?

Eine Vonage Application mag für Entwickler, die von der SMS API kommen, ein neues Konzept sein. Sie ist im Wesentlichen ein Container für die Konfiguration und die Anmeldedaten. Sie ist nicht dasselbe wie Ihre Software-Anwendung.

Jede Vonage Application enthält:

• Ein Name
• Eine eindeutige Application ID
• Ein generiertes öffentliches/privates Schlüsselpaar (verwendet für die JWT-Authentifizierung)
• Zusätzliche produktspezifische Einstellungen. Für die Messages API sind dies Webhook-URLs für eingehende Nachrichten und Nachrichtenstatus-Updates

Die SMS API verwendet keine Applications. Webhooks werden global auf der Ebene des Accounts konfiguriert. Obwohl Sie mit der Messages API weiterhin Einstellungen auf Kontoebene verwenden können, wenn Sie sich dafür entscheiden, ist es auch unterstützt die Verwendung von Vonage Applications. Da jede Applikation ihre eigene Webhook-Konfiguration und -Einstellungen hat, ist es einfacher, mehrere Integrationen unabhängig voneinander zu verwalten.

Warum werden Vonage Applications empfohlen?

Die Wahl des Konfigurationsansatzes in der Messages API wirkt sich darauf aus, wo Ihre Einstellungen konfiguriert werden, und auch auf die verwendete Authentifizierungsmethode.

Vonage Applications werden empfohlen, weil:

• Da die Einstellungen auf der Ebene der Vonage Applications definiert werden und Sie viele Applications erstellen können, ist es einfacher, mehrere Integrationen für unterschiedliche Geschäftsabläufe oder Anwendungsfälle zu verwalten.
• Vonage Applications können programmatisch über die Vonage CLI oder Application API erstellt und verwaltet werden
• Vonage Applications ermöglichen die Verwendung von JWTs, die mit einem öffentlichen/privaten Schlüsselpaar für die Authentifizierung generiert werden. Dadurch wird der Authentifizierungsprozess im Vergleich zur Basic Authentication um eine zusätzliche Sicherheitsebene erweitert.

Einstellungen auf Account-Ebene verwenden

Wenn Sie Einstellungen auf Account-Ebene mit den Messages API-Webhooks verwenden möchten, ist der grundlegende Einrichtungsablauf folgender:

1. Öffnen Sie API-Einstellungen im Dashboard.
2. Setzen Sie die Messages API Version zu v1.
3. Konfigurieren Sie die eingehenden und Status-Webhook-URLs auf Account-Ebene.
4. Überprüfung Ihre Numbers für alle eingehenden Überschreibungen pro Nummer, die das Routing ändern könnten.
5. Senden Sie Messages API-Anfragen mit einfacher Authentifizierung.
6. Überprüfen Sie, ob die eingehenden Nachrichten und Statusrückrufe die erwarteten Endpunkte auf Account-Ebene erreichen, bevor Sie den Produktionsverkehr umschalten.

Verwendung einer Vonage Application für Messages API

Wenn Sie Routing auf Anwendungsebene und JWT-Authentifizierung wünschen, ist der Einrichtungsablauf folgender:

1. Erstellen Sie eine neue Anwendung, oder öffnen Sie die gewünschte Anwendung.
2. Aktivieren Sie die Nachrichten Fähigkeit.
3. Konfigurieren Sie die Webhook-URLs für eingehende und Statusmeldungen der Anwendung.
4. Setzen Sie die Messages API Version zu v1.
5. Verknüpfen Sie die SMS-fähige Nummer mit dieser Anwendung.
6. Senden Sie Messages API-Anfragen mit JWT-Authentifizierung.
7. Überprüfen Sie, ob eingehende Nachrichten und Statusrückrufe die Endpunkte auf Anwendungsebene erreichen, bevor Sie den Produktionsverkehr umleiten.

Erstellen einer Vonage API-Applikation

Es gibt drei alternative Methoden zur Erstellung einer Nachrichten-Anwendung:

1. Verwenden der Vonage CLI
2. Verwendung des Dashboards
3. Verwendung der Application API

Jede dieser Methoden wird in den folgenden Abschnitten beschrieben.

So erstellen Sie eine Messages-Applikation mit der Vonage CLI

Um Ihre Anwendung mit der Vonage CLI zu erstellen, geben Sie den folgenden Befehl in die Shell ein:

Mit diesem Befehl wird eine Vonage API-Anwendung mit einer Nachrichten Fähigkeitund die Webhook-URLs werden wie angegeben konfiguriert. Es wird auch eine private Schlüsseldatei erzeugt my_messages_app.key und erstellt oder aktualisiert die vonage_app.json Datei.

So erstellen Sie eine Nachrichten-Applikation mit dem Dashboard

Sie können eine Anwendung "Nachrichten" in der Dashboard.

So erstellen Sie Ihre Anwendung über das Dashboard:

1. Unter Applications im Dashboard, klicken Sie auf die Schaltfläche Erstellen Sie eine neue Anwendung Taste.

2. Unter Namegeben Sie den Namen der Applikation ein. Wählen Sie einen Namen, damit Sie ihn in Zukunft leichter finden.

3. Klicken Sie auf die Schaltfläche Öffentlichen und privaten Schlüssel generieren. Dadurch wird ein öffentliches/privates Schlüsselpaar erstellt und der private Schlüssel wird von Ihrem Browser heruntergeladen.

4. Unter Fähigkeiten wählen Sie die Nachrichten Taste.

5. In der Eingehende URL geben Sie die URL für Ihren Webhook für eingehende Nachrichten ein, zum Beispiel, https://example.com/webhooks/inbound-message.

6. In der Status-URL geben Sie die URL für Ihren Nachrichtenstatus-Webhook ein, zum Beispiel, https://example.com/webhooks/message-status.

7. Klicken Sie auf die Neue Anwendung generieren Schaltfläche. Sie gelangen nun zum nächsten Schritt des Verfahrens "Anwendung erstellen", wo Sie eine Vonage API-Nummer mit der Anwendung verknüpfen und externe Accounts wie Facebook mit dieser Anwendung verknüpfen können.

8. Wenn es ein externes Konto gibt, mit dem Sie diese Anwendung verknüpfen möchten, klicken Sie auf die Schaltfläche Verknüpfte externe Konten und klicken Sie dann auf die entsprechende Registerkarte Link für den Account, den Sie verknüpfen möchten.

Sie haben nun Ihre Anwendung erstellt.

Erstellen einer Messages-Applikation mit Hilfe der Application API

Mit der Application API können Sie eine Vonage Application programmatisch erstellen und konfigurieren - ohne das Dashboard oder die CLI zu verwenden. Eine über die Application API erstellte Vonage Application funktioniert genauso wie eine über das Dashboard erstellte.

Einen vollständigen Überblick über die Erstellung einer Vonage Application finden Sie unter Erstellen einer Vonage-Applikation.

Verknüpfung einer Telefonnummer mit Ihrer Applikation

Öffnen Sie im Dashboard den Bereich Applications Seitewählen Sie die gewünschte Anwendung aus, und verknüpfen Sie die Nummer aus dem Verzeichnis der Anwendung Link-Nummern tab.

Sie können auch rufnummernspezifische Einstellungen für eingehende Webhooks verwalten unter Ihre Numbers. Das Dashboard zeigt an, dass ein eingehender Webhook pro Nummer den eingehenden Webhook auf Kontoebene übersteuert. Wenn Sie Numbers verwenden, die auch mit einer Nachrichten-Applikation verknüpft sind, validieren Sie das resultierende Routing in Ihrem Account, bevor Sie sich auf dieses Überschreibungsverhalten verlassen.

Versenden einer SMS (Ausgehende Nachrichten)

Endpunkt

Struktur der Anfrage

Messages API-Nutzdaten:

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

SMS API (Legacy) Nutzdaten:

from=Vonage
text=Hello from Vonage
to=447700900000

Hauptunterschiede im Anfragetext

Code-Schnipsel

Die folgenden Codeschnipsel enthalten das cURL-Beispiel und die verfügbaren Server-SDK-Beispiele für jede API.

Messages API Code-Schnipsel

curl -X POST https://api.nexmo.com/v1/messages \
  -H "Authorization: Bearer "$JWT\
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d $'{
    "to": "'${MESSAGES_TO_NUMBER}'",
    "from": "'${SMS_SENDER_ID}'",
    "channel": "sms",
    "message_type": "text",
    "text": "This is an SMS sent using the Vonage Messages API."
  }'

npm install @vonage/server-sdk @vonage/messages

const { Vonage } = require('@vonage/server-sdk');
const { Channels } = require('@vonage/messages');

/**
 * It is best to send messages using JWT instead of basic auth. If you leave out
 * apiKey and apiSecret, the messages SDK will send requests using JWT tokens
 *
 * @link https://developer.vonage.com/en/messages/technical-details#authentication
 */
const vonage = new Vonage(
  {
    applicationId: VONAGE_APPLICATION_ID,
    privateKey: VONAGE_PRIVATE_KEY,
  },
  {
    ...(MESSAGES_API_URL ? {apiHost: MESSAGES_API_URL} : {}),
  },
);

vonage.messages.send({
  messageType: 'sms',
  channel: Channels.SMS,
  text: 'This is an SMS text message sent using the Messages API',
  to: MESSAGES_TO_NUMBER,
  from: SMS_SENDER_ID,
})
  .then(({ messageUUID }) => console.log(messageUUID))
  .catch((error) => console.error(error));

implementation 'com.vonage:server-sdk-kotlin:2.1.1'

val client = Vonage {
    applicationId(VONAGE_APPLICATION_ID)
    privateKeyPath(VONAGE_PRIVATE_KEY_PATH)
}

val messageId = client.messages.send(
    smsText {
        to(MESSAGES_TO_NUMBER)
        from(SMS_SENDER_ID)
        text("This is an SMS text message sent using the Messages API")
    }
)

apply plugin: 'application'
mainClassName = project.hasProperty('main') ? project.getProperty('main') : ''

implementation 'com.vonage:server-sdk:9.3.1'

VonageClient client = VonageClient.builder()
		.applicationId(VONAGE_APPLICATION_ID)
		.privateKeyPath(VONAGE_PRIVATE_KEY_PATH)
		.build();

var response = client.getMessagesClient().sendMessage(
		SmsTextRequest.builder()
			.from(SMS_SENDER_ID).to(MESSAGES_TO_NUMBER)
			.text("This is an SMS text message sent using the Messages API")
			.build()
);
System.out.println("Message sent successfully. ID: " + response.getMessageUuid());

apply plugin: 'application'
mainClassName = project.hasProperty('main') ? project.getProperty('main') : ''

Install-Package Vonage

var credentials = Credentials.FromAppIdAndPrivateKeyPath(VONAGE_APP_ID, VONAGE_PRIVATE_KEY_PATH);

var vonageClient = new VonageClient(credentials);

var request = new Vonage.Messages.Sms.SmsRequest
{
    To = MESSAGES_TO_NUMBER,
    From = SMS_SENDER_ID,
    Text = "An SMS sent using the Vonage Messages API"
};

var response = await vonageClient.MessagesClient.SendAsync(request);

composer require vonage/client

pip install vonage python-dotenv

from vonage import Auth, Vonage
from vonage_messages import Sms

client = Vonage(
    Auth(
        application_id=VONAGE_APPLICATION_ID,
        private_key=VONAGE_PRIVATE_KEY,
    )
)

response = client.messages.send(
    Sms(
        to=MESSAGES_TO_NUMBER,
        from_=SMS_SENDER_ID,
        text='This is an SMS sent using the Vonage Messages API.',
    )
)
print(response)

gem install vonage

SMS API (Legacy) Codeschnipsel

curl -X POST https://rest.nexmo.com/sms/json \
  -u "$VONAGE_API_KEY:$VONAGE_API_SECRET" \
  -d "from=${SMS_SENDER_ID}" \
  -d "to=${SMS_TO_NUMBER}" \
  -d 'text=A text message sent using the Vonage SMS API'

npm install @vonage/server-sdk

const { Vonage } = require('@vonage/server-sdk');

const vonage = new Vonage({
  apiKey: VONAGE_API_KEY,
  apiSecret: VONAGE_API_SECRET,
});

vonage.sms.send({
  to: SMS_TO_NUMBER,
  from: SMS_SENDER_ID,
  text: 'A text message sent using the Vonage SMS API',
})
  .then((resp) => {
    console.log('Message sent successfully');
    console.log(resp);
  })
  .catch((err) => {
    console.log('There was an error sending the messages.');
    console.error(err);
  });

implementation 'com.vonage:server-sdk-kotlin:2.1.1'

val client = Vonage {
    apiKey(VONAGE_API_KEY)
    apiSecret(VONAGE_API_SECRET)
}

val response = client.sms.sendText(
    from = SMS_SENDER_ID,
    to = SMS_TO_NUMBER,
    message = "Hello from Vonage SMS API"
)

println(
    if (response.wasSuccessfullySent())
        "Message sent successfully."
    else
        "Message failed with error: ${response[0].errorText}"
)

apply plugin: 'application'
mainClassName = project.hasProperty('main') ? project.getProperty('main') : ''

implementation 'com.vonage:server-sdk:9.3.1'

VonageClient client = VonageClient.builder().apiKey(VONAGE_API_KEY).apiSecret(VONAGE_API_SECRET).build();

TextMessage message = new TextMessage(
        SMS_SENDER_ID, SMS_TO_NUMBER,
        "A text message sent using the Vonage SMS API"
);

SmsSubmissionResponse response = client.getSmsClient().submitMessage(message);

if (response.getMessages().get(0).getStatus() == MessageStatus.OK) {
    System.out.println("Message sent successfully.");
} else {
    System.out.println("Message failed with error: " + response.getMessages().get(0).getErrorText());
}

apply plugin: 'application'
mainClassName = project.hasProperty('main') ? project.getProperty('main') : ''

Install-Package Vonage

using Vonage;
using Vonage.Request;

var credentials = Credentials.FromApiKeyAndSecret(
    vonageApiKey,
    vonageApiSecret
    );

var vonageClient = new VonageClient(credentials);

var response = await vonageClient.SmsClient.SendAnSmsAsync(new Vonage.Messaging.SendSmsRequest()
{
    To = SMS_TO_NUMBER,
    From = SMS_SENDER_ID,
    Text = "A text message sent using the Vonage SMS API"
});
Console.WriteLine(response.Messages[0].To);

composer require vonage/client

pip install vonage python-dotenv

from vonage import Auth, Vonage
from vonage_sms import SmsMessage, SmsResponse

client = Vonage(Auth(api_key=VONAGE_API_KEY, api_secret=VONAGE_API_SECRET))

message = SmsMessage(
    to=SMS_TO_NUMBER,
    from_=SMS_SENDER_ID,
    text="A text message sent using the Vonage SMS API.",
)

response: SmsResponse = client.sms.send(message)
print(response)

gem install vonage

Optionale Parameter und Funktionsunterschiede

Sobald die erforderlichen SMS-Felder migriert sind, müssen im nächsten Schritt alle optionalen SMS API-Parameter überprüft werden, auf die Ihre Integration angewiesen ist.

HTTP-Antwort-Codes

Dies ist einer der wichtigsten Unterschiede im Verhalten der beiden APIs.

Die SMS API gibt immer ein 200 HTTP-Antwortcode, unabhängig von Erfolg oder Misserfolg, mit einer status Parameter im Antwortkörper, dessen Wert dem Ergebnis entspricht.

Die Messages API gibt ein 202 Antwortcode für erfolgreiche Anfragen, und 4xx oder 5xx Codes für Fehlerantworten.

Einige Beispiele sind in der nachstehenden Vergleichstabelle aufgeführt.

Siehe Messages API-Fehler, SMS API-Fehlercodesund die SMS API Sendeendpunkt für die vollständigen Fehlerdetails.

SMS API Erfolgsmeldung

{
  "message-count": "1",
  "messages": [
    {
      "to": "447700900000",
      "message-id": "0A0000000123ABCD1",
      "status": "0",
      "remaining-balance": "3.14159265",
      "message-price": "0.03330000",
      "network": "23410"
    }
  ]
}

SMS API-Fehlerantwort

{
  "message-count": "1",
  "messages": [
    {
      "status": "4",
      "error-text": "Bad Credentials"
    }
  ]
}

Messages API Erfolgsmeldung

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

Messages API Error Response (401 Unauthorized)

{
  "type": "https://developer.vonage.com/api-errors#unauthorized",
  "title": "Unauthorized",
  "detail": "You did not provide correct credentials.",
  "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}

Empfangen einer SMS (eingehende Nachrichten)

Beide APIs liefern eingehende SMS-Nachrichten an eine von Ihnen konfigurierte Webhook-URL. Es gibt einige Unterschiede zwischen den beiden APIs in der Struktur der eingehenden Nutzdaten und der Benennung der Parameter. Die Webhook-Einrichtung wird in Einrichten Ihres Vonage Accounts zur Verwendung der Messages API.

SMS API Eingehende Nutzdaten

Wenn eine Nachricht über die SMS API empfangen wird, sendet Vonage eine

Beispiel-Nutzlast:

{
  "msisdn": "447700900001",
  "to": "447700900000",
  "messageId": "0A0000000123ABCD1",
  "text": "Hello from a user",
  "type": "text",
  "keyword": "HELLO",
  "message-timestamp": "2020-01-01 12:00:00"
}

Messages API Eingehende Nutzdaten

Wenn eine Nachricht über die Messages API empfangen wird, sendet Vonage eine

Beispiel-Nutzlast:

{
   "channel": "sms",
   "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
   "to": "447700900000",
   "from": "447700900001",
   "timestamp": "2025-02-03T12:14:25Z",
   "text": "Hello From Vonage!",
   "sms": {
      "num_messages": "2",
      "keyword": "HELLO"
   },
   "usage": {
      "currency": "EUR",
      "price": "0.0333"
   },
   "origin": {
      "network_code": "12345"
   }
}

Verfolgung des Nachrichtenstatus

Die Messages API verwendet Status-Callbacks, um Ihre Anwendung zu benachrichtigen, wenn sich der Status einer Nachricht ändert. Diese sind das Messages API-Äquivalent zu den von der SMS API verwendeten Delivery Receipts (DLRs).

DLR-Status Äquivalente

Die nächstgelegenen Messages API-Äquivalente für SMS API DLR-Status sind unten aufgeführt:

Weitere Informationen finden Sie unter Messages API-Statusrückrufe.

Zusätzliche Funktionen der Messages API

Dieser Leitfaden konzentriert sich zwar auf die Migration Ihrer SMS-Integration, aber die Messages API bietet eine Reihe zusätzlicher Funktionen, die es wert sind, erkundet zu werden, sobald Ihre Migration abgeschlossen ist.

Multi-Channel-Messaging

Die Messages API unterstützt mehrere Kanäle über eine einzige, einheitliche API-Schnittstelle. Sobald Sie Ihre SMS-Integration migriert haben, können Sie neue Kanäle hinzufügen, ohne Ihre Kernintegration zu ändern:

Die Struktur der Anfrage ist für alle Kanäle gleich. Um eine Nachricht über einen anderen Kanal zu senden, ändern Sie das Kanalfeld und fügen alle kanalspezifischen Parameter hinzu. Ihr Webhook-Handler für Statusrückrufe und eingehende Nachrichten funktioniert unabhängig vom Kanal auf die gleiche Weise.

Ausfallsicherung

Die Messages API unterstützt Failover-Workflows, die es Ihnen ermöglichen, eine Nachricht automatisch auf einem anderen Kanal zu wiederholen, wenn der erste Versuch fehlschlägt oder nicht innerhalb eines bestimmten Zeitfensters gelesen wird. Sie können zum Beispiel eine WhatsApp-Nachricht senden und auf SMS zurückgreifen, wenn der Empfänger kein WhatsApp hat oder die Nachricht nicht innerhalb eines bestimmten Zeitraums liest.

Siehe Messages API Failover für weitere Informationen.

Reichhaltiger Inhalt

Auf Kanälen, die dies unterstützen (RCS, WhatsApp, MMS, Messenger, Viber), können Sie mit der Messages API senden:

• Bilder, Video, Audio und Dateianhänge
• Interaktive Nachrichtenvorlagen
• Vorgeschlagene Antwort- und Aktionsschaltflächen (RCS, WhatsApp)
• Reichhaltige Karten und Karussells (RCS)

Weitere Lektüre

• Messages API-Referenz
• Technische Details der Messages API
• Messages API Failover