Comment créer un SVI simple avec Ruby on Rails

Nous avons construit cet exemple en utilisant Ruby 3.0.0 et Ruby on Rails 6.1.4.1, ainsi que l'API Voice de Vonage.

Vous est-il déjà arrivé de composer le numéro d'une entreprise et d'être invité à suivre les instructions d'un menu ? Si c'est le cas, vous avez eu affaire à un serveur vocal interactif (SVI). Le SVI agit en fonction des données fournies par l'appelant, généralement sous la forme de choix effectués à l'aide d'un clavier numérique. Vous pouvez créer votre propre SVI en utilisant Ruby on Rails et l'API Voice de Vonage.

Dans ce guide, nous allons construire une petite application Rails qui hébergera un simple service IVR. Une fois que nous aurons terminé, vous pourrez développer cette application pour construire ce dont vous avez besoin. Dans ce tutoriel, notre application acceptera une entrée numérique (également appelée code DTMF) de la part de l'appelant, puis lui restituera l'entrée saisie.

Conditions préalables

Vous aurez besoin des éléments suivants pour suivre ce tutoriel :

• Ruby on Rails

• ngrok afin que Vonage puisse accéder au service fonctionnant localement sur votre machine

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.

Pour commencer

Créer une application Rails

La première chose à faire est de créer une nouvelle application Rails. Vous pouvez le faire sur votre ligne de commande avec ce qui suit :

La commande ci-dessus créera notre application Rails dans /vonage-rails-ivr-demoet évitera l'installation d'une base de données. Dans ce tutoriel, nous ne persisterons pas nos données, donc nous n'en avons pas besoin.

Changez de répertoire dans le dossier vonage-rails-ivr-demo et lancez bundle install à partir de la ligne de commande. Bien que Vonage dispose d'un Ruby SDK gemet d'un initialisateur Rails initializer gemnous n'avons pas besoin d'installer l'un ou l'autre pour cette application.

Créer un contrôleur IVR

Maintenant que notre application a été créée, l'étape suivante consiste à créer le contrôleur qui répondra à deux itinéraires à l'aide d'objets de contrôle d'appel Nexmo (NCCO). Nexmo Call Control Objects (NCCO). La première route répondra à l'appel et demandera à l'appelant d'appuyer sur un numéro de son clavier. La seconde route répondra au numéro que l'appelant a saisi.

Pour créer notre contrôleur, exécutez la commande suivante à partir de la ligne de commande :

Une fois l'opération terminée, ouvrez l'application dans votre éditeur de code préféré et modifiez le nouveau fichier /app/controllers/ivr_controller.rb. Nous allons maintenant ajouter des méthodes pour nos deux routes. Tout d'abord, créons la méthode #answer qui prendra l'appel :

# ivr_controller.rb

class IvrController < ApplicationController
  skip_before_action :verify_authenticity_token
  
  BASE_URL = ''

  def answer
    render json:
      [
        {
          action: 'talk',
          text: 'Welcome! This is the Vonage Ruby on Rails IVR Demo Application. Please enter a number on your keypad, followed by the hash key.',
          language: "en-US",
          style: 9
        },
        {
          action: 'input',
          submitOnHash: true,
          eventUrl: ["#{BASE_URL}/event"]
        }
      ].to_json
  end
end

Comme indiqué ci-dessus, la méthode #answer fournit deux instructions NCCO. La première est l'action talk dans laquelle l'appelant est accueilli par l'application. J'ai choisi la locale des États-Unis et le style numéro 9. L'API Voice fournit une sélection robuste d'options de langue et de style. guide de la synthèse vocale. Remarque : l'ancien paramètre voiceName est désormais obsolète. Pour en savoir plus.

La deuxième action est l'action input et nous avons défini le paramètre optionnel submitOnHash à true pour que la saisie se termine lorsque l'utilisateur appuie sur la touche dièse de son téléphone. Nous avons également fourni au paramètre obligatoire eventUrl une URL qui pointe vers notre autre route qui répondra à la saisie de l'utilisateur.

Enfin, nous constatons que la méthode #answer utilise une variable constante appelée BASE_URL qui est actuellement définie comme une chaîne vide. Plus tard dans ce guide, nous remplirons cette variable avec notre URL ngrok accessible de l'extérieur.

