Créer une application de synthèse vocale avec Hanami

Ce tutoriel montre comment créer une application vocale de synthèse vocale en utilisant Hanami, le SDK Ruby de Vonage et l'API Voice. Ce tutoriel nécessitera la création d'une application Vonage avec des capacités vocales.

Vous pouvez également trouver le code et l'application complète présentée dans ce tutoriel sur GitHub.

Conditions préalables

• Application Voice de Vonage

• Numéro de téléphone fourni par Vonage

• Ruby et Hanami installés sur votre machine

• Ngrok

Qu'est-ce que Hanami ?

Hanami est un framework web Ruby complet. Il offre une alternative à Ruby on Rails qui est plus légère et consomme moins de mémoire. Il est basé sur la même méthodologie MVC (modèles, vues et contrôleurs) que Rails. L'une de ses principales différences de conception réside dans le fait qu'il réduit les fonctionnalités à leur plus petite partie possible. Par conséquent, une application web Hanami peut avoir plus de fichiers pour accomplir la même chose qu'une application web Rails, mais chaque fichier est responsable d'aussi peu de choses que possible. Cela permet de rationaliser le suivi des bogues, l'ajout de fonctionnalités et le remaniement.

Il n'est pas rare de trouver des modèles et des contrôleurs étendus dans une application Ruby on Rails. Souvent, une grande partie de ce code est réarchitecturée en zone de services ou en classes d'aide. Cependant, dans une application Hanami, en raison de sa conception globale, il est assez difficile de finir par remplir un seul modèle ou un seul contrôleur avec tellement de code qu'il en devient lourd.

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.

Créer une application Voice de Vonage

Pour créer une application Web qui utilise l'API Voice de Vonage, nous devons créer une application Voice de Vonage dans le tableau de bord. Naviguez vers Vos Applications dans le menu de la barre de navigation latérale. Créez une nouvelle application avec le nom de votre choix, puis sélectionnez "Generate public and private key". Le fichier sera téléchargé sur votre ordinateur. private.key sur votre ordinateur. Une fois que nous aurons commencé à créer notre application Hanami, nous déplacerons ce fichier dans son dossier racine.

Veillez à activer la fonction "Voice" dans la rubrique Capacités lors de la création de l'application. Une fois que vous avez terminé, cliquez sur Enregistrer. Si vous oubliez de cliquer sur Sauvegarderles informations relatives aux clés publiques et privées ne seront pas conservées dans l'application Vonage et vous devrez générer une nouvelle paire de clés publiques et privées.

Les applications Voice de Vonage requièrent des adresses webhook accessibles de l'extérieur pour les données provenant de l'API Voice de Vonage. Dans ce tutoriel, nous ne ferons rien avec ces données. Néanmoins, dans les environnements de production, lorsque vous travaillez avec des webhooks, il est de bon ton d'accuser réception des informations envoyées par l'API. Vous pouvez utiliser ngrok pour rendre votre environnement de développement local accessible à l'extérieur lorsque vous créez ou travaillez sur une application. Si vous n'avez jamais utilisé ngrok auparavant, vous pouvez suivre ce tutoriel pour savoir comment le configurer et l'utiliser dans votre application Vonage.

Après avoir créé l'application Voice dans le tableau de bord, vous disposerez d'un identifiant d'application. Cet identifiant sera important pour notre application, alors notez-le.

Maintenant que nous disposons d'une application In-App Voice Voice et d'un numéro virtuel Vonage, nous sommes prêts à créer notre application !

Créer une application Hanami

La première étape de notre nouvelle application consiste à l'initialiser. A partir de la ligne de commande, exécutez :

Cela créera un nouveau répertoire appelé voice_app à partir duquel nous avons exécuté cette commande avec l'échafaudage d'une application web utilisant PostgreSQL comme base de données. Allez-y et changez de répertoire et ouvrez-le avec votre éditeur de code préféré.

Nous pouvons maintenant commencer à écrire le code de notre application de synthèse vocale.

