Cree una aplicación de texto a voz con Hanami

Este tutorial mostrará cómo crear una aplicación de voz de texto a voz usando Hanami, el SDK Ruby de Vonage y Voice API. Este tutorial requerirá crear una aplicación de Vonage con capacidades de voz.

También puedes encontrar el código y la aplicación completa que se muestra en este tutorial en GitHub.

Requisitos previos

• Aplicación Voice de Vonage

• Número de teléfono proporcionado por Vonage

• Ruby y Hanami instalados en su máquina

• Ngrok

¿Qué es el Hanami?

Hanami es un framework web Ruby con todas las funciones. Ofrece una alternativa a Ruby on Rails que es más ligera y consume menos memoria. Se basa en la misma metodología MVC (modelos, vistas y controladores) que Rails. Una de sus principales diferencias de diseño es que reduce la funcionalidad a su mínima expresión. Como resultado, una aplicación web Hanami puede tener más archivos para lograr lo mismo que una aplicación web Rails, pero cada archivo es responsable de lo menos posible. Esto hace que el seguimiento de errores, la adición de características y la refactorización sean más ágiles.

No es raro encontrar extensos modelos y controladores en una aplicación Ruby on Rails. A menudo, gran parte de ese código se reordena a un área de servicios o clases de ayuda. Sin embargo, en una aplicación Hanami, debido a su diseño general, es bastante difícil acabar llenando un único modelo o un único controlador con tanto código que se vuelva inmanejable.

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.

Crear una aplicación de voz de Vonage

Para crear una aplicación web que utilice la Voice API de Vonage, necesitaremos crear una aplicación de voz de Vonage en el panel. Ve a Tus aplicaciones desde el menú en la barra lateral. Genera una nueva aplicación con el nombre que elijas y luego selecciona "Generar clave pública y privada". Esto descargará el archivo private.key archivo a tu ordenador. Una vez que empecemos a crear nuestra aplicación Hanami, moveremos ese archivo a su carpeta raíz.

Asegúrese de activar la función "Voice" en Capacidades al crear la aplicación. Una vez que haya terminado, haga clic en Guardar. Si olvida hacer clic en Guardarla información de las claves pública y privada no permanecerá en la aplicación de Vonage y deberás generar un nuevo par de claves pública y privada nuevamente.

Las aplicaciones de voz en Vonage requieren que se proporcionen direcciones de webhook accesibles externamente para los datos de la Voice API de Vonage. En este tutorial, no haremos nada con estos datos. Aún así, es una buena práctica en entornos de producción cuando se trabaja con webhooks para, al menos, reconocer la información que se envía desde la API. Puedes utilizar ngrok para hacer accesible externamente tu entorno de desarrollo local cuando crees o trabajes en una aplicación. Si nunca has utilizado ngrok antes, puedes seguir este tutorial para obtener instrucciones sobre cómo configurarlo y usarlo en tu aplicación de Vonage.

Cuando termines de crear la aplicación Voice en el Dashboard, tendrás un ID de aplicación. Esto será importante en nuestra aplicación, así que anótalo.

Ahora que tenemos una aplicación Vonage Voice y un número virtual de Vonage, ¡estamos listos para crear nuestra aplicación!

Crear una aplicación Hanami

El primer paso en nuestra nueva aplicación es inicializarla. Desde la línea de comandos ejecute:

Esto creará un nuevo directorio llamado voice_app desde donde ejecutamos este comando con el andamiaje de una aplicación web usando PostgreSQL para la base de datos. Siga adelante y cambie a ese directorio y ábralo con su editor de código preferido.

Ya podemos empezar a escribir el código de nuestra aplicación de texto a voz.

Instala el SDK Ruby de Vonage

La primera tarea que queremos hacer es añadir el SDK Ruby de Vonage como una dependencia de gema al directorio Gemfile.

Abra la carpeta Gemfile de la carpeta raíz y añada gem 'vonage' a la misma. Una vez hecho esto, puede ejecutar bundle install desde la línea de comandos.

