Construire une boîte vocale avec Ruby on Rails

Avez-vous déjà voulu être en mesure de fournir aux clients un numéro de téléphone qu'ils peuvent appeler et simplement vous laisser un message ? Vous pouvez créer votre propre application de messagerie vocale à l'aide de l'API Voice de Nexmo et de Ruby on Rails. Dans ce tutoriel, nous verrons les étapes à suivre pour mettre en place votre application. Votre application sera capable de recevoir des appels téléphoniques, d'enregistrer des messages vocaux et d'avoir une interface web pour afficher tous les messages et les lire.

Si vous préférez, vous pouvez également cloner une copie complète de cette application sur GutHub

C'est parti !

Conditions préalables

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.

This tutorial also uses a virtual phone number. To purchase one, go to Numbers > Buy Numbers and search for one that meets your needs.

Ready to start building?

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

Pour réaliser ce tutoriel, vous aurez besoin des éléments suivants :

• Rails 5.2+

• ngrok

Créer une application de messagerie vocale

Nous allons suivre les étapes suivantes :

1. Créer une nouvelle application Rails

2. Ouvrir un compte Nexmo

3. Mise en place de ngrok

4. Mise en place de notre application Rails

Une fois que nous aurons terminé toutes les étapes ci-dessus, nous serons prêts à appeler notre nouvelle application, à laisser un message et à l'écouter à partir de notre interface web.

Créer une nouvelle application Rails

A partir de votre ligne de commande, exécutez ce qui suit :

Une fois qu'il est terminé, vous aurez une toute nouvelle application Rails appelée nexmo-rails-voicemail-demo dont la base de données est PostgreSQL. A ce stade, vous voudrez également créer la base de données de développement dans PostgreSQL. Vous pouvez le faire en exécutant ce qui suit :

Maintenant que la base de données est créée, nous pouvons créer notre table qui stockera les informations relatives à chaque enregistrement de boîte vocale. Nous voulons une table qui contiendra les identifiants uniques de la boîte vocale, de l'enregistrement et du numéro de téléphone de l'expéditeur. Conversationde l'enregistrement et du numéro de téléphone de l'expéditeur. Nous définirons ce qu'est un Conversation et comment l'utiliser lorsque nous aborderons la création du contrôleur. La commande suivante créera notre table :

Vous pouvez inspecter le fichier de migration créé par le générateur en ouvrant l'application dans votre éditeur de code préféré et en visualisant le fichier dans le dossier /db/migrate dans le dossier Il sera nommé create_recordings.rb précédé de l'heure à laquelle vous avez exécuté la commande ci-dessus. Le fichier devrait ressembler à ceci :

class CreateRecordings < ActiveRecord::Migration[5.2]
  def change
    create_table :recordings do |t|
      t.string :conversation_uuid
      t.string :recording_uuid
      t.numeric :from

      t.timestamps
    end
  end
end

Si le fichier de migration semble correct, vous pouvez continuer et exécuter la migration en lançant rake db:migrate à partir de votre ligne de commande.

La dernière étape pour l'instant dans la mise en place de notre application Rails est l'installation de nos dépendances. Ouvrez le fichier Gemfile dans le dossier racine de l'application et ajoutez ce qui suit :

# Gemfile

gem 'nexmo_rails'
gem 'dotenv-rails'

Une fois le fichier sauvegardé, lancez bundle install à partir de votre terminal. Vous aurez installé la gem nexmo_rails initializer dans votre application, ce qui nous permet d'instancier un client Nexmo accrédité. Nous allons nous abstenir d'exécuter l'initialisateur Nexmo pour l'instant car nous devons d'abord créer notre Account Nexmo et recevoir nos informations d'identification pour l'API. Vous avez également installé la gem dotenv-rails qui nous aidera à ajouter nos identifiants API Nexmo en tant que variables d'environnement.

Nous sommes maintenant prêts à passer à l'étape suivante et à créer notre Account Nexmo.

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, nous avons juste besoin 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 d'enregistrement 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 Nexmo contacte l'URL ngrok.io l'URL sera transmise à votre serveur local.

Veillez à copier l ngrok.io dans un endroit sûr. Nous l'utiliserons lors de la prochaine étape de configuration de notre compte Nexmo, de notre numéro de téléphone et de l'application Voice.

Créer un Account Nexmo

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

Vous pouvez créer un compte Nexmo 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 quatre options suivantes s'affichent sous APPLICATIONS:

Cliquez sur l'option Create an application et vous serez dirigé vers une page où vous pourrez créer une nouvelle application Nexmo.

Complétez le formulaire avec les informations suivantes :

• Application name champ de texte entrer nexmo-rails-voicemail-demo

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

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

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

Une fois l'application créée, vous pouvez générer une paire de clés publique/privée. Vous aurez besoin de ces clés pour accéder aux enregistrements de la messagerie vocale à partir de l'API. Cliquez sur generate public/private key pair et déplacez le fichier private.key automatiquement téléchargé dans le dossier racine de notre application.

