Como criar um IVR simples com Ruby on Rails

Criamos este exemplo usando o Ruby 3.0.0, o Ruby on Rails 6.1.4.1 e a Voice API da Vonage.

Você já ligou para uma empresa e foi orientado a seguir as instruções do menu? Se sim, então você interagiu com um Sistema de Resposta Interativa de Voz (IVR). O IVR atua com base nas informações fornecidas pelo usuário, geralmente na forma de opções digitadas no teclado numérico. Você pode criar seu próprio IVR usando Ruby on Rails e a Voice API da Vonage.

Neste passo a passo, vamos criar um pequeno aplicativo em Rails que hospedará um serviço IVR simples. Quando terminarmos, você poderá expandir esse aplicativo para criar o que precisar. Neste tutorial, nossa aplicação aceitará uma entrada numérica (também chamada de código DTMF) do chamador e, em seguida, reproduzirá a entrada digitada para o chamador.

Pré-requisitos

Você precisará do seguinte para acompanhar este tutorial:

• Ruby on Rails

• ngrok para que a Vonage possa acessar o serviço em execução localmente na sua máquina

Introdução

Criar uma aplicação Rails

A primeira coisa que precisamos fazer é criar uma nova aplicação Rails. Você pode fazer isso na linha de comando com o seguinte comando:

O comando acima criará nosso aplicativo Rails em /vonage-rails-ivr-demo, e também ignorará a instalação de um banco de dados. Neste tutorial, não vamos armazenar nossos dados de forma persistente, portanto, não precisamos disso.

Mude para a pasta vonage-rails-ivr-demo pasta e execute bundle install na linha de comando. Embora a Vonage disponha de um robusto gem de SDK do Rubye uma gem de inicializador do Rails, não precisamos instalar nenhum dos dois para esta aplicação.

Criar um controlador de IVR

Agora que nosso aplicativo foi criado, nosso próximo passo é criar o Controlador que responderá a duas rotas com Objetos de Controle de Chamadas da Nexmo (NCCO). A primeira rota atenderá a chamada e solicitará que o chamador digite um número no teclado. A segunda rota repetirá em voz alta o número digitado pelo chamador.

Para criar nosso controlador, execute o seguinte na linha de comando:

Assim que isso estiver concluído, abra o aplicativo no seu editor de código preferido e vamos editar o arquivo recém-gerado /app/controllers/ivr_controller.rb. Agora vamos adicionar métodos para nossas duas rotas. Primeiro, vamos criar o #answer método que irá atender a chamada:

# 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

Conforme mostrado acima, o #answer método fornece duas instruções NCCO. A primeira é a talk ação, na qual o usuário é recebido pelo aplicativo. Escolhi a localidade Estados Unidos e o estilo número 9. A Voice API oferece uma ampla seleção de opções de idioma e estilo; veja mais no guia de conversão de texto em fala. Observação: o parâmetro “voiceName” anterior agora está obsoleto. Leia mais.

A segunda ação é a input ação, e definimos o parâmetro opcional submitOnHash para true para que a entrada termine quando o usuário pressionar a tecla # no celular. Também fornecemos o eventUrl com uma URL que aponta para nossa outra rota, que responderá à entrada do usuário.

Por fim, vemos que o #answer método usa uma variável constante chamada BASE_URL que, no momento, está definida como uma string vazia. Mais adiante neste passo a passo, vamos preenchê-la com nossa URL do ngrok acessível externamente.

Agora, vamos adicionar nossa segunda e última ação do Controlador, #event. Ela reagirá à entrada do usuário, informando em voz alta a opção de número escolhida por ele:

# 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

No final, nosso Controller ficará assim:

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

O próximo passo que precisamos dar é definir nossas rotas. Fazemos isso editando o /config/routes.rb arquivo e adicionando os dois caminhos de URL correspondentes às nossas duas ações do Controlador:

# routes.rb

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

Configurar o ngrok

A partir do Rails 6, você deve conceder permissão à URL do seu túnel ngrok para acessar seu ambiente de desenvolvimento. A variável NGROK_URL será substituída pela sua URL real do ngrok na etapa seguinte. Adicione o seguinte ao seu development.rb arquivo.

Observação: É necessário reiniciar o servidor Rails após editar development.rb para que as alterações entrem em vigor.

#development.rb

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

Neste momento, nossa aplicação Rails está pronta para ser executada. Agora, vamos configurar nossa URL do ngrok para acesso externo. Precisaremos disso para a etapa final, que é a criação de nossa aplicação Vonage e do número de telefone provisionado pela Vonage.

Conecte-se ao mundo exterior

Configurar o ngrok

Existem várias maneiras de tornar nosso servidor de desenvolvimento local acessível externamente, mas uma das mais simples é usando o ngrok. Você pode ler este artigo para obter uma explicação mais detalhada sobre como o ngrok funciona.

No entanto, para os nossos fins, basta colocá-lo em funcionamento e copiar a URL que ele nos fornece.

