Migration de l'API SMS vers l'API Messages

L'API Messages de Vonage est le moyen recommandé pour envoyer et recevoir des SMS. Elle prend en charge plusieurs canaux tels que les SMS, MMS, RCS et WhatsApp par le biais d'une interface unique et cohérente. Ce guide compare l'API SMS basée sur HTTP et l'API Messages pour les cas d'utilisation de SMS, et présente la configuration du compte, les demandes sortantes, les charges utiles entrantes et les changements de suivi de l'état que vous devez effectuer lors d'une migration. Il ne couvre pas les intégrations SMPP.

Configurer votre Account Vonage pour utiliser l'API Messages

Sélectionnez l'API Messages dans le tableau de bord.

La première étape de la migration de l'ancienne API SMS vers l'API Messages consiste à mettre à jour le fichier Type d'API Messages sur l'écran Paramètres de l'API page du tableau de bord du développeur Vonage. Sélectionnez Messages API en tant que Type d'API ici.

Si vous ne modifiez pas ce paramètre à partir de SMS API (legacy), les messages entrants et les accusés de réception continueront d'utiliser la configuration SMS API dans le tableau de bord.

Paramètres au niveau du compte et applications Vonage

Une fois que vous avez configuré votre Account pour qu'il utilise l'API Messages, vous devez décider de la manière dont vous souhaitez configurer les paramètres de l'API Messages. Il existe deux façons de procéder :

• Paramètres au niveau du compte
• Une application Vonage

Les principales différences entre les deux sont l'endroit où vous configurez les webhooks et les informations d'identification utilisées pour l'authentification (et donc les méthodes d'authentification disponibles). L'utilisation de l'API Messages avec des paramètres au niveau de l'Account est plus proche, en termes de configuration, de la manière dont les paramètres de l'API SMS sont configurés. Le tableau ci-dessous compare les différences de manière plus détaillée.

1. L'API SMS et l'API Messages permettent également de remplacer l'URL du webhook DLR/Status configuré pour chaque demande.
2. Nous vous recommandons vivement d'utiliser Messages API v1 pour votre migration. Veillez à ce que le fichier Version est fixé à v1 soit dans les paramètres de votre Account, soit dans toute application Vonage que vous créez (en fonction de l'approche de configuration que vous utilisez). Il s'agit de la valeur par défaut pour tous les nouveaux comptes Vonage, mais elle peut être réglée sur v0.1 sur les comptes plus anciens à des fins de rétrocompatibilité.

En général, nous vous recommandons d'utiliser les Applications Vonage pour votre intégration de l'API Messages en raison de leur flexibilité accrue et de l'utilisation des JWT pour l'authentification. Toutefois, étant donné que les paramètres au niveau du compte sont plus proches de l'approche utilisée par l'API SMS, vous pouvez envisager une approche en deux étapes pour votre migration, en passant d'abord aux paramètres au niveau du compte et à l'authentification de base pour l'API Messages avant d'utiliser les Applications Vonage.

Qu'est-ce qu'une application Vonage ?

Une Application Vonage peut être un nouveau concept pour les développeurs qui viennent de l'API SMS. Il s'agit essentiellement d'un conteneur pour la configuration et les informations d'identification. Ce n'est pas la même chose que votre application logicielle.

Chaque application Vonage contient :

