Cómo crear un IVR sencillo con Ruby on Rails

Hemos creado este ejemplo utilizando Ruby 3.0.0 y Ruby on Rails 6.1.4.1, y la Voice API de Vonage.

¿Ha llamado alguna vez a una empresa y le han pedido que siga las instrucciones del menú? Si es así, ha interactuado con una Respuesta de Voz Interactiva (IVR). La IVR actúa a partir de la información proporcionada por la persona que llama, normalmente en forma de opciones de teclado numérico. Puedes crear tu propia IVR usando Ruby on Rails y Voice API de Vonage.

En este tutorial crearemos una pequeña aplicación Rails que albergará un sencillo servicio IVR. Una vez que hayamos terminado, podemos ampliar esta aplicación para crear lo que necesitemos. En este tutorial, nuestra aplicación aceptará una entrada numérica (también llamada código DTMF) de la persona que llama y, a continuación, le devolverá la entrada introducida.

Requisitos previos

Necesitarás lo siguiente para seguir este tutorial:

• Ruby en Rails

• ngrok para que Vonage pueda acceder al servicio que se ejecuta localmente en tu máquina

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.

Primeros pasos

Crear una aplicación Rails

Lo primero que tenemos que hacer es crear una nueva aplicación Rails. Puedes hacerlo en tu línea de comandos con lo siguiente:

El comando anterior creará nuestra aplicación Rails en /vonage-rails-ivr-demoy también omitirá la instalación de una base de datos. En este tutorial no vamos a persistir nuestros datos, por lo que no la necesitamos.

Cambia de directorio a la carpeta vonage-rails-ivr-demo y ejecute bundle install desde la línea de comandos. Aunque Vonage cuenta con una sólida Ruby SDK gemy una gema gema inicializadora de Railsno necesitamos instalar ninguna de ellas para esta aplicación.

Crear un controlador IVR

Ahora que nuestra aplicación ha sido creada nuestro siguiente paso es crear el Controlador que responderá a dos rutas con Objetos de Control de Llamada Nexmo (NCCO). La primera ruta responderá a la llamada y pedirá a la persona que llama que pulse un número en su teclado. La segunda ruta responderá al número introducido por la persona que llama.

Para crear nuestro Controlador ejecute lo siguiente desde la línea de comandos:

Una vez que se haya completado, abra la aplicación en su editor de código preferido y vamos a editar el recién generado /app/controllers/ivr_controller.rb. Ahora vamos a añadir métodos para nuestras dos rutas. En primer lugar, vamos a crear el método #answer que recogerá la llamada:

# 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

Como se muestra arriba, el método #answer proporciona dos instrucciones NCCO. La primera es la talk en la que la aplicación saluda a la persona que llama. He elegido la configuración regional de Estados Unidos y el estilo número 9. La Voice API ofrece una amplia selección de opciones de idioma y estilo. guía de texto a voz. Nota: el anterior parámetro voiceName ha quedado obsoleto. Más información.

La segunda acción es la input y hemos establecido el parámetro opcional submitOnHash a true para que la entrada termine cuando el usuario pulse la tecla hash en su teléfono. También proporcionamos el parámetro obligatorio eventUrl con una URL que apunta a nuestra otra ruta que responderá a la entrada del usuario.

Por último, vemos que el método #answer utiliza una variable constante llamada BASE_URL que actualmente está definida como una cadena vacía. Más adelante en este tutorial, vamos a llenar eso con nuestro ngrok URL accesible externamente.

Ahora, vamos a añadir nuestra segunda y última acción de Controlador, #event. Esto actuará sobre la entrada de la persona que llama por hablar de nuevo a la persona que llama su elección de número:

# 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

En conjunto, nuestro controlador tendrá este aspecto:

# 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

Definir rutas

El siguiente paso es definir nuestras rutas. Para ello, editamos el archivo /config/routes.rb y añadiendo las dos rutas URL correspondientes a nuestras dos acciones de controlador:

# routes.rb

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

Configurar ngrok

A partir de Rails 6, debes dar permiso a la URL de tu túnel ngrok para acceder a tu entorno de desarrollo. NGROK_URL se sustituirá por la URL real de ngrok en el siguiente paso. Añade lo siguiente a tu archivo development.rb archivo.

Nota: Debe reiniciar su servidor rails después de editar development.rb para que los cambios surtan efecto.

#development.rb

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

En este punto, nuestra aplicación Rails está lista para ejecutarse. Ahora vamos a configurar nuestra URL de acceso externo ngrok. La necesitaremos para el paso final, que es crear nuestra aplicación de Vonage y nuestro número de teléfono provisto por Vonage.

Conectar con el mundo exterior

Configurar ngrok

Hay varias formas de hacer que nuestro servidor de desarrollo local sea accesible externamente, pero una de las formas más sencillas es con ngrok. Puedes leer este artículo para una explicación más detallada de cómo funciona ngrok.

Sin embargo, para nuestros propósitos, sólo necesitamos ponerlo en marcha y copiar la URL que nos proporciona.