Para instanciar un cliente Vonage Client SDK autenticado capaz de realizar llamadas de voz, debemos proporcionar algunas credenciales de la API de Vonage. El archivo private.key que descargaste de Vonage Dashboard ahora puedes moverlo a la carpeta raíz de tu aplicación Hanami. También debemos proporcionar nuestro ID de aplicación de Vonage y aprovecharemos este momento para agregar nuestro número de teléfono de Vonage. Si aún no existe uno, crea un archivo .env en la carpeta raíz, o abre el actual, y agrega lo siguiente:

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

Es necesario sustituir el texto después de cada signo igual por el valor requerido. Puede mantener el valor de VONAGE_PRIVATE_KEY ya que apunta con precisión a su archivo de clave privada.

Preparar la base de datos

En este punto, vamos a preparar nuestra base de datos para la aplicación. Utilizaremos la base de datos para mantener una lista de opciones de idioma para nuestra aplicación de texto a voz. Los usuarios podrán elegir cualquiera de los idiomas disponibles en la base de datos para crear un mensaje y enviarlo a través de una llamada telefónica.

Generaremos un nuevo modelo que contendrá la información para nuestros idiomas. En Hanami, la lógica de un modelo de base de datos se almacena en un archivo entityy los datos se almacenan en un fichero repository. Un entity está desacoplado de la base de datos, mientras que el repository es el propio nivel de datos.

Para generar nuestro modelo lingüístico, podemos utilizar de nuevo el generador Hanami ejecutando bundle exec hanami generate model language.

Esto creará una nueva entidad en lib/voice_app/entities llamada language.rbun nuevo repositorio en lib/voice_app/repositories llamado language_repository.rb y una nueva migración de base de datos en db/migrations. El archivo de migración empezará con una marca de tiempo y terminará con create_languages.rb. El generador también crea algunos archivos de especificaciones para nosotros.

Tenemos que abrir el archivo de migración y editarlo para incluir columnas para el nombre del idioma y el idioma IETF BCP-47 designación del código.

El archivo de migración tendrá este aspecto cuando lo abra inicialmente:

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

Después de la línea primary_key :id añada el código para crear dos nuevas columnas de datos:

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

Puedes guardar el archivo y luego ejecutar el siguiente comando para crear nuestra base de datos con la tabla de idiomas y sus columnas que hemos añadido:

Por último, vamos a añadir algunos idiomas a nuestra base de datos. La forma más rápida de hacerlo es ingresar a la consola Hanami desde la terminal y agregar algunos. Puedes elegir de la lista de idiomas disponibles en el portal para desarrolladores de la API de Vonage o usar los que aparecen en el código de muestra a continuación. Primero, para ingresar a la consola, ejecuta bundle exec hanami console desde la línea de comandos. Luego, para crear los datos, ejecuta el siguiente código, ya sea usando los idiomas de muestra en el fragmento de código a continuación o cambiándolos de los que elegiste:

>> 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

Ahora tenemos una base de datos de idiomas creada en nuestra nueva aplicación y estamos listos para proceder al siguiente paso, generar las vistas.

Crear las Acciones Web

Para este tutorial, construiremos acciones estructuradas en la carpeta home que Hanami incluye para mantener nuestro código sin complicaciones. Así, para nuestra primera acción, que corresponde a nuestra ruta raíz / utilizaremos el generador de Hanami desde la línea de comandos para crear una acción. index acción. Esto creará un controlador para la vista index y la plantilla HTML dentro de app/web/templates/home/index.html.erb.

Además, este generador también añadirá automáticamente una ruta para nosotros dentro de app/web/config/routes.rb: get '/', to: 'home#index'.

Ejecutamos lo siguiente para crear lo anterior: bundle exec hanami generate action web home#index.

Vamos a aprovechar este momento para generar las demás acciones que necesitamos para nuestra aplicación. En resumen, necesitamos lo siguiente:

• new: La acción POST acción para el formulario que los usuarios enviarán con la información de su llamada telefónica

• create: La acción para crear una nueva llamada de texto a voz con los datos del formulario.

• success: La acción que mostrará la vista después de inicializar la llamada

Para crearlas, ejecute lo siguiente. Cada uno se divide en una línea separada en aras de la claridad:

Cada una de las acciones generadoras anteriores creó su estructura de carpetas de controladores y plantillas, al igual que la primera acción index acción.

Crear las vistas

Vamos a añadir HTML para dos vistas de nuestra aplicación. La primera vista será la vista raíz index y la segunda será la vista success después del envío del formulario.