Installer le SDK Ruby de Vonage

La première chose à faire est d'ajouter le SDK Ruby de Vonage en tant que dépendance gem au fichier Gemfile.

Ouvrez le fichier Gemfile du dossier racine et ajoutez-y gem 'vonage' à la racine. Une fois que vous l'avez fait, vous pouvez lancer bundle install à partir de la ligne de commande.

Pour instancier un client Vonage SDK authentifié capable de passer des appels vocaux, nous devons fournir certaines informations d'identification de l'API Vonage. Le fichier private.key que vous avez téléchargé depuis le tableau de bord de Vonage peut maintenant être déplacé dans le dossier racine de votre application Hanami. Nous devons également fournir notre identifiant d'application Vonage, et nous profiterons de ce moment pour ajouter notre numéro de téléphone Vonage. S'il n'existe pas encore, créez un fichier .env dans le dossier racine, ou ouvrez le fichier actuel, et ajoutez ce qui suit :

VONAGE_APPLICATION_ID=Your Vonage Application ID Goes Here
VONAGE_PRIVATE_KEY=./private.key
VONAGE_NUMBER=Your Vonage Number Goes Here

Vous devez remplacer le texte après chaque signe égal par la valeur requise. Vous pouvez conserver la valeur de l'élément VONAGE_PRIVATE_KEY car elle pointe précisément vers votre fichier de clé privée.

Préparer la base de données

À ce stade, nous allons préparer notre base de données pour l'application. Nous utiliserons la base de données pour conserver une liste d'options linguistiques pour notre application de synthèse vocale. Les utilisateurs pourront choisir l'une des langues disponibles dans la base de données pour créer un message à envoyer lors d'un appel téléphonique.

Nous allons générer un nouveau modèle qui contiendra les informations relatives à nos langues. Dans Hanami, la logique d'un modèle de base de données est stockée dans un fichier entityet les données sont stockées dans un repository. Un entity est découplé de la base de données, tandis que le modèle repository est le niveau de données lui-même.

Pour générer notre modèle de langage, nous pouvons utiliser à nouveau le générateur Hanami en lançant bundle exec hanami generate model language.

Cela créera une nouvelle entité dans lib/voice_app/entities appelée language.rbun nouveau dépôt dans lib/voice_app/repositories appelé language_repository.rb et une nouvelle migration de base de données dans db/migrations. Le fichier de migration commencera par un horodatage et se terminera par create_languages.rb. Le générateur construit également quelques fichiers de spécification pour nous.

Nous devons ouvrir le fichier de migration et le modifier pour inclure des colonnes pour le nom de la langue et la langue IETF BCP-47 de la langue.

Le fichier de migration se présente comme suit lorsque vous l'ouvrez initialement :

Hanami::Model.migration do
  change do
    create_table :languages do
      primary_key :id

      column :created_at, DateTime, null: false
      column :updated_at, DateTime, null: false
    end
  end
end

Après la ligne primary_key :id ajouter le code pour créer deux nouvelles colonnes de données :

column :name, String, null: false
column :code, String, null: false

Vous pouvez enregistrer le fichier et exécuter la commande suivante pour créer notre base de données avec la table des langues et les colonnes que nous avons ajoutées :

Enfin, ajoutons quelques langues à notre base de données. La façon la plus rapide de le faire est de se rendre dans la console Hanami à partir du terminal et d'en ajouter quelques-unes. Vous pouvez choisir parmi la liste des langues disponibles sur le portail des développeurs de l'API Vonage ou utiliser celles qui se trouvent dans l'exemple de code ci-dessous. Tout d'abord, pour entrer dans la console, exécutez bundle exec hanami console à partir de la ligne de commande. Ensuite, pour créer les données, exécutez le code suivant, en utilisant les langues de l'exemple de code ci-dessous ou en les modifiant à partir de celles que vous avez choisies :

>> repository = LanguageRepository.new
>> repository.create(language: 'English', code: 'en-US')
>> repository.create(language: 'Danish', code: 'da-DK')
>> repository.create(language: 'Tamil', code: 'ta-IN')
>> exit