Para iniciar ngrok, abra una nueva ventana de terminal y ejecute lo siguiente desde la línea de comandos:

Ahora verá una interfaz de registro ngrok en su ventana de terminal. Cerca de la parte superior de la interfaz hay una línea que empieza por Forwarding y contiene dos URLs. La primera es la URL de ngrok accesible externamente, que termina con ngrok.io seguido de http://localhost:3000que es tu servidor de desarrollo local. Ahora, cuando tú o Vonage se comuniquen con la ngrok.io URL, la reenviará a tu servidor local.

Ahora sería un buen momento para volver al archivo ivr_controller.rb y reemplazar la cadena vacía con su URL ngrok para la constante BASE_URL constante. También debería reemplazar su URL ngrok por NGROK_URL en el archivo development.rb archivo. También lo usaremos en el próximo paso para configurar nuestra cuenta de Vonage, el número de teléfono y la aplicación Voice.

Conéctate con Vonage

Configurar una cuenta de Vonage

Para que nuestra aplicación de voz funcione, necesitamos una cuenta de Vonage, un número de teléfono provisto por Vonage, una aplicación de Vonage y, por último, necesitamos vincular nuestra aplicación a nuestro número de teléfono.

Puedes crear una cuenta de Vonage de forma gratuita y, como bonificación adicional, se abonarán 2 euros en tu cuenta para empezar a utilizar tu nueva aplicación. Visita el Panel para desarrolladores de API de Vonage y sigue los pasos de inscripción si aún no tienes una cuenta de desarrollador de API de Vonage. Una vez que completes la inscripción, verás tu panel de desarrollador de API de Vonage.

En el menú de la izquierda, haga clic en el Voice menu . Verá las siguientes opciones:

voice menu options

Haz clic en la opción Getting started y serás dirigido a una página donde podrás probar la función de texto a voz o configurar una nueva aplicación de Vonage. Busca el siguiente Create an application formulario:

create application form

Rellene el formulario con lo siguiente:

• Application name introducir campo de texto vonage-rails-ivr-demo

Cuando haya terminado, pulse el botón Create Application .

Una vez creada la aplicación, puedes generar un par de claves pública/privada. No las usaremos en este tutorial, pero es bueno saber dónde están en caso de que decidas ampliar esta aplicación con más funcionalidades.

Ahora has creado una aplicación Vonage Voice. Nuestro próximo paso es comprar un número de teléfono de Vonage y vincularlo a esta aplicación. Haz clic en Configure application Como se ve a continuación:

configure application button

Esto te redireccionará a la página de configuración de tu aplicación. En la segunda mitad de la página, puedes vincular tu aplicación a los números de teléfono provistos por Vonage. Haz clic en el botón Buy numbers y serás dirigido a una página donde podrás elegir el país, las funciones, el tipo y los cuatro dígitos que deseas que tenga el número.

buy numbers menu

Para nosotros: elige el país en el que te encuentras para que la llamada sea local; elige Voice para las características y móvil o fijo para el tipo. No necesita introducir nada en el campo Number campo de texto. Cuando pulse Searchverás una lista de números de teléfono disponibles.

Elija uno haciendo clic en el botón Buy y vuelva a pulsar el botón negro Buy una vez más en la ventana de confirmación.

Una vez que posea el número, podrá vincularlo a su aplicación de vonage-rails-ivr-demo aplicación Voice. Para ello, haga clic en la opción Your applications del panel izquierdo. Vuelve a la página de tu aplicación. Ahora verás tu número de teléfono recién comprado en la segunda mitad de la página, como se ve a continuación:

link numbers menu

Basta con pulsar el botón blanco link blanco. El botón se volverá rojo y cambiará a unlink. Tu número de teléfono de Vonage ahora está vinculado a tu aplicación. Nuestro último paso es configurar la aplicación de Vonage para que acepte llamadas telefónicas y las envíe a la aplicación IVR Rails. Haz clic en el botón edit en la sección superior, debajo del nombre de tu aplicación. Serás redirigido a una página llamada Edit vonage-rails-ivr-demo. Desplázate hasta que encuentres la siguiente sección Capacidades:

Voice API Capabilities Form

Rellene el formulario con lo siguiente:

• Answer URL introduzca de nuevo su URL ngrok: https://[ngrok url here]/answer

• Event URL introduzca su URL ngrok: https://[ngrok url here]/event

Desplácese hasta la parte inferior de la página y pulse el botón save-changes .

Con ese último paso, ¡has terminado! Ahora tienes una aplicación IVR Rails simple completamente funcional con tecnología de Vonage. Puedes probarla iniciando tu servidor Rails y, con ngrok también en ejecución, llama a tu aplicación al número de teléfono que acabas de comprar.

Lecturas complementarias

Para seguir aprendiendo sobre lo que hemos debatido, considere la posibilidad de explorar lo siguiente:

• Referencia OCNC

• Descripción general de Voice API

• Guía de referencia de la Voice API

• Creación de un IVR de Twitter con la Voice API de Nexmo