Si vous ne l'avez pas encore fait, c'est le moment de créer un fichier .gitignore dans le niveau supérieur de votre application et d'ajouter ./private.key afin de ne pas livrer votre clé privée au contrôle de version.

Vous avez maintenant créé une application Nexmo Voice. La prochaine étape consiste à acheter un numéro de téléphone Nexmo et à le lier à cette application.

Dans le tableau de bord Nexmo, cliquez sur l'élément de menu Numbers dans le menu de gauche. Vous verrez apparaître trois options :

Cliquez sur l'option 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.

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 orange Buy et en cliquant à nouveau sur le bouton orange Buy à la demande de confirmation.

Une fois que vous possédez le numéro, vous pouvez maintenant le lier à votre nexmo-rails-voicemail-demo Voice. Pour ce faire, cliquez sur l'icône d'engrenage à côté du numéro de téléphone et vous verrez le menu suivant :

Sélectionnez l'application nexmo-rails-voicemail-demo Application dans la liste déroulante et cliquez sur le bouton bleu Ok bleu. Votre numéro de téléphone Numbers est maintenant lié à votre application Voice et prêt à accepter et à transférer les appels téléphoniques entrants via le proxy vocal.

Notre dernière étape avant d'être prêt à exécuter notre application est de définir notre contrôleur Rails, notre vue, notre modèle et nos routes.

Mise en place de notre application Rails

Avant de commencer à écrire le code de notre modèle, de notre vue et de notre contrôleur, prenons un moment pour passer en revue ce que nous voulons que l'application fasse. Notre application comporte deux aspects différents :

• Recevoir un appel téléphonique et enregistrer un message

• Afficher et rendre accessibles les enregistrements sur une page web

Afin d'accomplir la première tâche de réception d'un appel et d'enregistrement d'un message, nous avons besoin d'une route webhook qui peut accepter la demande de l'API Voice Nexmo lors de la réponse à un appel et renvoyer des instructions à l'API. Nous avons ensuite besoin d'une route séparée qui peut accepter les mises à jour de l'état de l'appel.

La deuxième tâche de notre application nécessite une route capable d'accepter une demande de GET afin d'obtenir la liste de tous les enregistrements. De plus, puisque nous devons lister tous les enregistrements, nous devrons ensuite sauvegarder chaque enregistrement dans la base de données que nous avons créée plus tôt. Nous devrons également sauvegarder chaque enregistrement afin de pouvoir le lire facilement à l'auditeur.

Maintenant que nous avons une idée de la voie à suivre, commençons à la construire.

Définir nos itinéraires

Ouvrez le fichier /config/routes.rb dans votre éditeur de code et ajoutez les routes suivantes :

# routes.rb

get '/', to: 'voicemail#index'
get '/answer', to: 'voicemail#answer'
post '/event', to: 'voicemail#event'
post '/recording', to: 'voicemail#new'

Nous avons créé quatre routes distinctes qui dirigeront tout le trafic vers notre application vers les méthodes appropriées de notre contrôleur de messagerie vocale qui sera bientôt créé. Nous avons créé deux routes de GET l'une pour gérer la demande de niveau supérieur pour lister tous les enregistrements et l'autre pour recevoir la demande API initiale de Nexmo lorsqu'un appel téléphonique est pris. Nous avons également créé deux requêtes POST l'une pour recevoir les mises à jour de Nexmo sur l'état de l'appel, et l'autre pour sauvegarder l'enregistrement lorsque l'appel est terminé.

Définir les actions de notre contrôleur

Les routes que nous avons créées font référence à un contrôleur que nous n'avons pas encore créé, alors allons-y et faisons-le maintenant. Depuis la ligne de commande, exécutez ce qui suit :

Cela créera un fichier dans /app/controllers appelé voicemail_controller.rb. Nous devons créer une action pour chacun des itinéraires. Ces actions contiendront la logique de l'itinéraire et dirigeront le trafic vers la vue appropriée, le cas échéant. Les actions sont les suivantes :

• #index: Contient une variable d'instance appelée @recordings qui contient tous les enregistrements de la messagerie vocale.

• #answer: Rend un Nexmo Call Control Object (NCCO) [objet JSON contenant les instructions pour l'API Nexmo] à l'API Nexmo.

• #event: Reçoit les mises à jour de l'API Nexmo. Lorsque l'application reçoit un statut de answeredla méthode crée une nouvelle entrée dans le tableau Recordings table.

• #new: Accédé par l'API lorsqu'un enregistrement a été effectué et met à jour une entrée d'enregistrement avec l'identifiant unique de l'enregistrement audio. recording_uuidl'identifiant unique de l'enregistrement audio.

Enfin, avant de définir toute méthode, nous créons deux variables constantes : NEXMO_NUMBER et EXTERNAL_URLpour contenir respectivement le numéro de téléphone de Numbers que nous avons provisionné et l'URL de notre URL ngrok accessible de l'extérieur. Veillez à les définir dans votre contrôleur avec vos informations.

Voici à quoi ressemblera notre contrôleur lorsqu'il sera terminé :

