Receber eventos de chamadas de voz com Ruby on Rails

Anteriormente, aprendemos como fazer chamadas de saída usando Ruby on Rails No entanto, muitas coisas podem acontecer quando você tenta fazer uma ligação. A ligação foi bem-sucedida? O destinatário atendeu? O telefone chegou a tocar? Com as Applications Ruby on Rails Voice, podemos acompanhar o status das ligações programaticamente usando a Voice API e os Webhook de Eventos de Chamada.

Este tutorial mostrará como integrar eventos de chamadas de voz em um aplicativo Ruby on Rails usando os webhooks da Vonage.

Resumo Pule esta parte e veja todo o códigos do Guia Rápido no GitHub.

Pré-requisitos

• Uma conta no ngrok

• Número virtual da Vonage 

• Aplicativo Ruby on Rails, conforme descrito anteriormente

O que é um evento de chamada?

Ao fazer uma chamada de voz usando a Voice API, a plataforma não se limita a enviar a chamada e esquecê-la; ela acompanha tudo o que acontece com a chamada, passo a passo. Cada ação significativa durante o ciclo de vida da chamada aciona um evento de chamada.

Um evento de chamada é uma notificação em tempo real que informa ao seu aplicativo o que está acontecendo com a chamada. Por exemplo:

• Quando a chamada for criada, você receberá um evento .

• Quando o telefone começar a tocar, você receberá um toque . Quando a chamada for atendida, você receberá um atendida .

• Se a linha estiver ocupada, a chamada for rejeitada ou falhar por algum motivo, você receberá eventos como ocupada, rejeitadaou falha.

Cada um desses eventos é enviado ao seu servidor por meio de um webhook para que você possa reagir programaticamente. Você pode atualizar uma interface de usuário, registrar detalhes da chamada, acionar uma resposta automatizada ou processar o faturamento.

Para capturar esses eventos, você precisará configurar uma URL de webhook de evento ao configurar sua chamada pela Voice API. Dessa forma, a Vonage enviará automaticamente, por meio de uma solicitação POST, dados detalhados do evento para o seu servidor à medida que a chamada passa pelas diferentes etapas.

Como disponibilizar publicamente nosso aplicativo Ruby on Rails com o Ngrok

Dando continuidade à post anterior do blog, nossa aplicação Ruby on Rails está rodando em modo de desenvolvimento na porta 3000, então podemos acessá-la localmente em localhost:3000. No entanto, isso só funciona no nosso computador!

Você pode usar o ngrok para expor com segurança seu servidor local ao público via HTTP. Então, agora, em uma aba separada do seu servidor Rails, abra um túnel do ngrok na porta 3000.

ngrok http 3000

Certifique-se de adicionar 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.

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

# config/environments/development.rb

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

Agora, no nosso arquivo .env, defina seu VONAGE_SERVER_HOSTNAME para a sua URL do ngrok.

# .env

# ngrok URL, don't include the protocol (https://)
VONAGE_SERVER_HOSTNAME=''

Edite seu aplicativo Vonage, criado no tutorial anterior, no painel de controle para adicionar a URL do ngrok aos seus webhooks. No campo “Status URL”, adicione sua URL do ngrok seguida de /call_events. Certifique-se de que a solicitação esteja sendo enviada como POST.

Configuring Voice API webhooks in the Vonage dashboard with answer, event, and fallback URLs

Assim que você clicar em “Salvar”, o ngrok passará a encaminhar as solicitações feitas ao endpoint /call_events para o seu aplicativo Rails! Mas há um pequeno problema: nosso aplicativo Rails não possui esse endpoint.

Como lidar com webhooks de eventos de chamada no Rails

Agora que a Vonage está encaminhando os status para o /call_events , vamos atualizar nosso aplicativo e criar uma rota para lidar com isso.

# config/routes.rb


Rails.application.routes.draw do
 resources :call_events, only: [:create]


	...previous routes...

Mas o que vai acontecer aí? Nosso aplicativo vai receber o evento de chamada e analisá-lo para extrair as informações relevantes. Você pode ver como é um evento de chamada típico:

{
"from": "442079460000",
"to": "447700900000",
"uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"conversation_uuid":
"CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"status": "ringing",
"direction": "outbound",
"timestamp": "2020-01-01T12:00:00.000Z"
}

O formato dos dados incluídos depende do evento que ocorreu. Consulte a lista completa de eventos de chamada para obter mais detalhes. O campo mais importante é o status , pois ele informa se sua mensagem foi entregue e, caso contrário, o que deu errado.

Vamos criar uma lógica para atualizar o status da chamada com base no evento de chamada recebida. Vamos gerar um novo controlador na linha de comando para lidar com isso.

rails g controller CallEvents create

Nosso controlador possui um único e simples método de criação . Primeiro, o método analisa nosso evento de chamada e extrai o uuid; ele usa esse ID externo para localizar a chamada em nosso banco de dados local. Em seguida, ele atualiza o status dessa chamada para o status atual que recebemos no evento de chamada.

# app/controllers/call_events_controller.rb
class CallEventsController < ApplicationController
  # We disable CSRF for this webhook call
  skip_before_action :verify_authenticity_token

  def create
    if params[:uuid]
      Call.where(uuid: params[:uuid])
		.find_or_create_by
          .first_or_create
          .update(
            status: params[:status],
            conversation_uuid: params[:conversation_uuid]
          )
    end

    head :ok
  end
end

Agora você pode iniciar uma chamada para o seu número da Vonage e observar no servidor Rails para ver como a chamada se desloca de toque para atendida e concluída. E a cada etapa, o ActiveRecord atualiza o banco de dados!

Terminal log output showing Vonage Voice API call event lifecycle using a Rails controller

Conclusão

Você conseguiu! Você aprendeu a configurar sua aplicação Ruby on Rails para receber um webhook via ngrok, atualizando seu banco de dados nesse processo! Vamos continuar a desenvolver essa aplicação, aceitando chamadas recebidas no próximo post.

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.