Recevoir les événements d'un appel Voice avec Ruby on Rails

Précédemment, nous avons appris comment effectuer des appels sortants en utilisant l'intégration Ruby on Rails Voice. Cependant, beaucoup de choses peuvent se produire lorsque vous essayez de passer un appel téléphonique. L'appel a-t-il abouti ? Le destinataire a-t-il décroché ? Le téléphone a-t-il même sonné ? Avec les applications Voice de Ruby on Rails, nous pouvons suivre l'état des appels de manière programmatique grâce à l'API Voice et à la fonction Crochet Web des événements d'appel.

Ce tutoriel vous montrera comment intégrer des événements d'appels vocaux 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

Vonage API Account

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.

Ready to start building?

Experience seamless connectivity, real-time messaging, and crystal-clear voice and video calls—all at your fingertips.

Qu'est-ce qu'un événement d'appel ?

Lorsque vous passez un appel vocal à l'aide de l Voice APIla plateforme ne se contente pas d'envoyer l'appel et de l'oublier ; elle suit tout ce qui se passe au cours de l'appel, étape par étape. Chaque action importante au cours du cycle de vie de l'appel déclenche un événement d'appel.

Un événement d'appel est une notification en temps réel qui indique à votre application ce qui se passe avec l'appel. Par exemple, un événement d'appel est une notification en temps réel :

• Lorsque l'appel est créé, vous obtiendrez un démarré l'événement.

• Lorsque le téléphone commence à sonner, vous obtenez une sonnerie de sonnerie. Lorsque l'appel est pris, vous obtenez un événement répondu événement.

• Si la ligne est occupée, si l'appel est rejeté ou si l'appel échoue pour une raison quelconque, vous obtiendrez des événements tels que occupé, rejetéou échoué.

Chacun de ces événements est envoyé à votre serveur par l'intermédiaire d'un crochet web afin que vous puissiez réagir de manière programmatique. Vous pouvez mettre à jour une interface utilisateur, enregistrer les détails d'un appel, déclencher une réponse automatisée ou gérer la facturation.

Pour capturer ces événements, vous devrez configurer une URL de webhook d'événement lors de la configuration de votre appel Voice API. De cette façon, Vonage POSTERA automatiquement les données détaillées de l'événement sur votre serveur au fur et à mesure que l'appel passe par les différentes étapes.

Comment exposer publiquement notre application Ruby on Rails avec Ngrok

Suite de l'article de blog billet précédentNotre application Ruby on Rails s'exécute 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

Veillez à ajouter l'URL de votre ngrok en tant qu'élément de config.host dans votre fichier development.rb. Nous utiliserons 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, définissez votre VONAGE_SERVER_HOSTNAME à l'URL de ngrok.

# .env

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

Modifiez votre application Vonage du tutoriel précédent dans le le tableau de bord pour ajouter l'URL ngrok dans vos webhooks. Dans le champ Status URL, ajoutez votre URL ngrok suivie de /call_events. Assurez-vous que la requête est envoyée en tant que POST.

Configuring Voice API webhooks in the Vonage dashboard with answer, event, and fallback URLs

Une fois que vous aurez appuyé sur save, ngrok transmettra les requêtes faites au point de terminaison /call_events à 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 d'événements d'appel dans Rails

Maintenant que Vonage transmet les statuts au répertoire /call_events mettons à jour notre application et créons une route pour le gérer.

# config/routes.rb


Rails.application.routes.draw do
 resources :call_events, only: [:create]


	...previous routes...

Mais que va-t-il se passer ? Notre application va accepter l'événement d'appel et l'analyser pour en extraire les informations pertinentes. Vous pouvez voir à quoi ressemble un événement d'appel typique :

{
"from": "442079460000",
"to": "447700900000",
"uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"conversation_uuid":
"CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"status": "ringing",
"direction": "outbound",
"timestamp": "2020-01-01T12:00:00.000Z"
}

Le format des données incluses dépend de l'événement qui s'est produit. Voir la liste complète des événements d'appel pour plus de détails. Le champ le plus important est le champ statut car il vous indique si votre message a été délivré et, si ce n'est pas le cas, ce qui n'a pas fonctionné.

Nous allons créer une logique pour mettre à jour le statut de l'appel en fonction de l'événement d'appel reçu. Générons un nouveau contrôleur dans la ligne de commande pour gérer cela.

rails g controller CallEvents create

Notre contrôleur comporte une seule et simple fonction créer simple. Tout d'abord, la méthode analyse notre événement d'appel et extrait l'uuid ; elle utilise cet identifiant étranger pour trouver l'appel dans notre base de données locale. Elle met ensuite à jour le statut de cet appel avec le statut actuel que nous avons reçu dans l'événement d'appel.

# app/controllers/call_events_controller.rb
class CallEventsController < ApplicationController
  # We disable CSRF for this webhook call
  skip_before_action :verify_authenticity_token

  def create
    if params[:uuid]
      Call.where(uuid: params[:uuid])
		.find_or_create_by
          .first_or_create
          .update(
            status: params[:status],
            conversation_uuid: params[:conversation_uuid]
          )
    end

    head :ok
  end
end

Vous pouvez maintenant lancer un appel vers votre numéro Vonage et observer votre serveur de rails pour voir comment l'appel passe de sonnerie à la répondu à terminé. Et à chaque étape, ActiveRecord met à jour la base de données !

Terminal log output showing Vonage Voice API call event lifecycle using a Rails controller

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 allons continuer à développer cette application en acceptant des appels entrants dans le prochain post.

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.