• Un nom
• Un numéro d'identification unique pour l'application
• Une paire de clés publique/privée générée (utilisée pour l'authentification JWT)
• Paramètres supplémentaires spécifiques au produit. Pour l'API Messages, il s'agit notamment des URL des webhooks pour les messages entrants et les mises à jour de l'état des messages

L'API SMS n'utilise pas d'Applications. Les webhooks sont configurés globalement au niveau du compte. Bien que vous puissiez toujours utiliser les paramètres au niveau du compte avec l'API Messages si vous le souhaitez, il également prend en charge l'utilisation des Applications Vonage. Étant donné que chaque application dispose de sa propre configuration et de ses propres paramètres de webhook, cela facilite la gestion indépendante de plusieurs intégrations.

Pourquoi les Applications Vonage sont-elles recommandées ?

Le choix de l'approche de configuration dans l'API Messages affecte l'endroit où vos paramètres sont configurés ainsi que la méthode d'authentification utilisée.

Les Applications Vonage sont recommandées pour les raisons suivantes :

• Comme les paramètres sont définis au niveau de l'application Vonage et que vous pouvez créer de nombreuses applications, il est plus facile de gérer plusieurs intégrations pour différents flux de travail ou cas d'utilisation.
• Les Applications Vonage peuvent être créées et gérées par programmation à l'aide de la CLI ou de l'API de Vonage.
• Les Applications Vonage permettent l'utilisation de JWT, générés à l'aide d'une paire de clés publique/privée, pour l'authentification. Cela ajoute une couche de sécurité supplémentaire au processus d'authentification par rapport à l'authentification de base.

Utilisation des paramètres au niveau du Account

Si vous souhaitez utiliser des paramètres au niveau de l'Account avec les webhooks de l'API Messages, le processus de configuration de base est le suivant :

1. Ouvrir Paramètres de l'API dans le Tableau de bord.
2. Régler le Messages API version à v1.
3. Configurez les URL des webhooks de réception et d'état au niveau de l'Account.
4. Révision Vos Numbers pour toutes les dérogations d'entrée par numéro qui pourraient modifier le routage.
5. Envoyer des demandes de Messages API en utilisant l'authentification de base.
6. Validez que les messages entrants et les rappels d'état atteignent les points de terminaison prévus au niveau du Account avant de basculer le trafic de production.

Utilisation d'une application Vonage pour l'API Messages

Si vous souhaitez un routage au niveau de l'application et une authentification JWT, le flux de configuration est :

1. Créez une nouvelle application ou ouvrez l'application existante que vous souhaitez utiliser.
2. Activer le Messages capacité.
3. Configurez les URL des webhooks d'entrée et d'état de l'application.
4. Régler le Messages API version à v1.
5. Lier le numéro compatible avec les SMS à cette application.
6. Envoyez des demandes d'API Messages en utilisant l'authentification JWT.
7. Validez que les messages entrants et les rappels d'état atteignent les points de terminaison au niveau de l'application avant de basculer le trafic de production.

Créer une application API Vonage

Il existe trois méthodes alternatives pour créer une application Messages :

1. Utilisation de la CLI de Vonage
2. Utilisation du tableau de bord
3. Utilisation de l'API d'application

Chacune de ces méthodes est décrite dans les sections suivantes.

Comment créer une application de messages à l'aide de la CLI de Vonage

Pour créer votre application à l'aide de la CLI de Vonage, entrez la commande suivante dans l'interpréteur de commandes :

Cette commande crée une application Vonage API avec un message capacitéet les URL des webhooks sont configurées comme indiqué. Il génère également un fichier de clé privée my_messages_app.key et crée ou met à jour le vonage_app.json fichier.

Comment créer une application Messages à l'aide du tableau de bord

Vous pouvez créer une application Applications dans le module Tableau de bord.

Pour créer votre application à l'aide du tableau de bord :

1. Sous Applications dans le tableau de bord, cliquez sur le bouton Créer une nouvelle application bouton.

2. Sous Nom, saisissez le nom de l'Applications. Choisissez un nom pour faciliter les références futures.

3. Cliquez sur le bouton Générer une clé publique et une clé privée. Cela créera une paire de clés publique/privée et la clé privée sera téléchargée par votre navigateur.

4. Sous Capacités sélectionner le Messages bouton.

5. Dans le cadre de la URL entrant entrez l'URL de votre webhook de messages entrants, par exemple, https://example.com/webhooks/inbound-message.

6. Dans le cadre de la URL de l'état entrez l'URL de votre webhook sur l'état des messages, par exemple, https://example.com/webhooks/message-status.

7. Cliquez sur le bouton Générer une nouvelle application bouton. Vous passez à l'étape suivante de la procédure de création d'une application, où vous pouvez associer un numéro API de Vonage à l'application, et lier des comptes externes tels que Facebook à cette application.

8. S'il existe un Account externe auquel vous souhaitez lier cette application, cliquez sur le bouton Comptes externes liés et cliquez sur l'onglet correspondant Lien pour le compte auquel vous voulez vous relier.

Vous avez maintenant créé votre application.

Comment créer une application Messages à l'aide de l'API d'application

L'API d'application vous permet de créer et de configurer une application Vonage de manière programmatique - sans utiliser le tableau de bord ou la CLI. Une application Vonage créée via l'API d'application fonctionne de la même manière qu'une application créée via le tableau de bord.

Pour une présentation complète de la création d'une application Vonage, voir Créer une application Vonage.

Associer un numéro de téléphone à votre Applications

Dans le tableau de bord, ouvrez la fenêtre Applications pagesélectionnez l'application que vous souhaitez utiliser et associez le numéro de l'application en question au numéro de téléphone de l'application. Numbers de liens tabulation.

Vous pouvez également gérer les paramètres du webhook entrant spécifiques à un numéro à partir de Vos Numbers. Le tableau de bord indique qu'un webhook entrant par numéro a priorité sur le webhook entrant au niveau du compte. Si vous utilisez des numéros qui sont également liés à une application Messages, validez l'acheminement qui en résulte dans votre Account avant de vous fier à ce comportement prioritaire.

Envoi d'un SMS (messages sortants)

Point final

Structure de la demande

Messages API :

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

Charge utile de l'API SMS (ancienne) :

from=Vonage
text=Hello from Vonage
to=447700900000

Principales différences dans le corps de la demande

Extraits de code

Les extraits de code suivants comprennent l'exemple cURL et les exemples de SDK serveur disponibles pour chaque API.

Extraits de code de l'API Messages

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

Extraits de code de l'API SMS (ancienne)

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

Paramètres optionnels et différences de caractéristiques

Une fois les champs SMS obligatoires migrés, l'étape suivante consiste à passer en revue tous les paramètres API SMS facultatifs sur lesquels repose votre intégration.

Codes de réponse HTTP

Il s'agit de l'une des différences de comportement les plus significatives entre les deux API.

L'API SMS renvoie toujours une valeur de 200 Code de réponse HTTP, qu'il s'agisse d'un succès ou d'un échec, avec un code status dans le corps de la réponse, dont la valeur correspond au résultat.

L'API Messages renvoie un fichier 202 le code de réponse pour les demandes réussies, et 4xx ou 5xx codes pour les réponses d'erreur.

Quelques exemples sont présentés dans le tableau comparatif ci-dessous.

Voir Messages API errors (en anglais), Codes d'erreur de l'API SMSet le Point de terminaison d'envoi de l'API SMS pour connaître tous les détails de l'erreur.

Réponse positive de l'API SMS

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

Réponse d'erreur de l'API SMS

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

Messages API Success Response (Réponse de réussite de l'API)

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

Messages API Réponse d'erreur (401 non autorisé)

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

Réception d'un SMS (messages entrants)

Les deux API envoient des SMS entrants à l'URL d'un webhook que vous avez configuré. Il existe quelques différences entre les deux API au niveau de la structure de la charge utile entrante et de la dénomination des paramètres. La configuration du webhook est abordée dans la section Configurer votre Account Vonage pour utiliser l'API Messages.

Charge utile entrante de l'API SMS

Lorsqu'un message est reçu sur l'API SMS, Vonage envoie une requête

Exemple de charge utile :

{
  "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 Charge utile entrante

Lorsqu'un message est reçu sur l'API Messages, Vonage envoie une requête

Exemple de charge utile :

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

Suivi de l'état des messages

L'API Messages utilise des rappels d'état pour informer votre application lorsque l'état d'un message change. Il s'agit de l'équivalent pour l'API Messages des accusés de réception (DLR) utilisés par l'API SMS.

Équivalents de statut DLR

Les équivalents les plus proches de l'API Messages pour les statuts DLR de l'API SMS sont indiqués ci-dessous :

Pour plus d'informations, voir Messages API Callbacks d'état.

Fonctionnalités supplémentaires de l'API Messages

Bien que ce guide se concentre sur la migration de votre intégration SMS, l'API Messages offre un certain nombre de fonctionnalités supplémentaires qui méritent d'être explorées une fois la migration terminée.

Messagerie multicanal

L'API Messages prend en charge plusieurs canaux par le biais d'une interface API unique et cohérente. Une fois que vous avez migré votre intégration SMS, vous pouvez ajouter de nouveaux canaux sans modifier votre intégration principale :

La structure de la demande est cohérente d'un canal à l'autre. Pour envoyer un message sur un autre canal, vous devez modifier le champ du canal et ajouter les paramètres spécifiques au canal. Votre gestionnaire de webhook pour les rappels d'état et les messages entrants fonctionne de la même manière quel que soit le canal.

Basculement

L'API Messages prend en charge les flux de travail de basculement, qui vous permettent de réessayer automatiquement un message sur un canal différent si la première tentative échoue ou n'est pas lue dans une fenêtre de temps spécifiée. Par exemple, vous pouvez envoyer un message WhatsApp et revenir au SMS si le destinataire n'a pas WhatsApp ou ne lit pas le message dans un délai donné.

Voir Messages API Failover (basculement de l'API) pour plus d'informations.

Un contenu riche

Sur les canaux qui la prennent en charge (RCS, WhatsApp, MMS, Messenger, Viber), l'API Messages permet d'envoyer :

• Images, vidéo, audio et pièces jointes
• Modèles de messages interactifs
• Boutons de réponse et d'action suggérés (RCS, WhatsApp)
• Cartes et carrousels riches (RCS)

Pour en savoir plus

• Référence de l'API Messages
• Détails techniques de l'API Messages
• Messages API Failover (basculement de l'API)