Nous disposons à présent d'une base de données des langues créées dans notre nouvelle application et sommes prêts à passer à l'étape suivante, la génération des vues.

Créer les actions web

Pour ce tutoriel, nous construirons des actions structurées sur le dossier home fourni par Hanami, afin de simplifier notre code. Ainsi, pour notre première action, qui correspond à notre chemin racine / nous utiliserons le générateur Hanami à partir de la ligne de commande pour créer une action index action. Cela créera un contrôleur pour la vue index et le modèle HTML correspondant à l'intérieur de app/web/templates/home/index.html.erb.

De plus, ce générateur ajoutera automatiquement une route pour nous à l'intérieur app/web/config/routes.rb: get '/', to: 'home#index'.

Nous exécutons la procédure suivante pour créer ce qui précède : bundle exec hanami generate action web home#index.

Nous allons profiter de ce moment pour générer les autres actions dont nous avons besoin pour notre application. En bref, nous avons besoin de ce qui suit :

• new: L'action POST action pour le formulaire que les utilisateurs soumettront avec les informations relatives à leur appel téléphonique

• create: L'action pour créer un nouvel appel de synthèse vocale avec les données du formulaire

• success: L'action qui affichera la vue après l'initialisation de l'appel

Pour les créer, exécutez les commandes suivantes. Pour plus de clarté, chaque ligne est séparée :

Chacune des actions du générateur ci-dessus a créé son contrôleur et sa structure de dossiers de modèles, tout comme la première action index première action.

Créer les vues

Nous allons ajouter du HTML pour deux vues de notre application. La première vue sera la vue racine index et la seconde sera la vue success après la soumission du formulaire.

Ouvrez le fichier /apps/web/templates/home/index.html.erb et ajoutez ce qui suit :

<h1>Text-to-Speech Calls on Hanami</h1>

<p>Let's make a phone call!</p>

<form action="/create" method="post">
  <label for="number">Enter a recipient number:</label>
  <input type="text" id="number" name="number">
  <br />
  <label for="language">Choose a language:</label>
  <select id="language" name="language">
    <% languages.each do |voice| %>
      <option value=<%= language.code %>><%= language.name %></option>
    <% end %>
  </select>
  <br />
  <label for="message">Enter a message:</label>
  <textarea id="message" name="message" col="10">
  </textarea>
  <br />
  <input type="submit" value="Submit">
</form>

La vue index contient un petit formulaire HTML qui contient trois entrées et un bouton d'envoi. La première entrée est le numéro que l'utilisateur souhaite composer. La deuxième entrée est la sélection de la langue. Enfin, la troisième entrée est le message à délivrer lors de l'appel.

La sélection déroulante de la langue dans la deuxième entrée est générée à partir des langues de notre référentiel linguistique. Cependant, vous remarquerez qu'elles sont accessibles via une variable locale voices dans la vue. D'où vient cette variable ? Nous rendrons cette variable accessible dans la prochaine étape de ce tutoriel.

Ajoutons maintenant la success vue. Ouvrez /apps/web/templates/home/success.html.erb et ajoutons ce qui suit :

<p>Congrats, you sent your message!</p>
<br />
<p>Care to <a href="/">try again?</a>

Cette vue contient un message de félicitations à l'issue de l'appel et une invitation à réessayer.

Ajoutons la logique à nos contrôleurs pour que la variable locale voices fonctionne dans la vue et effectue l'appel téléphonique.

Définir la logique du contrôleur

Comme nous l'avons mentionné dans l'étape précédente, nous devons fournir le contexte de la variable dans la vue index de la variable. Sinon, notre application la considérera comme non définie. Pour ce faire, nous définissons une variable d'instance dans l'élément index contrôleur à l'intérieur de apps/web/controllers/home/index.rb. Deux étapes sont nécessaires. Tout d'abord, nous devons exposer les données au contrôleur. Hanami ne part pas du principe que chaque contrôleur a besoin d'accéder à tous les magasins de données, ce qui vous oblige à déterminer les données auxquelles un contrôleur peut accéder. Deuxièmement, nous devons instancier une variable dans la méthode #call avec les données.