Ajoutons maintenant notre deuxième et dernière action du contrôleur, #event. Cette action répondra à l'entrée de l'appelant en lui indiquant le numéro qu'il a choisi :

# ivr_controller.rb

def event
  number = params['dtmf']

  render json:
  [
    {
      action: 'talk',
      text: "You entered #{number}. Thank you for trying the Vonage Ruby on Rails IVR Demo Application!",
      language: "en-US",
      style: 9
    }
  ].to_json
end

Au total, notre contrôleur se présentera comme suit :

# ivr_controller.rb

class IvrController < ApplicationController
  skip_before_action :verify_authenticity_token

  BASE_URL = ''

  def answer
    render json:
      [
        {
          action: 'talk',
          text: 'Welcome! This is the Vonage Ruby on Rails IVR Demo Application. Please enter a number on your keypad, followed by the hash key.',
          language: "en-US",
          style: 9
        },
        {
          action: 'input',
          submitOnHash: true,
          eventUrl: ["#{BASE_URL}/event"]
        }
      ].to_json
  end

  def event
    number = params['dtmf']

    render json:
    [
      {
        action: 'talk',
        text: "You entered #{number}. Thank you for trying the Vonage Ruby on Rails IVR Demo Application!",
        language: "en-US",
        style: 9
      }
    ].to_json
  end

end

Définir les itinéraires

L'étape suivante consiste à définir nos itinéraires. Nous le faisons en éditant le fichier /config/routes.rb et en ajoutant les deux chemins d'URL correspondant à nos deux actions de contrôleur :

# routes.rb

Rails.application.routes.draw do
  get '/answer', to: 'ivr#answer'
  post '/event', to: 'ivr#event'
end

Configurer ngrok

A partir de Rails 6, vous devez donner à l'URL de votre tunnel ngrok la permission d'accéder à votre environnement de développement. L'URL NGROK_URL sera remplacée par l'URL ngrok dans l'étape suivante. Ajoutez ce qui suit à votre fichier development.rb fichier.

Note : Vous devez redémarrer votre serveur rails après l'avoir modifié : Vous devez redémarrer votre serveur rails après avoir modifié development.rb pour que les modifications soient prises en compte.

#development.rb

  config.hosts << "NGROK_URL.ngrok.io"

À ce stade, notre application Rails est prête à fonctionner. Maintenant, configurons notre URL ngrok accessible de l'extérieur. Nous en aurons besoin pour la dernière étape, qui consiste à créer notre application Vonage et notre numéro de téléphone provisionné par Vonage.

Se connecter au monde extérieur

Mise en place de ngrok

Il y a plusieurs façons de rendre notre serveur de développement local accessible à l'extérieur, mais l'une des façons les plus simples est d'utiliser ngrok. Vous pouvez lire cet article pour une explication plus détaillée du fonctionnement de ngrok.

Cependant, pour nos besoins, il nous suffit de le faire fonctionner et de copier l'URL qu'il nous fournit.

Pour démarrer ngrok, ouvrez une nouvelle fenêtre de terminal et exécutez la commande suivante :

Vous verrez maintenant une interface de journalisation ngrok dans votre fenêtre de terminal. En haut de l'interface se trouve une ligne qui commence par Forwarding et qui contient deux URL. La première est l'URL de ngrok accessible de l'extérieur, qui se termine par ngrok.io suivie de http://localhost:3000qui est votre serveur de développement local. Maintenant, lorsque vous ou Vonage contactez l'URL ngrok.io l'URL, il la transmettra à votre serveur local.

C'est maintenant le bon moment pour retourner à la section ivr_controller.rb et de remplacer la chaîne vide par votre URL ngrok pour la constante BASE_URL constante. Vous devriez également remplacer votre URL ngrok par NGROK_URL dans le fichier development.rb dans le fichier Nous l'utiliserons également lors de la prochaine étape qui consistera à configurer notre Account Vonage, notre numéro de téléphone et notre application Voice.

Se connecter avec Vonage

Établir un compte Vonage

Pour que notre application vocale fonctionne, nous avons besoin d'un compte Voice, d'un numéro de téléphone fourni par Voice, d'une application Voice et, enfin, nous devons lier notre application à notre numéro de téléphone.

