Recepción de eventos de llamadas de voz con Ruby on Rails

Anteriormente, aprendimos cómo hacer llamadas salientes usando Ruby on Rails Voice. Sin embargo, pueden ocurrir muchas cosas cuando intentas hacer una llamada. ¿Tuvo éxito la llamada? ¿Contestó el destinatario? ¿Ha sonado el teléfono? Con las aplicaciones Voice de Ruby on Rails, podemos hacer un seguimiento programático del estado de las llamadas con la Voice API y el Webhook de eventos de llamada Webhook de eventos de llamada.

Este tutorial te mostrará cómo integrar eventos de llamadas de voz en una aplicación Ruby on Rails utilizando webhooks de Vonage.

TL;DR Saltar adelante y encontrar todo el código de inicio rápido en GitHub.

Requisitos previos

• Una Account ngrok

• Número virtual de Vonage

• Aplicación Ruby on Rails, como se ha descrito anteriormente

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.

¿Qué es un evento de llamada?

Cuando realice una llamada de voz utilizando la Voice APIla plataforma no se limita a enviar la llamada y olvidarse de ella, sino que hace un seguimiento de todo lo que ocurre con la llamada, paso a paso. Cada acción significativa durante el ciclo de vida de la llamada desencadena un evento de llamada.

Un evento de llamada es una notificación en tiempo real que informa a tu aplicación de lo que está ocurriendo con la llamada. Por ejemplo:

• Cuando se cree la llamada, aparecerá un icono iniciado evento.

• Cuando el teléfono empiece a sonar, recibirás un timbre de llamada. Cuando se conteste la llamada, obtendrá un evento contestada contestada.

• Si la línea está ocupada, la llamada es rechazada o la llamada falla por alguna razón, obtendrá eventos como ocupado, rechazadao fallida.

Cada uno de estos eventos se envía a su servidor a través de un webhook para que pueda reaccionar mediante programación. Puede actualizar una interfaz de usuario, registrar los detalles de la llamada, activar una respuesta automática o gestionar la facturación.

Para capturar estos eventos, deberás configurar una URL de webhook de eventos al configurar tu llamada de Voice API. De esa manera, Vonage enviará automáticamente datos de eventos detallados a tu servidor a medida que la llamada pase por las diferentes etapas.

Cómo exponer públicamente nuestra aplicación Ruby on Rails con Ngrok

Continuación de la entrada anteriornuestra aplicación Ruby on Rails se está ejecutando en desarrollo en el puerto 3000, por lo que podemos acceder a ella localmente en localhost:3000. Sin embargo, ¡eso sólo funciona en nuestro ordenador!

Puede utilizar ngrok para exponer de forma segura su servidor local públicamente a través de HTTP. Así que ahora, en una pestaña separada de tu servidor rails, abre un túnel ngrok en el puerto 3000.

ngrok http 3000

Asegúrese de añadir su URL ngrok como config.host en tu archivo development.rb. Utilizaremos la variable de entorno VONAGE_SERVER_HOSTNAMEpara hacer nuestra aplicación más dinámica.

Para obtener más ayuda, consulte cómo empezar a usar ngrok en Rails.

# config/environments/development.rb

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

Ahora en nuestro archivo .env, configure su VONAGE_SERVER_HOSTNAME a su URL ngrok.

# .env

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

Edita tu aplicación de Vonage del tutorial anterior en el panel de control para agregar la URL de ngrok en tus webhooks. En el campo URL de estado, agrega tu URL ngrok seguida de /call_events. Asegúrese de que la solicitud se envía como POST.

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

Una vez que pulses guardar, ngrok reenviará las peticiones hechas al endpoint /call_events a tu aplicación Rails. Pero hay un pequeño problema: nuestra aplicación Rails no tiene ese endpoint.

Cómo manejar Webhooks de eventos de llamada en Rails

Ahora que Vonage está reenviando los estados a la carpeta /eventos_llamada actualicemos nuestra aplicación y creemos una ruta para manejarlo.

# config/routes.rb


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


	...previous routes...

Pero, ¿qué va a pasar ahí? Nuestra aplicación aceptará el evento de llamada y lo analizará para obtener la información relevante. Puedes ver cómo es un evento de llamada 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"
}

El formato de los datos incluidos depende del acontecimiento que se haya producido. Consulte la lista completa de eventos de llamada para más detalles. El campo más importante es el estado porque le indica si su mensaje ha sido entregado y, en caso negativo, qué ha fallado.

Vamos a crear algo de lógica para actualizar nuestro estado de llamada basado en el evento de llamada recibida. Vamos a generar un nuevo controlador en la línea de comandos para manejar esto.

rails g controller CallEvents create

Nuestro controlador tiene un único y sencillo comando crear simple. En primer lugar, el método analiza nuestro evento de llamada y extrae el uuid; utiliza este ID externo para encontrar la llamada en nuestra base de datos local. Luego actualiza el estado de esta llamada al estado actual que recibimos en el evento de llamada.

# 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

Ahora puedes iniciar una llamada a tu número de Vonage y ver en tu servidor de rieles cómo la llamada pasa de sonando a contestada a completada. Y en cada paso ActiveRecord actualiza la base de datos.

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

Conclusión

¡Lo has conseguido! Has aprendido a exponer tu aplicación Ruby on Rails a la escucha de un webhook a través de ngrok, actualizando tu base de datos en el proceso. Seguiremos desarrollando esta aplicación para aceptar llamadas entrantes en el próximo post.

Si tienes alguna pregunta o sugerencia sobre más contenidos de Ruby, envíanos un mensaje a la Slack de la comunidad. También puedes estar al tanto de nuestros contenidos y eventos para desarrolladores en X, antes conocido como Twitter.