Abra el archivo /apps/web/templates/home/index.html.erb y añada lo siguiente:

<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 vista index contiene un pequeño formulario HTML con tres entradas y un botón de envío. La primera entrada es el número que el usuario quiere marcar. La segunda entrada es la selección del idioma. Por último, la tercera entrada es el mensaje que se enviará en la llamada.

La selección desplegable de idiomas en la segunda entrada se genera a partir de los idiomas de nuestro repositorio de idiomas. Sin embargo, observará que se accede a ellos a través de una variable local voices en la vista. ¿De dónde viene esa variable? Haremos accesible esa variable en el siguiente paso de este tutorial.

Ahora, vamos a añadir la success vista. Abre /apps/web/templates/home/success.html.erb y añade lo siguiente:

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

Esta vista contiene un mensaje de felicitación al finalizar la llamada y una invitación a intentarlo de nuevo.

Añadamos la lógica a nuestros controladores para que la variable local voices variable local funcione en la vista y realice la llamada telefónica.

Definir la lógica del controlador

Como mencionamos en el paso anterior a este, necesitamos proporcionar el contexto de la variable en la vista index vista. De lo contrario, nuestra aplicación la verá como indefinida. Para ello, definiremos una variable de instancia en el controlador index dentro de apps/web/controllers/home/index.rb. Se requieren dos pasos. En primer lugar, tenemos que exponer los datos al controlador. Hanami no asume que todos los controladores necesitan acceder a todos los almacenes de datos, por lo que requiere que seas intencional acerca de los datos a los que un controlador puede acceder. En segundo lugar, tenemos que instanciar una variable en el método #call con los datos.

Este es el aspecto del index controlador:

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

        def call(params)
        end
      end
    end
  end
end

Después de la línea include Web::Action añada otra línea con expose :languages. Esto hará que la tabla de la base de datos de idiomas esté disponible para nuestro controlador. Luego, dentro de la acción #call añada lo siguiente: @languages = LanguageRepository.new.all para pasar todos los idiomas dentro del repositorio a la vista index vista.

Ahora, sigamos adelante e incorporemos el SDK Ruby de Vonage en el create controlador. Instanciaremos una instancia con credenciales del SDK y la utilizaremos para generar la llamada telefónica con el texto del usuario enviado en la llamada a través de texto a voz. Puedes añadir lo siguiente a tu archivo apps/web/controllers/home/create.rb archivo:

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

En la primera línea del fragmento de código require el SDK Ruby de Vonage. Luego, dentro del método #call creamos nuestro cliente y utilizamos el método de instancia voice#create para enviar la llamada. El método voice#create sigue la especificación API para la Voice API en los parámetros obligatorios y opcionales que acepta. Como mínimo, el método requiere

• to parámetro: Un array que contiene un hash con type y number claves

• from parámetro: Un hash con dos claves de type y number

• ncco parámetro: Un array con un hash que contiene las instrucciones enviadas a la Voice API.

El sitio especificación APIasí como la referencia NCCOson buenos puntos de partida para descubrir todos los valores posibles que se pueden utilizar al crear una llamada de voz.

Ejecutar la aplicación

Ya está listo para ejecutar su aplicación. Para iniciar tu aplicación web Hanami, ejecuta el siguiente comando desde tu terminal:

El comando anterior iniciará un servidor web en el puerto 2300. Ahora puede utilizar su navegador web para navegar a http://localhost:2300. Verás el formulario que creaste para enviar texto a voz a través de una llamada telefónica. Rellénalo, quizás utilizando tu número de teléfono como número de destinatario. Una vez que pulse "Enviar", debería recibir la llamada con su mensaje, y su navegador debería ser redirigido a la vista success vista.

¡Felicitaciones! Has creado una aplicación de voz totalmente funcional utilizando la función de texto a voz de la Voice API de Vonage con Hanami.

¿Y ahora qué?

Ahora que has comenzado a experimentar con las posibilidades de lo que puedes hacer con la Voice API de Vonage, hay mucho más por descubrir. Los siguientes recursos pueden ser un buen lugar para continuar tu viaje:

• Respuesta de voz interactiva

• Bots de llamadas / asistentes de voz

• Uso de WebSockets

• Reconocimiento de voz

• Crear buzón de voz con Ruby on Rails