Vous pouvez créer un compte Vonage gratuitement et, en prime, votre compte sera crédité de 2 euros pour commencer à utiliser votre nouvelle application. Visitez le tableau de bord du développeur API de Vonage et suivez les étapes d'inscription si vous n'avez pas encore de compte Vonage API Developer. Une fois l'inscription terminée, vous verrez votre tableau de bord du développeur API de Vonage.

Dans le menu de gauche, cliquez sur l'élément Voice menu dans le menu de gauche. Les options suivantes s'affichent :

voice menu options

Cliquez sur l'option Getting started et vous serez dirigé vers une page où vous pourrez tester la fonctionnalité de synthèse vocale ou configurer une nouvelle application Vonage. Trouvez le formulaire suivant Create an application formulaire :

create application form

Complétez le formulaire avec les informations suivantes :

• Application name champ de texte entrer vonage-rails-ivr-demo

Une fois que vous avez terminé, cliquez sur le bouton Create Application et cliquez sur le bouton

Une fois l'application créée, vous pouvez générer une paire de clés publique/privée. Nous ne les utiliserons pas dans le cadre de ce tutoriel, mais il est bon de savoir où elles se trouvent au cas où vous décideriez d'étendre cette application à d'autres fonctionnalités.

Vous avez maintenant créé une application Vonage Voice. La prochaine étape consiste à acheter un numéro de téléphone Vonage et à le lier à cette application. Cliquez sur l'icône Configure application Comme on le voit ci-dessous :

configure application button

Cela vous redirigera vers la page des paramètres de votre application. Dans la seconde moitié de la page, vous pouvez lier votre application aux numéros de téléphone fournis par Vonage. Cliquez sur le bouton Buy numbers et vous serez dirigé vers une page où vous pourrez choisir un pays, des caractéristiques, un type et les quatre chiffres que vous souhaitez voir figurer sur le numéro.

buy numbers menu

Pour ce qui nous concerne : choisissez le pays dans lequel vous vous trouvez actuellement afin que l'appel soit un appel local pour vous ; choisissez Voice pour les caractéristiques et mobile ou fixe pour le type. Vous n'avez pas besoin d'entrer quoi que ce soit dans le Number pour le champ de texte. Lorsque vous cliquez sur Searchvous verrez une liste de numéros de téléphone disponibles.

Choisissez-en un en cliquant sur le bouton Buy et cliquez à nouveau sur le bouton noir Buy à la demande de confirmation.

Une fois que vous possédez le numéro, vous pouvez maintenant le lier à votre vonage-rails-ivr-demo Voice. Pour ce faire, cliquez sur l'option Your applications dans le panneau de gauche. Retournez à la page de votre application. Vous verrez maintenant votre numéro de téléphone nouvellement acheté répertorié dans la seconde moitié de la page, comme vu ci-dessous :

link numbers menu

Il suffit de cliquer sur le bouton blanc link blanc. Le bouton devient rouge et se transforme en unlink. Votre numéro de téléphone Vonage est maintenant lié à votre application. Notre dernière étape consiste à configurer l'application Vonage pour qu'elle accepte les appels téléphoniques et les envoie à l'application IVR Rails. Cliquez sur le bouton edit dans la section supérieure, sous le nom de votre application. Vous serez redirigé vers une page appelée Edit vonage-rails-ivr-demo. Faites défiler la page jusqu'à ce que vous trouviez la section Capacités suivante :

Voice API Capabilities Form

Complétez le formulaire avec les informations suivantes :

• Answer URL Dans le champ de texte, entrez à nouveau l'URL de votre ngrok : https://[ngrok url here]/answer

• Event URL Dans le champ de texte, entrez l'URL de votre ngrok : https://[ngrok url here]/event

Descendez au bas de la page et cliquez sur le bouton save-changes et cliquez sur le bouton

Avec cette dernière étape, vous avez terminé ! Vous avez maintenant une application IVR Rails simple entièrement fonctionnelle, alimentée par Vonage. Vous pouvez l'essayer en démarrant votre serveur Rails, et avec ngrok également en cours d'exécution, appelez votre application au numéro de téléphone que vous venez d'acheter.

Pour en savoir plus

Pour continuer à en apprendre davantage sur ce que nous avons discuté, envisagez d'explorer ce qui suit :

• Référence NCCO

• Aperçu de l'API Voice

• Guide de référence de la Voice API

• Créer un SVI pour Twitter avec l'API Voice de Nexmo