Como fazer chamadas telefônicas de saída com Ruby on Rails

Introdução

Quer fazer chamadas telefônicas com o Ruby on Rails? Com a Voice API da Vonage, você pode criar uma solução de chamadas programáticas que oferece suporte à conversão de texto em fala, gravação de chamadas e interações de voz em tempo real com apenas algumas linhas de código.

Este guia mostra como realizar chamadas telefônicas de saída com conversão de texto em fala usando Ruby on Rails e o SDK da Vonage.

Resumo Pule esta parte e veja todo o códigos do Guia de Início Rápido no GitHub

Diagram showing how an application authenticates with the Vonage Voice API to initiate a voice call to a user, using NCCO instructions and private key authentication.

Pré-requisitos

• Ruby e Rails instalados no seu computador. Para qualquer dúvida sobre as convenções do Rails, a documentação é bastante completa.

• Um account da API da Vonage.

• Um número virtual da Vonage com recursos de voz.

Como configurar sua aplicação Ruby on Rails

Se você ainda não concluiu os artigos anteriores, precisará criar um novo aplicativo Rails e fazer algumas configurações. Se já tiver feito a configuração, pule para a seção “Como configurar variáveis de ambiente”.

Criar um novo projeto Rails

Comece criando uma nova aplicação Rails:

rails new vonage-voice-quickstart

Acesse o diretório do projeto:

cd vonage-voice-quickstart

Instale a Voice API da Vonage para Ruby on Rails

Edite o Gemfile e adicione o SDK da Vonage junto com o dotenv para gerenciamento de variáveis de ambiente:

gem 'vonage'
gem 'dotenv-rails', groups: [:development, :test]

Agora, instale as dependências:

bundle install

Usando o ngrok para gerenciar webhooks de chamadas de voz

A Vonage precisará saber o que fazer quando uma chamada for atendida, e nós informaremos isso a ela por meio das informações contidas no answer_url que fornecemos em nosso NCCO. Não se preocupe; falaremos mais sobre isso depois. Por enquanto, basta entender que nossa aplicação Ruby on Rails será executada em ambiente de desenvolvimento na porta 3000, de modo que podemos acessá-la localmente em localhost:3000. No entanto, isso só funciona no nosso computador! Precisamos configurar nosso answer_url acessível também para a Vonage. Você pode usar o ngrok para expor seu servidor local publicamente via HTTP de maneira segura. Então, agora, em uma aba separada daquela em que você executará seu servidor Rails, abra um túnel ngrok na porta 3000.

ngrok http 3000

Adicione sua URL do ngrok como um config.host no seu arquivo development.rb . Usaremos a variável de ambiente VONAGE_SERVER_HOSTNAMEpara tornar nosso aplicativo mais dinâmico. Vamos defini-la mais adiante neste tutorial.

# config/environments/development.rb

Rails.application.configure do
   config.hosts << ENV['VONAGE_SERVER_HOSTNAME']

Para obter mais ajuda, consulte como começar a usar o ngrok no Rails.

Criar uma aplicação da Vonage

Para este tutorial, ative o recurso de Voice e adicione suas URLs do ngrok na seção de webhooks. Consulte a seção “Ativar recursos de Voice” abaixo para ver como deve ficar.

Certifique-se de gerar um arquivo private.key clicando em “Gerar chave pública e privada”. Isso fará com que um arquivo private.key seja baixado para o seu computador. Em seguida, mova o arquivo private.key para a raiz da sua aplicação Rails.

Quando seu aplicativo for criado, anote o ID do aplicativo. Você precisará desse ID na etapa “Variáveis de ambiente”.

Ativação dos recursos de voz no Vonage

Com o ngrok em execução, agora você pode habilitar a Voice API no seu aplicativo Vonage. Ative a seção “Voice”. Por enquanto, você pode adicionar URLs provisórias para os webhooks. Atualizaremos essas informações em futuras postagens do blog.

• URL da resposta: https://example.com/inbound_calls

• URL do evento: https://example.com/call_events

  
  Vonage Voice API configuration screen showing Answer, Event, and Fallback URLs for handling inbound calls and call events

Como configurar variáveis de ambiente

Crie um arquivo .env e adicione suas credenciais da Vonage:

# .env

VONAGE_APPLICATION_ID='XXXX'
VONAGE_PRIVATE_KEY='./private.key'
VONAGE_SERVER_HOSTNAME='XXXXXX.ngrok.app

Mantenha suas credenciais seguras>> Nunca salve arquivos .env no seu repositório! Certifique-se de que .env e private.key estejam no seu .gitignore.

Para obter mais ajuda sobre o ngrok, consulte como começar a usar o ngrok no Rails.

Como definir o modelo e o controlador no Rails

Gerando um modelo Rails para chamadas

Agora, precisaremos criar nosso modelo Call, que define seus atributos e como eles são armazenados no banco de dados. Usaremos o gerador do Ruby on Rails para gerar nossos modelos e gerar nossos controladores.

Vamos precisar de 6 campos:

• to: o destinatário da convocação

• from: o remetente da chamada

• text: o conteúdo de uma chamada com conversão de texto em fala

• uuid: o identificador único de uma única instância de chamada (uma parte específica de uma ligação telefônica)

• status: se uma chamada foi entregue com sucesso ou não. Veja mais informações na Referência da API

• conversation_uuid: o identificador exclusivo de uma conversa inteira, que pode envolver várias etapas de chamada (cada participante de uma chamada possui um uuid exclusivo; o conversation_uuid agrupa todos eles)

• is_inbound: seja a chamada enviada ou recebida pelo nosso aplicativo, isso será importante nas próximas postagens do blog

