Avec les progrès de la technologie, la notification est devenue un processus en une seule étape. L’époque où les gens se rappelaient les événements ou autres occasions par le bouche-à-oreille est révolue. La messagerie est une méthode de notification plus efficace et plus fiable. Si Harry a un rendez-vous prévu à 18 heures le mercredi, nous pouvons lui envoyer une confirmation la veille, suivie d’un rappel une heure avant. Harry a un emploi du temps chargé. En le prévenant, il se rappellera qu’il est attendu à son rendez-vous.
Ce tutoriel couvre les points suivants :
- Envoi d’un message à l’aide de métadonnées et programmation d’un message
- Vérification de l’état d’un message
- Vérification des réponses aux messages
- Vérification des rapports de livraison
- Confirmation de la réception d’une réponse et accusé de réception une fois qu’elle a été traitée
- Mise en œuvre des webhooks
Si vous êtes bloqué sur une section à un moment donné, vous pouvez consulter le code dans ce dépôt pour vous aider.
Prérequis
Pour suivre ce tutoriel, vous aurez besoin des éléments suivants :
Installation du SDK Messages Ruby
Pour cette partie, vous aurez besoin d’un éditeur de code comme Sublime Text. Nous utiliserons Ruby pour développer notre application, vous devrez donc vous assurer que vous l’avez également installé sur votre machine. Créez maintenant un dossier vide pour votre projet, que nous nommerons « testApp ». Maintenant, ouvrez votre invite de commande, accédez au répertoire et exécutez la commande suivante pour installer le SDK Messages :
gem install messagemedia_messages_sdk
Envoi d’un message
Créez un fichier app.rb dans ce dossier et ouvrez-le dans votre éditeur. Écrivez le code suivant. Nous l’avons également commenté pour que vous puissiez comprendre ce qui se passe à chaque ligne.
require ’message_media_messages.rb’ # Cette gemme contient toute la logique pour traiter avec l’API de messagerie MessageMedia
require ’pp’ # Cette gemme permet d’afficher un ’joli’ JSON
def setup
# Les identifiants nécessaires pour accéder à l’API de messagerie
auth_user_name = ’API_KEY’
auth_password = ’API_SECRET’
use_hmac = false # Changez ce paramètre en true si vous utilisez des clés HMAC
# Instanciation du client
client = MessageMediaMessages::MessageMediaMessagesClient.new(
auth_user_name: auth_user_name,
auth_password: auth_password,
use_hmac: use_hmac
)
return client
end
def send_message
client = setup();
# Création de la structure du message
messages = client.messages
body_value = ’{
"messages":[
{
"content":"Bonjour Harry, vous avez un rendez-vous avec le Dr George aujourd’hui à 18h00. Répondez O pour confirmer ou N pour annuler.",
"destination_number":"MOBILE_NUMBER",
"metadata": {
"name": "Ibrahim"
},
"scheduled": "2018-04-30T11:49:02.807Z",
"delivery_report": "true"
}
]
}’;
# Analyse du corps du message et conversion en objet Ruby
body = JSON.parse(body_value);
# Enfin, envoi du message
result = messages.create_send_messages(body)
# Affichage de la réponse dans la console
pp result
end
# Appel de la fonction send_message
send_message
Nous avons programmé l’envoi du message un jour avant le rendez-vous de Harry, et nous avons également inclus quelques métadonnées dans le corps du message. Les métadonnées peuvent être utilisées lorsque vous ne souhaitez pas stocker de données persistantes dans l’application. Un message peut contenir jusqu’à 10 paires de métadonnées clé/valeur. Avant d’envoyer le message, ajoutez vos identifiants API et le numéro de Harry (+61491570156). Vous pouvez désormais effectuer l’envoi !
Voici à quoi devrait ressembler une réponse réussie.
Vérification de l’état du message
Le message envoyé est mis en file d’attente (vérifiez le statut de la capture d’écran ci-dessus). Vous ne savez pas quand et si le message a été réellement envoyé à partir de la réponse initiale de l’API. Nous pouvons en savoir plus en vérifiant le statut du message à l’aide du message ID qui se trouve dans l’objet de la réponse.
Ajoutons un peu de code pour vérifier le statut du dernier message que nous avons envoyé.
def check_status
client = setup()
messages = client.messages
message_id = ’YOUR_MESSAGE_ID’
result = messages.get_message_status(message_id)
print result.inspect
end
# Appel de la fonction check_status
check_status
N’oubliez pas de remplacer l’espace réservé au messageID par un véritable messageID. Dans notre cas, il s’agissait de fbbe1ae6-8ad7-441d-bc4c-551880911e2b. Voici la réponse que nous avons reçue :
La structure de la réponse est très similaire à celle de send_message. Vous pouvez voir dans la réponse que le message est actuellement programmé pour être délivré. Espérons qu’Harry ne manquera pas son rendez-vous. Pour nous en assurer, nous lui enverrons un autre rappel dans la section suivante, où nous verrons comment vérifier les réponses.
Vérification des réponses
Les réponses envoyées à partir d’un appareil s’affichent lorsque nous appelons la fonction de réponse. Essayons donc d’envoyer un message à Harry à partir de notre téléphone portable.
Ajoutons maintenant un peu de code pour vérifier les réponses.
def check_replies
client = setup()
replies = client.replies
result = replies.get_check_replies()
print result.inspect
end
# Appel de la fonction check_replies
check_replies
Chaque demande de vérification des réponses renvoie toutes les réponses reçues qui n’ont pas encore été confirmées à l’aide d’un autre point de terminaison similaire aux réponses, appelé confirm replies (réponses de confirmation). Une réponse du point de terminaison de vérification des réponses aura la structure indiquée ci-dessous.
Vérification des rapports de livraison
Les rapports de livraison sont une notification du changement de statut d’un message en cours de traitement.
Chaque demande de vérification des rapports de livraison renvoie tous les rapports de livraison reçus qui n’ont pas encore été confirmés à l’aide du point final de confirmation des rapports de livraison.
Ajoutons maintenant du code pour vérifier les rapports de livraison.
def check_delivery_reports
client = setup()
deliveryReports = client.delivery_reports
result = deliveryReports.get_check_delivery_reports()
pp result
end
# Appelez check_delivery_reportsfunction
check_delivery_reports
Une réponse provenant du point de terminaison de vérification des rapports de livraison aura la structure suivante.
Confirmation des réponses et des rapports de livraison
Le point de terminaison de confirmation des réponses est destiné à être utilisé conjointement avec le point de terminaison de vérification des réponses, afin de permettre un traitement robuste des messages de réponse. Une fois qu’un ou plusieurs messages de réponse ont été traités, ils peuvent être confirmés à l’aide du point de terminaison « confirm replies », de sorte qu’ils ne sont plus renvoyés dans les demandes ultérieures de vérification des réponses. Le point de terminaison de confirmation des rapports de livraison fonctionne exactement de la même manière, mais avec le point de terminaison de vérification des rapports de livraison.
Le point final de confirmation des réponses prend une liste d’identifiants de réponse comme suit :
{
"reply_ids": [
"011dcead-6988-4ad6-a1c7-6b6c68ea628d",
"3487b3fa-6586-4979-a233-2d1b095c7718",
"ba28e94b-c83d-4759-98e7-ff9c7edb87a1"
]
}
Le point de terminaison de confirmation des rapports de livraison prend une liste d’ID de rapports de livraison comme suit :
{
"delivery_report_ids": [
"011dcead-6988-4ad6-a1c7-6b6c68ea628d",
"3487b3fa-6586-4979-a233-2d1b095c7718",
"ba28e94b-c83d-4759-98e7-ff9c7edb87a1"
]
}
Il est probable que vous interrogiez le point de terminaison de vérification des réponses ou de vérification des rapports de livraison pour obtenir des résultats. Comme vous pouvez le constater, cela peut devenir très vite fastidieux. Pourquoi ? Vous devrez interroger le point de terminaison pour chaque demande d’envoi de message que vous ferez. Pour 1 000 messages envoyés, il y aura 1 000 demandes pour chaque point de terminaison. Il n’est pas recommandé de traiter les réponses ou les rapports séparément. Au lieu de cela, vous pouvez utiliser les webhooks. Un webhook est une URL. Si une application web implémente ce webhook, des messages peuvent être envoyés à cette URL lorsque certains événements se produisent.
En utilisant les webhooks, vous pouvez recevoir automatiquement les modifications de statut du message, les réponses au message ou les rapports de livraison reçus pour le message.
Webhooks
Pour activer les webhooks, il suffit de spécifier un paramètre callback_url dans le corps du message de votre fonction send_message.
"messages":[
{
"content":"Rappel : vous avez un rendez-vous aujourd’hui.",
"destination_number":"+61491570156",
"metadata": {
"name": "Ibrahim"
},
"delivery_report": "true",
"callback_url": "https://my.callback.url.com"
}
]
Personnellement, j’aime tester les invocations de rappel sur un site web appelé Webhook Tester. Ce site web vous permet de tester facilement les webhooks et d’autres types de requêtes HTTP. Il enregistre instantanément toutes les requêtes envoyées à cette URL et, surtout, vous n’avez pas besoin de rafraîchir la page.
Essayons d’envoyer un message en utilisant un callback_url à partir de Webhook Tester. Pour obtenir une URL de rappel, visitez Webhook Tester et copiez l’URL unique qui devrait être générée pour vous sur la landing page.
Modifions le corps de notre message pour ajouter la prise en charge du callback_url. Le corps de votre message devrait être le suivant. J’ai ajouté mon callback_url.
"messages":[
{
"content":"Rappel : vous avez un rendez-vous aujourd’hui.",
"destination_number":"+61491570156",
"metadata": {
"name": "Ibrahim"
},
"delivery_report": "true",
"callback_url": "https://webhook.site/d49c3883-c1fd-4cf5-8977-52a4ea57ddc2"
}
]
Quelques secondes après avoir invoqué la fonction send_message, vous devriez voir quelque chose de similaire sur l’écran de Webhook Tester.
Dans la partie gauche de l’écran, vous trouverez plusieurs demandes. Il s’agit de vos rapports de livraison. Chacun d’entre eux aura un statut différent. Ils montrent comment le statut du message change lorsqu’il passe de l’expéditeur à notre passerelle, au transporteur et enfin au destinataire. Pour obtenir une vue plus jolie de l’objet réponse, cochez la case « Format JSON » tout en haut de l’écran, juste sous la barre de navigation.
Voici un extrait d’un de mes rapports de livraison :
Conclusion
Harry se rend à son rendez-vous. Il l’aurait oublié si vous n’aviez pas été là. Vous avez non seulement veillé à ce qu’Harry se présente, mais vous avez aussi beaucoup appris en cours de route. Bon travail !
Obtenir le code
Tout le code de ce tutoriel est disponible dans le dépôt Github du tutoriel Ruby Messaging.
Ressources