Partager:
){kind=small}
Ancien rédacteur technique chez Vonage. Aime jouer avec les API et les documenter.
Réception des accusés de réception de SMS avec Java et Spark
Vous avez appris comment envoyer un message texte à partir de votre numéro virtuel Vonage à l'aide de l'API SMS. Tout semble bien se passer : votre application ne contient pas d'erreur et l'API renvoie status: 0Vous êtes donc certain que votre message a été envoyé.
Mais, à moins d'avoir un accès direct à l'appareil associé à ce numéro, comment pouvez-vous être sûr qu'il a été livré ?
La bonne nouvelle, c'est que de nombreux réseaux utilisés par Vonage pour acheminer votre message fourniront un reçu de livraison. Vous pouvez accéder à ce récépissé de manière programmatique, et c'est ce que nous allons vous montrer dans cet article.
La mauvaise nouvelle, c'est que les accusés de réception des réseaux ne constituent pas tous une preuve irréfutable que votre message a bien été livré, les opérateurs étant plus fiables dans certains pays que dans d'autres.
Certains transporteurs vous diront qu'ils ont reçu votre message, mais ne confirmeront pas s'il est arrivé à destination. D'autres produisent de faux reçus. D'autres n'envoient aucun reçu.
Donc, avant de vous fier aux reçus de livraison comme étant une source de vérité, consultez la Base de connaissances de Vonage pour obtenir des informations spécifiques à chaque pays.
Pour demander un récépissé de livraison, vous devez créer un webhook accessible au public et configurer votre Account Vonage pour l'utiliser. Nous utiliserons Java et le cadre web Spark web framework pour créer le webhook. Vous pouvez trouver le code de ce tutoriel sur GitHub.
Le JDK ou son équivalent open source OpenJDK. Ce tutoriel a été écrit avec OpenJDK 11, mais la version 8 ou supérieure de l'un ou l'autre devrait convenir.
Gradle (version 3.4 ou ultérieure) pour construire votre projet et gérer ses dépendances.
ngrok pour rendre votre webhook disponible sur l'internet public.
To complete this tutorial, you will need a Vonage API account. If you don’t have one already, you can sign up today and start building with free credit. Once you have an account, you can find your API Key and API Secret at the top of the Vonage API Dashboard.
This tutorial also uses a virtual phone number. To purchase one, go to Numbers > Buy Numbers and search for one that meets your needs.
Créez un répertoire pour votre projet appelé get-delivery-receipt, passez dans ce répertoire et utilisez ensuite gradle pour initialiser le projet :
Acceptez tous les paramètres par défaut, puis ouvrez le projet généré dans votre IDE.
Localisez le fichier build.gradle et modifiez le référentiel de dépendances de jcenter() à mavenCentral():
repositories {
mavenCentral()
}Remplacer la section dependencies par le texte suivant :
dependencies {
// Spark framework
implementation 'com.sparkjava:spark-core:2.8.0'
// Vonage client library
implementation 'com.nexmo:client:4.4.0'
// To display formatted JSON
implementation 'com.cedarsoftware:json-io:4.10.1'
}
Gradle a créé la classe App dans le dossier src/main/java/get/delivery/receipt dans le dossier
Ouvrez App.java dans votre IDE. Supprimez la méthode getGreeting() qui a été créée pour vous gradle a créée pour vous et ajoutez les déclarations import nécessaires pour les spark et JsonWriter nécessaires pour les paquets.
Ensuite, appelez la méthode port pour indiquer que votre application écoute les requêtes sur le port 3000.
Votre App.java devrait ressembler à ceci :
package get.delivery.receipt;
import static spark.Spark.*;
import com.cedarsoftware.util.io.JsonWriter;
public class App {
public static void main(String[] args) throws Exception {
port(3000);
// Your code goes here
}
}
Lorsque Vonage reçoit un récépissé de livraison d'un transporteur, il vérifie la configuration de votre compte pour voir si vous avez fourni l'URL d'un point de terminaison webhook. Si c'est le cas, Vonage envoie une requête à ce point de terminaison avec les informations relatives au récépissé de livraison.
Par défaut, il s'agit d'une GET nous allons donc coder cela en premier. Le point d'accès que nous allons exposer est /webhooks/delivery-receipt.
Ajoutez ce qui suit à votre méthode main méthode :
get("/webhooks/delivery-receipt", (req, res) -> {
System.out.println("DLR received via GET");
for (String param : req.queryParams()) {
System.out.printf("%s: %s\n", param, req.queryParams(param));
}
res.status(204);
return "";
});
Ce code intercepte les requêtes GET sur votre point d'accès, supprime l'information de réception de la chaîne de requête et l'écrit dans le fichier stdout. Il renvoie ensuite le code d'état HTTP 204 pour indiquer aux API de Vonage que la demande a abouti, mais qu'il ne faut pas s'attendre à du contenu dans la réponse.
Vous pouvez également configurer votre Account Vonage de manière à ce que Vonage fournisse le récépissé de livraison par une POST soit sous la forme d'une URL codée, soit sous la forme d'un fichier JSON.
Pour que votre application puisse accepter soit GET ou POST ajoutez le code suivant à App.java:
post("/webhooks/delivery-receipt", (req, res) -> {
if (req.contentType().startsWith("application/x-www-form-urlencoded")) {
System.out.println("DLR received via POST");
for (String param : req.queryParams()) {
System.out.printf("%s: %s\n", param, req.queryParams(param));
}
} else {
System.out.println("DLR received via POST-JSON");
String prettyJson = JsonWriter.formatJson(req.body());
System.out.println(prettyJson);
}
res.status(204);
return "";
});
C'est tout le code dont vous avez besoin pour capturer les accusés de réception, quelle que soit la méthode HTTP utilisée par Vonage pour les envoyer.
Vous devez rendre votre webhook accessible aux API de Vonage. Une bonne façon de le faire pendant le développement est d'utiliser ngrok. Pour en savoir plus, lisez notre article de blog sur ngrok.
Téléchargez et installez ngrokpuis exécutez la commande suivante pour exposer votre application sur le port 3000 à l'Internet public :
Notez les URL publiques que ngrok et laissez-le fonctionner pendant la durée de ce tutoriel (parce qu'il vous donne une nouvelle URL aléatoire à chaque fois que vous le lancez, à moins que vous ne souscriviez à un plan plan payant) :
Terminal showing the ngrok URLs
Maintenant que vous avez une URL pour votre webhook, vous devez indiquer à Vonage de l'utiliser.
Se connecter au tableau de bord du développeur et sous le nom de votre Account dans le menu de navigation de gauche, sélectionnez "Paramètres".
Dans la partie droite de cette page, sous "Paramètres SMS par défaut", saisissez l'URL complète de votre webhook (ngrok URL plus /webhooks/delivery-receipt) et cliquez sur "Enregistrer les modifications". Notez l'option permettant d'être informé des accusés de réception via POST au lieu de la méthode par défaut GET au lieu de la méthode HTTP par défaut :
Setting the delivery receipt webhook URL in the developer dashboard
Tout est prêt ! Vous pouvez maintenant le tester.
Exécutez votre application Java à partir du répertoire de votre application :
Envoyez un message test à votre numéro de téléphone mobile personnel.
Lorsque Vonage reçoit un accusé de réception du réseau, il le transmet à votre application qui l'affiche :
Modifier la méthode HTTP dans la page page des paramètres du tableau de bord à l'une des méthodes POST et envoyez un autre SMS pour vous assurer que votre application peut toujours récupérer les informations relatives à l'accusé de réception. Par exemple, POST-JSON:
DLR received via POST-JSON
{
"msisdn":"447700900005",
"to":"NEXMOTEST",
"network-code":"23420",
"messageId":"140023462904E8",
"price":"0.03330000",
"status":"delivered",
"scts":"1907171217",
"err-code":"0",
"message-timestamp":"2019-07-17 11:17:52"
}
Dans ce tutoriel, vous avez appris à créer une application Java avec le framework Spark pour récupérer un reçu de livraison de Vonage à l'aide de l'API SMS. Le webhook que vous avez codé était capable d'extraire le reçu de livraison quelle que soit la méthode HTTP utilisée pour effectuer la requête.