# voicemail_controller.rb

class VoicemailController < ApplicationController
    skip_before_action :verify_authenticity_token

    NEXMO_NUMBER = YOUR PHONE NUMBER GOES HERE
    EXTERNAL_URL = 'YOUR NGROK URL GOES HERE'
    
    def index
        @recordings = Recording.all
    end

    def answer
        render json:
        [
            {
                :action => 'talk',
                :text => 'Leave your message after the beep.'
            },
            {
                :action => 'record',
                :beepStart => true,
                :eventUrl => [ "#{EXTERNAL_URL}/recording" ],
                :endOnSilence => 3
            }
        ]
    end

    def event
        if params['status'] == 'answered'
            Recording.create(conversation_uuid: params['conversation_uuid'], from: params['from'])
        end
    end

    def new
        if params['recording_url']
            recording = Recording.find_by(uuid: params['conversation_uuid'])
            recording.recording_uuid = params['recording_uuid']
            recording.save
            Nexmo.files.save(params['recording_url'], "public/voicemail/#{params['recording_uuid']}.wav")
        end
    end
end

Définir notre modèle

Dans notre application, nous n'avons besoin de créer qu'un seul modèle que nous utiliserons pour interagir avec notre table dans la base de données. Recordings dans la base de données. Allez-y et créez un fichier appelé recording.rb dans /app/models/ et tout ce que vous avez à faire à l'intérieur est de définir qu'il s'agit d'un modèle qui hérite de ActiveRecord::Base:

# recording.rb

class Recording < ActiveRecord::Base
end

Maintenant que nous avons défini nos Routes, notre Contrôleur et notre Modèle, le prochain élément que nous devons créer est une #index vue. Allons-y et faisons-le maintenant.

Créer notre vue

Nous devons créer une vue pour notre application, qui sera l'endroit où tous les enregistrements de la messagerie vocale seront affichés. L'utilisateur peut cliquer sur l'un d'entre eux pour écouter l'enregistrement. Nous devons créer un fichier index.html.erb dans le fichier /app/views/voicemail. Dans ce fichier, nous voulons tirer parti de la variable d'instance @recordings que nous avons créée dans l'action voicemail Controller #index qui contient toutes les entrées de la table Recordings . Nous allons itérer sur ces données et créer un tableau HTML pour lister tous les enregistrements. Notre vue finale contiendra le code suivant :

# index.html.erb

<h1>Your Voicemail</h1>

<strong>You have <%= Dir["public/voicemail/*"].length %> messages</strong>

<br /><br />

<table>
    <tr>
        <th>From</th>
        <th>Timestamp</th>
        <th>Conversation UUID</th>
        <th>Recording</th>
    </tr>
    <% @recordings.each do |r| %>
        <tr>
            <td><%= r.from %></td>
            <td><%= r.created_at %></td>
            <td><%= r.conversation_uuid %></td>
            <td><a href="/voicemail/<%= r.recording_uuid %>.wav">Click here to listen</a></td>
        </tr>
    <% end %>
</table>

Le seul élément supplémentaire que nous avons ajouté à la vue, en plus du tableau HTML, est un décompte du nombre d'enregistrements de la messagerie vocale. Nous utilisons la méthode #length en Numbers pour compter le nombre de fichiers dans le dossier local des enregistrements de messages vocaux et afficher ce nombre.

Avec la création de la vue, notre application est maintenant presque prête. La dernière chose à faire est d'ajouter les identifiants de l'API Nexmo comme variables d'environnement et d'initialiser notre client Nexmo à l'aide de l'initialisateur Nexmo Rails.

Ajout d'informations d'identification Nexmo et initialisation d'un client Nexmo

Plus tôt dans ce tutoriel, nous avons installé les logiciels dotenv-rails et nexmo_rails comme dépendances. La première nous aide à gérer l'utilisation des variables d'environnement dans notre application, tandis que la seconde contient un générateur Rails pour initialiser un client crédité Nexmo.

La première chose à faire pour ajouter nos identifiants Nexmo est d'ouvrir, ou de créer le fichier s'il n'existe pas encore, .env dans le dossier racine de notre projet. Dans le fichier .env nous allons ajouter nos informations d'identification pour notre clé API Nexmo, notre secret, le chemin d'accès au fichier de la clé privée et l'ID de l'application. Il ressemblera à ce qui suit, en remplaçant les valeurs par vos identifiants uniques que vous avez obtenus à partir du tableau de bord Nexmo :

# .env

NEXMO_API_KEY=your api key
NEXMO_API_SECRET=your api secret
NEXMO_APPLICATION_ID=your application id
NEXMO_PRIVATE_KEY=./private.key

Maintenant que nos informations d'identification sont ajoutées en tant que variables d'environnement, nous sommes prêts à exécuter le générateur. A partir de la ligne de commande, exécutez ce qui suit :

Et voilà ! Vous disposez à présent d'une application pleinement opérationnelle.

Démarrez votre serveur Rails, et en vous assurant que ngrok est en cours d'exécution, appelez-le et laissez-lui un message !