Comment passer des appels téléphoniques sortants avec Ruby on Rails

Introduction

Vous souhaitez passer des appels téléphoniques sortants en Ruby on Rails ? Avec l'API Voice de Vonage, vous pouvez créer une solution d'appel programmatique qui prend en charge la synthèse vocale, l'enregistrement des appels et les interactions vocales en direct en seulement quelques lignes de code.

Ce guide montre comment envoyer des appels téléphoniques sortants avec la synthèse vocale en utilisant Ruby on Rails et le SDK de Vonage.

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

Diagram showing how an application authenticates with the Vonage Voice API to initiate a voice call to a user, using NCCO instructions and private key authentication.

Conditions préalables

• Ruby et Rails installés sur votre machine. Pour toute question sur les conventions Rails, la documentation est très complète.

• Un compte API Vonage.

• Un numéro virtuel Vonage avec des capacités vocales.

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.

Comment configurer votre application Ruby on Rails

Si vous n'avez pas suivi les articles précédents, vous devrez créer une nouvelle application Rails et procéder à quelques réglages. Si vous l'avez déjà fait, passez directement à la section Comment configurer les variables d'environnement.

Créer un nouveau projet Rails

Commencez par générer une nouvelle application Rails :

rails new vonage-voice-quickstart

Naviguez dans le répertoire du projet :

cd vonage-voice-quickstart

Installer l'API Voice de Vonage pour Ruby on Rails

Modifier le fichier Gemfile et ajoutez le SDK Vonage ainsi que dotenv pour la gestion des variables d'environnement :

gem 'vonage'
gem 'dotenv-rails', groups: [:development, :test]

Maintenant, installez les dépendances :

bundle install

Utilisation de ngrok pour gérer les Webhooks pour les appels Voice

Vonage devra savoir ce qu'il doit faire lorsqu'il répond à un appel, et nous lui indiquerons les informations contenues dans le champ answer_url que nous fournissons dans notre NCCO. Ne vous inquiétez pas, nous y reviendrons plus tard. Pour l'instant, vous devez simplement comprendre que notre application Ruby on Rails s'exécutera en développement sur le port 3000, et que nous pouvons donc y accéder localement à l'adresse localhost:3000. Cependant, cela ne fonctionne que sur notre ordinateur ! Nous devons sauvegarder notre answer_url accessible à Vonage. Vous pouvez utiliser ngrok pour exposer publiquement votre serveur local via HTTP de manière sûre. Donc maintenant, dans un onglet séparé d'où vous exécuterez votre serveur Rails, ouvrez un tunnel ngrok sur le port 3000.

ngrok http 3000

Ajoutez l'URL de votre ngrok en tant que config.host dans votre fichier development.rb dans votre fichier development.rb. Nous utiliserons la variable d'environnement VONAGE_SERVER_HOSTNAMEpour rendre notre application plus dynamique. Nous la définirons plus tard dans ce tutoriel.

# config/environments/development.rb

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

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

Créer une application Vonage

Pour ce tutoriel, activez la fonctionnalité Voice, et ajoutez vos URLs ngrok dans la section webhook. Voir la section Activer les capacités Voice ci-dessous pour voir à quoi cela devrait ressembler.

Assurez-vous de générer une clé privée, cliquez sur "Générer une clé publique et privée". Cela téléchargera un fichier private.key sur votre ordinateur. Déplacez ensuite le fichier private.key à la racine de votre application Rails.

Lorsque votre application est créée, notez l'identifiant de l'application. Vous en aurez besoin à l'étape des variables d'environnement.

Activation des capacités vocales dans Voice

Avec ngrok en marche, vous pouvez maintenant activer l'API Voice sur votre application Vonage. Cliquez sur la section Voice. Pour l'instant, vous pouvez ajouter des URL de remplacement pour les webhooks. Nous les mettrons à jour dans d'autres articles de blog.

• URL de la réponse : https://example.com/inbound_calls

• URL de l'événement : https://example.com/call_events

  
  Vonage Voice API configuration screen showing Answer, Event, and Fallback URLs for handling inbound calls and call events

Comment configurer les variables d'environnement

Créer un fichier .env et ajoutez vos identifiants Vonage :

# .env

VONAGE_APPLICATION_ID='XXXX'
VONAGE_PRIVATE_KEY='./private.key'
VONAGE_SERVER_HOSTNAME='XXXXXX.ngrok.app

Sécurisez vos données d'identification>> N'engagez jamais .env dans votre référentiel ! Assurez-vous que les fichiers .env et private.key se trouvent dans votre fichier .gitignore.

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

Comment définir le modèle et le contrôleur Rails ?

Générer un modèle Rails pour les appels

Nous devons maintenant créer notre modèle d'appel, qui définit ses attributs et la manière dont ils sont stockés dans la base de données. Nous utiliserons le générateur Ruby on Rails pour générer nos modèles et générer nos contrôleurs.

Nous aurons besoin de 6 champs :

• tole destinataire de l'appel

• froml'expéditeur de l'appel

• textLe contenu d'un appel à la synthèse vocale