Execute o seguinte gerador do Rails e faça a migração:

rails g model Call to:string from:string text:text uuid:string status:string is_inbound:boolean conversation_uuid:string

Vamos criar nosso controlador para lidar com nossa lógica.

rails g controller OutboundCalls new create show

E precisaremos atualizar nosso banco de dados com o novo modelo.

rails db:migrate

Por fim, vamos adicionar nossas rotas para chamadas de saída.

# config/routes.rb

Rails.application.routes.draw do
  resources :outbound_calls, only: [:new, :create, :show]
	...previous routes...
end

Como inicializar o cliente Ruby da Vonage

Para usar o cliente Ruby e a Voice API, precisaremos inicializar uma instância com nossas credenciais da Vonage armazenadas em nosso arquivo de ambiente. Além da Voice API, o cliente Ruby nos permite acessar facilmente mais de 15 APIs da Vonage. Você pode saber mais sobre as APIs compatíveis.

Antes de habilitar o cliente Ruby em uma aplicação Rails completa, vamos ver como podemos usá-lo de maneira mais geral em código Ruby. Para usar o cliente, basta inicializar uma instância com as informações da nossa aplicação armazenadas no nosso arquivo de ambiente.

vonage = Vonage::Client.new(
      application_id: ENV["VONAGE_APPLICATION_ID"],
      private_key: ENV["VONAGE_PRIVATE_KEY"]
    )

Como fazer uma chamada de voz de saída em Ruby

Agora que nosso cliente está inicializado, criar uma chamada de saída se torna bastante simples. Chamamos o voice método para instruir o cliente a usar a Voice API e, em seguida, chamamos o método `create` com os campos necessários.

A Voice API cria uma chamada com o to e from campos; em seguida, quando a chamada é atendida, ela procura por instruções adicionais no answer_url. Ela requer um objeto de chamada NCCO, que é um arquivo JSON com opções como reproduzir uma mensagem, conectar-se a outro número, aceitar entradas do usuário etc. 

Saiba mais no Guia do Objeto de Controle de Chamadas.

response = vonage.voice.create(
  to: [{
    type: 'phone',
    number: '447700900000'
  }],
  from: {
    type: 'phone',
    number: '447700900001'
  },
  answer_url: [
    'https://raw.githubusercontent.com/nexmo-community/ncco-examples/gh-pages/text-to-speech.json'
  ]
)

Fazer uma chamada externa em um aplicativo Ruby on Rails

Adicionar uma interface de usuário para criar uma chamada

Agora que já vimos como usar o cliente Ruby da Vonage para fazer chamadas de saída, vamos integrar a funcionalidade de chamadas de saída ao nosso aplicativo Rails com um formulário e um controlador simples. Precisaremos de uma interface de usuário agradável para lidar com o to, frome text campos. Você pode copiar e adicionar o formulário ao seu /app/views/outbound_calls/new.html.erb e CSS associado.

User interface for placing a call using the Vonage Voice API, allowing users to input sender and recipient phone numbers and a voice message.

Tratamento das respostas do NCCO para automação de voz

Agora, vamos implementar a lógica para que nosso formulário funcione. Primeiro, precisamos criar uma instância vazia de `Call` para carregar o formulário na página inicial. Em seguida, quando o formulário for enviado, chamamos o método `create`, que salva o `Call` em nosso banco de dados e, em seguida, o envia por meio do make_call método.

Veja o arquivo completo outbound_calls_controller.rb para ver como todo o código funciona em conjunto.

#app/controllers/outbound_calls_controller.rb


  def index
    @call = Call.new
  end

  def create
    @call = Call.new(safe_params)

    if @call.save
      make_call(@call)
      redirect_to new_outbound_call_url, notice: 'Call initiated'
      flash[:alert] = 'Something went wrong'
      render :new
    end
  end

  private

  def safe_params
    params.require(:call).permit(:to, :from, :text)
  end

end

O make_call método, então, inicia a chamada telefônica com a Voice API. Aqui, criamos um answer_url, que está alinhado com nosso show método.

def make_call(call)
    options = {
      to: [{ type: 'phone', number: call.to }],
      from: { type: 'phone', number: call.from },
      answer_url: ["https://#{ENV['VONAGE_SERVER_HOSTNAME']}/outbound_calls/#{call.id}"]
    }

    response = vonage.voice.create(options)

    call.update(
      uuid: response['uuid'],
      status: response['status']
    ) if response['status'] && response['uuid']
  end

Quando a API analisa o método `show`, ela encontra o NCCO, que a instrui a acionar o robô de chamadas. 

  def show
    call = Call.find(params[:id])
    render json: [
      {
        "action": "talk",
        "text": call.text,
        "language": "en-AU",
        "style": 3
      }
    ]
  end

Executando o aplicativo

Inicie seu servidor Rails:

rails s

Agora, acesse:

http://localhost:3000/outbound_calls/new

Preencha o formulário e clique em “Ligar”. Você deverá receber uma chamada Voice com o texto que digitou!

*O número de origem deve ser um número virtual da Vonage

Conclusão

Você conseguiu! Você configurou um aplicativo em Ruby on Rails para fazer chamadas de voz. Em posts futuros, vamos lidar com eventos de chamadas, receber chamadas e explorar interações de voz mais avançadas.

Se você tiver alguma dúvida ou sugestão para mais conteúdos sobre Ruby, envie-nos uma mensagem no Slack da Comunidade. Você também pode ficar por dentro do nosso conteúdo para desenvolvedores e dos eventos no X, anteriormente conhecido como Twitter.