Voici à quoi ressemble le index ressemble à un contrôleur :

module Web
  module Controllers
    module Home
      class Index
        include Web::Action

        def call(params)
        end
      end
    end
  end
end

Après la ligne include Web::Action ajouter une autre ligne avec expose :languages. Cela rendra la table de la base de données des langues disponible pour notre contrôleur. Ensuite, à l'intérieur de l'action #call ajoutez ce qui suit : @languages = LanguageRepository.new.all pour transmettre toutes les langues contenues dans le référentiel à la vue index vue.

Maintenant, nous allons incorporer le SDK Ruby de Vonage dans le contrôleur create contrôleur. Nous allons instancier une instance accréditée du SDK et l'utiliser pour générer l'appel téléphonique avec le texte de l'utilisateur envoyé dans l'appel via la synthèse vocale. Vous pouvez ajouter ce qui suit à votre fichier apps/web/controllers/home/create.rb à ce qui suit :

require 'vonage'

module Web
  module Controllers
    module Home
      class Create
        include Web::Action

        def call(params)
          client = Vonage::Client.new(
            application_id: ENV['VONAGE_APPLICATION_ID'],
            private_key: ENV['VONAGE_PRIVATE_KEY']
          )

          response = client.voice.create(
            to: [{
              type: 'phone',
              number: params[:number]
            }],
            from: {
              type: 'phone',
              number: ENV['VONAGE_NUMBER']
            },
            ncco: [{
              action: 'talk',
              text: params[:message],
              language: params[:language]
            }]
          )

          redirect_to '/success'
        end
      end
    end
  end
end

Sur la première ligne de l'extrait de code, nous avons require le SDK Ruby de Vonage. Ensuite, dans la méthode #call nous créons notre client et utilisons la méthode d'instance du SDK voice#create du SDK pour envoyer l'appel. La méthode voice#create suit la spécification de l spécification API pour l'API Voice dans les paramètres obligatoires et facultatifs qu'elle accepte. Au minimum, la méthode requiert

• to paramètre : Un tableau contenant un hachage avec type et number clés

• from paramètre : Un hachage avec deux clés de type et number

• ncco paramètre : Un tableau avec un hachage qui contient les instructions envoyées à l'API Voice.

La spécification spécification de l'APIainsi que le document de référence du référence NCCOsont de bons points de départ pour découvrir toutes les valeurs possibles qui peuvent être utilisées lors de la construction de votre appel vocal.

Exécution de l'application

Vous êtes maintenant prêt à lancer votre application ! Pour lancer votre application web Hanami, exécutez la commande suivante depuis votre terminal :

La commande ci-dessus démarre un serveur web sur le port 2300. Vous pouvez maintenant utiliser votre navigateur web pour naviguer vers http://localhost:2300. Vous verrez le formulaire que vous avez créé pour envoyer de la synthèse vocale lors d'un appel téléphonique. Remplissez-le, en utilisant éventuellement votre numéro de téléphone comme numéro de destinataire. Une fois que vous aurez appuyé sur "Soumettre", vous devriez recevoir l'appel avec votre message, et votre navigateur devrait être redirigé vers la vue success vue.

Félicitations ! Vous avez créé une application vocale entièrement fonctionnelle en utilisant la fonction de synthèse vocale de l'API Voice de Vonage avec Hanami.

Quelle est la prochaine étape ?

Maintenant que vous avez commencé à expérimenter les possibilités offertes par l'API Voice de Vonage, il vous reste encore beaucoup à découvrir. Les ressources suivantes peuvent vous aider à poursuivre votre voyage :

• Réponse vocale interactive

• Call Bots / Assistants vocaux

• Utilisation de WebSockets

• Reconnaissance de la parole

• Créer une messagerie vocale avec Ruby on Rails