Para iniciar o ngrok, abra uma nova janela do terminal e execute o seguinte na linha de comando:

Agora você verá uma interface de registro do ngrok na janela do seu terminal. Na parte superior da interface, há uma linha que começa com Forwarding e contém duas URLs. A primeira é a URL do ngrok acessível externamente, que termina com ngrok.io seguida por http://localhost:3000, que é o seu servidor de desenvolvimento local. Agora, quando você ou a Vonage acessarem a ngrok.io URL, ela será redirecionada para o seu servidor local.

Agora seria um bom momento para voltar ao ivr_controller.rb e substituir a string vazia pela sua URL do ngrok para a BASE_URL constante. Você também deve substituir sua URL do ngrok por NGROK_URL no development.rb arquivo. Também vamos usá-la na próxima etapa de configuração da nossa conta Vonage, do número de telefone e do aplicativo Voice.

Conecte-se com a Vonage

Criar um Account na Vonage

Para que nosso aplicativo de Voice funcione, precisamos de um Account na Vonage, um número de telefone fornecido pela Vonage, um aplicativo da Vonage e, por fim, precisamos vincular nosso aplicativo ao nosso número de telefone.

Você pode criar um Account na Vonage gratuitamente e, como bônus adicional, receberá um crédito de 2 euros no seu Account para começar a usar seu novo aplicativo. Acesse o Painel do Desenvolvedor da API da Vonage e siga as etapas de cadastro, caso ainda não tenha um Account de desenvolvedor da API da Vonage. Após concluir o cadastro, você verá o seu Painel do Desenvolvedor da API da Vonage.

No menu à esquerda, clique no Voice menu item. Você verá as seguintes opções:

voice menu options

Clique na Getting started opção e você será direcionado para uma página onde poderá testar a funcionalidade de conversão de texto em fala ou configurar um novo aplicativo da Vonage. Encontre o seguinte Create an application formulário:

create application form

Preencha o formulário com as seguintes informações:

• Application name campo de texto: Enter vonage-rails-ivr-demo

Quando terminar, clique no Create Application botão.

Depois que o aplicativo for criado, você poderá gerar um par de chaves pública e privada. Não vamos usá-las neste tutorial, mas é bom saber onde elas estão, caso você decida ampliar este aplicativo com mais funcionalidades.

Você acabou de criar um aplicativo do Vonage Voice. Nosso próximo passo é adquirir um número de telefone da Vonage e vinculá-lo a esse aplicativo. Clique no Configure application Conforme mostrado abaixo:

configure application button

Isso irá redirecioná-lo para a página de configurações do seu aplicativo. Na segunda metade da página, você poderá vincular seu aplicativo aos números de telefone provisionados pela Vonage. Clique no Buy numbers botão e você será direcionado para uma página onde poderá escolher um país, recursos, tipo e os quatro dígitos que deseja que o número tenha.

buy numbers menu

Para os nossos fins: escolha o país em que você está no momento, para que a ligação seja considerada local para você; escolha Voice “Recursos” e “Celular” ou “Fixo” como tipo. Você não precisa preencher nada no Number campo de texto. Ao clicar em Search, você verá uma lista de números de telefone disponíveis.

Escolha uma clicando no Buy botão e clique no botão preto Buy mais uma vez na janela de confirmação.

Depois de adquirir o número, você já pode vinculá-lo ao seu vonage-rails-ivr-demo aplicativo Voice. Para isso, clique na Your applications opção no painel à esquerda. Volte para a página do seu aplicativo. Agora você verá o número de telefone recém-adquirido listado na segunda metade da página, conforme mostrado abaixo:

link numbers menu

Basta clicar no botão branco link . O botão ficará vermelho e mudará para unlink. Seu número de telefone da Vonage agora está vinculado ao seu aplicativo. Nossa última etapa é configurar o aplicativo da Vonage para aceitar chamadas telefônicas e encaminhá-las para o aplicativo IVR Rails. Clique no edit botão na seção superior, abaixo do nome do seu aplicativo. Você será redirecionado para uma página chamada Edit vonage-rails-ivr-demo. Role a página até encontrar a seguinte seção “Recursos”:

Voice API Capabilities Form

Preencha o formulário com as seguintes informações:

• Answer URL No campo de texto, digite novamente a URL do ngrok: https://[ngrok url here]/answer

• Event URL No campo de texto, insira sua URL do ngrok: https://[ngrok url here]/event

Role até o final da página e clique no save-changes botão.

Com essa última etapa, você concluiu! Agora você tem um aplicativo IVR simples e totalmente funcional em Rails, com tecnologia da Vonage. Você pode testá-lo iniciando seu servidor Rails e, com o ngrok também em execução, ligar para o aplicativo usando o número de telefone que acabou de adquirir.

Leitura complementar

Para continuar aprendendo sobre o que discutimos, considere explorar o seguinte:

• Referência NCCO

• Visão geral da Voice API

• Guia de Referência da Voice API

• Criação de um IVR no Twitter com a Voice API da Nexmo