Recevoir un statut de message SMS avec Ruby on Rails

Précédemment, nous avons appris comment envoyer des SMS en utilisant l'intégration SMS de Ruby on Rails. Cependant, l'envoi d'un SMS ne doit pas donner l'impression d'envoyer un message dans une bouteille. Avec les applications Ruby on Rails SMS, nous pouvons suivre la livraison des messages et garantir leur fiabilité. Heureusement, nous obtenons tout cela et bien plus encore grâce à l'API Messages et à la fonction SMS Message Status.

Ce tutoriel vous montrera comment intégrer les statuts de livraison des SMS dans une application Ruby on Rails en utilisant les webhooks de Vonage.

TL;DR Passez à l'étape suivante et trouvez tout le code de code de démarrage rapide sur GitHub.

Conditions préalables

• Un Account ngrok

• Numéro virtuel Vonage

• Application Ruby on Rails, comme décrit précédemment

Qu'est-ce qu'un statut de message SMS ?

Lorsque vous lancez une demande d'envoi de SMS, il ne s'agit que de la première étape de son parcours. Si votre demande d'envoi de SMS est acceptée, Vonage mettre en file d'attente le SMS tout en recherchant le meilleur fournisseur de réseau pour l'acheminer. À partir de là, le fournisseur de réseau répondra à la demande et enverra le SMS à son destinataire.

Diagram explaining SMS Message Status, showing how messages travel from an application through Vonage and carriers to the user, with delivery status callbacks.

Ensuite, un statut de message (MS) est envoyé dans l'ordre inverse (Network Provider -> Vonage -> Your App) pour indiquer si le SMS a été délivré avec succès ou non.

Pour recevoir ce MS dans votre application, vous devrez configurer un point de terminaison webhook indiquant à Vonage où l'envoyer.

Comment exposer publiquement notre application Ruby on Rails avec ngrok

Vonage devra envoyer les statuts de nos messages à un point de terminaison. Notre application Ruby on Rails est exécutée en développement sur le port 3000, nous pouvons donc y accéder localement à l'adresse localhost:3000. Cependant, cela ne fonctionne que sur notre ordinateur !

Vous pouvez utiliser ngrok pour exposer publiquement et en toute sécurité votre serveur local via HTTP. Ainsi, dans un onglet séparé de votre serveur rails, ouvrez un tunnel ngrok sur le port 3000.

ngrok http 3000

Assurez-vous d'ajouter votre URL ngrok en tant que config.host dans votre fichier development.rb. Nous allons utiliser la variable d'environnement VONAGE_SERVER_HOSTNAMEpour rendre notre application plus dynamique.

Pour plus d'aide, voir comment démarrer et utiliser ngrok dans Rails.

# config/environments/development.rb

Rails.application.configure do
   config.hosts << ENV['VONAGE_SERVER_HOSTNAME']

Maintenant, dans notre fichier .env, mettez votre 'VONAGE_SERVER_HOSTNAME' à votre URL ngrok.

# .env

# ngrok URL, don't include the protocol (https://)
VONAGE_SERVER_HOSTNAME=''

Nous devrons également modifier notre application Vonage (de l'article précédent) dans le tableau de bord pour ajouter l'URL ngrok dans nos webhooks. Dans le champ Status URL, ajoutez votre URL ngrok suivie de /sms_message_status.

Vonage Messages API webhook settings showing an invalid Inbound URL error.Une fois que vous aurez appuyé sur save, ngrok transmettra les Applications faites au point de terminaison /sms_message_status à votre application Rails ! Mais il y a un petit problème : notre application Rails n'a pas ce point de terminaison.

Comment gérer les Webhooks de réception de livraison dans Rails

Maintenant que Vonage transmet les statuts au point de terminaison /sms_delivery_receipts mettons à jour notre application et créons une route pour le gérer.

# config/routes.rb
Rails.application.routes.draw do

 # For SmsMessageStatus controller, create
  post '/sms_message_status', to: 'sms_message_status#create', as: :sms_message_status

	...previous routes...

Mais que va-t-il se passer ici ? Notre application va accepter l'état du message et l'analyser pour en extraire les informations pertinentes. Vous pouvez voir à quoi ressemble un état de message typique :

{
"to"=>"13215678899",
"from"=>"John",
"channel"=>"sms",
"message_uuid"=>"93cc5afe-2824-4d40-97b1-e6f6ec00249e", 
"timestamp"=>"2025-02-23T14:52:53Z",
"status"=>"delivered", 
"destination"=> {"network_code"=>"42507"}
}

Le champ le plus important est le champ état car il vous indique si votre message a été délivré et, si ce n'est pas le cas, ce qui s'est passé. Voir plus d'informations sur Statut du message les webhooks.

Nous allons créer une logique pour mettre à jour le statut de notre SMS en fonction des statuts des messages reçus. Générons un nouveau contrôleur dans la ligne de commande pour gérer cela.

rails g controller SmsMessageStatus create

Notre contrôleur a une seule méthode simple create simple. Tout d'abord, la méthode analyse l'état de notre message et extrait le message_uuid ; elle utilise cet identifiant étranger pour trouver le SMS dans notre base de données locale. Elle met ensuite à jour l'état de ce SMS en fonction de l'état actuel que nous avons reçu dans l'état du message.

class SmsMessageStatusController < ApplicationController
  skip_before_action :verify_authenticity_token

  def create
   SmsMessage.where(message_uuid: params[:sms_message_status][:message_uuid])
       .update_all(status: params[:sms_message_status][:status]) if params[:sms_message_status][:message_uuid]

    # Return an empty HTTP 200 status
    head :ok
  end
end

Vous pouvez maintenant envoyer un SMS et observer votre serveur rails pour voir que le webhook est appelé, transmis, et qu'ActiveRecord met à jour la base de données !

Console log showing the processing of an SMS delivery receipt in a Vonage Rails application, including a database update query.

Conclusion

Vous avez réussi ! Vous avez appris à exposer votre application Ruby on Rails à l'écoute d'un webhook via ngrok, en mettant à jour votre base de données au passage ! Nous continuerons à développer cette application en acceptant les SMS entrants dans le prochain article.

Si vous avez des questions ou des suggestions pour plus de contenu Ruby, envoyez-nous un message sur le Communauté Slack. Vous pouvez également rester au courant de notre contenu et de nos événements pour les développeurs sur X, anciennement connu sous le nom de Twitter.