• uuidIdentifiant unique d'une instance d'appel (un segment individuel d'un appel téléphonique)

• status: si un appel a été délivré avec succès ou non. Pour plus d'informations, voir la Référence API

• conversation_uuid : l'identifiant unique d'une conversation entière, qui peut comporter plusieurs appels téléphoniques (chaque participant à un appel téléphonique a un uuid unique, le conversation_uuid les regroupe).

• is_inboundL'appel est envoyé par notre application ou reçu par notre application, ce qui sera important dans les articles suivants du blog.

Exécutez le générateur Rails suivant et migrez :

rails g model Call to:string from:string text:text uuid:string status:string is_inbound:boolean conversation_uuid:string

Créons notre contrôleur pour gérer notre logique.

rails g controller OutboundCalls new create show

Et nous devrons mettre à jour notre base de données avec le nouveau modèle.

rails db:migrate

Enfin, ajoutons nos routes pour les appels sortants.

# config/routes.rb

Rails.application.routes.draw do
  resources :outbound_calls, only: [:new, :create, :show]
	...previous routes...
end

Comment initialiser le client Ruby de Vonage

Pour utiliser le client Ruby et l'API Voice, nous devrons initialiser une instance avec nos identifiants Vonage stockés dans notre fichier d'environnement. En plus de l'API Voice, le client Ruby nous permet d'accéder facilement à plus de 15 API de Vonage. Vous pouvez en savoir plus sur les API prises en charge.

Avant d'activer le client Ruby dans une application Rails complète, voyons comment nous pourrions l'utiliser plus généralement dans du code Ruby. Pour utiliser le client, il suffit d'initialiser une instance avec les informations de notre application stockées dans notre fichier d'environnement.

vonage = Vonage::Client.new(
      application_id: ENV["VONAGE_APPLICATION_ID"],
      private_key: ENV["VONAGE_PRIVATE_KEY"]
    )

Comment passer un appel vocal sortant en Ruby

Maintenant que notre client est initialisé, la création d'un appel sortant devient assez simple. Nous appelons la méthode voice pour indiquer au client d'utiliser l'API Voice, puis nous appelons la méthode create avec les champs requis.

L'API Voice crée un appel avec les balises to et from puis, lorsque l'appel est pris, elle recherche d'autres instructions dans les champs answer_url. Elle nécessite un objet d'appel NCCO, qui est un fichier json avec des options comme jouer un message, se connecter à un autre numéro, accepter la saisie de l'utilisateur, etc.

Pour en savoir plus, consultez le Guide des objets de contrôle d'appel.

response = vonage.voice.create(
  to: [{
    type: 'phone',
    number: '447700900000'
  }],
  from: {
    type: 'phone',
    number: '447700900001'
  },
  answer_url: [
    'https://raw.githubusercontent.com/nexmo-community/ncco-examples/gh-pages/text-to-speech.json'
  ]
)

Passer un appel sortant dans une application Ruby on Rails

Ajouter une interface utilisateur pour créer un appel

Maintenant que nous avons vu comment utiliser le client Ruby de Vonage pour passer des appels sortants, nous allons intégrer la fonctionnalité d'appels sortants dans notre application Rails à l'aide d'un simple formulaire et d'un contrôleur. Nous aurons besoin d'une belle interface utilisateur pour gérer les appels sortants. to, from, et text . Vous pouvez copier et ajouter le formulaire à votre /app/views/outbound_calls/new.html.erb et aux feuilles de style CSS associé.

User interface for placing a call using the Vonage Voice API, allowing users to input sender and recipient phone numbers and a voice message.

Traitement des réponses du NCCO pour l'automatisation vocale

Maintenant, mettons en œuvre la logique nécessaire au fonctionnement de notre formulaire. Tout d'abord, nous devons créer une instance Call vide pour charger le formulaire dans l'index. Ensuite, lorsque le formulaire est soumis, nous appelons la méthode create, qui sauvegarde l'instance Call dans notre base de données et l'envoie ensuite via la méthode make_call méthode.

Voir le fichier complet outbound_calls_controller.rb pour voir comment tout le code fonctionne ensemble.

#app/controllers/outbound_calls_controller.rb


  def index
    @call = Call.new
  end

  def create
    @call = Call.new(safe_params)

    if @call.save
      make_call(@call)
      redirect_to new_outbound_call_url, notice: 'Call initiated'
      flash[:alert] = 'Something went wrong'
      render :new
    end
  end

  private

  def safe_params
    params.require(:call).permit(:to, :from, :text)
  end

end

La méthode make_call lance alors l'appel téléphonique à l'aide de la Voice API. Ici, nous créons une dynamique answer_urldynamique, qui s'aligne sur notre méthode show méthode.

def make_call(call)
    options = {
      to: [{ type: 'phone', number: call.to }],
      from: { type: 'phone', number: call.from },
      answer_url: ["https://#{ENV['VONAGE_SERVER_HOSTNAME']}/outbound_calls/#{call.id}"]
    }

    response = vonage.voice.create(options)

    call.update(
      uuid: response['uuid'],
      status: response['status']
    ) if response['status'] && response['uuid']
  end

Lorsque l'API examine la méthode show, elle trouve le NCCO, qui lui indique de déclencher l'appel du robot.

  def show
    call = Call.find(params[:id])
    render json: [
      {
        "action": "talk",
        "text": call.text,
        "language": "en-AU",
        "style": 3
      }
    ]
  end

Exécution de l'application

Démarrez votre serveur Rails :

rails s

Maintenant, visitez :

http://localhost:3000/outbound_calls/new

Remplissez le formulaire et appuyez sur call. Vous devriez recevoir un appel vocal avec le texte que vous avez saisi !

*Le numéro de départ doit être un numéro virtuel de Vonage.

Conclusion

Vous avez réussi ! Vous avez mis en place une application Ruby on Rails pour passer des appels vocaux sortants. Dans les prochains billets, nous gérerons les événements d'appel, recevrons des appels entrants et verrons des interactions vocales plus avancées.

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.