Empfangen von Sprachanruf-Ereignissen mit Ruby on Rails

Zuvor haben wir gelerntwie man ausgehende Anrufe mit Ruby on Rails Sprachintegration. Beim Versuch, einen Anruf zu tätigen, können jedoch so viele Dinge passieren. War der Anruf erfolgreich? Hat der Empfänger abgenommen? Hat das Telefon überhaupt geklingelt? Mit Ruby on Rails Voice-Anwendungen können wir den Anrufstatus programmatisch mit der Voice-API und dem Anrufereignisse Webhook.

Dieses Tutorial zeigt Ihnen, wie Sie mit Vonage Webhooks Sprachanrufe in eine Ruby on Rails Anwendung integrieren können.

TL;DR Überspringen Sie den Anfang und finden Sie den gesamten Schnellstart-Code auf GitHub.

Voraussetzungen

• Ein ngrok-Konto

• Virtuelle Nummer von Vonage

• Ruby on Rails-Anwendung, wie zuvor beschrieben

Vonage API-Konto

Um dieses Tutorial durchzuführen, benötigen Sie ein Vonage API-Konto. Wenn Sie noch keines haben, können Sie sich noch heute anmelden und mit einem kostenlosen Guthaben beginnen. Sobald Sie ein Konto haben, finden Sie Ihren API-Schlüssel und Ihr API-Geheimnis oben auf dem Vonage-API-Dashboard.

Sind Sie bereit, mit dem Bau zu beginnen?

Erleben Sie nahtlose Konnektivität, Echtzeit-Messaging und kristallklare Sprach- und Videoanrufe - alles auf Knopfdruck.

Was ist ein Anrufereignis?

Wenn Sie einen Sprachanruf über die Sprach-APItätigen, sendet die Plattform den Anruf nicht einfach nur und vergisst ihn, sondern sie verfolgt Schritt für Schritt alles, was mit dem Anruf geschieht. Jede wichtige Aktion während des Lebenszyklus des Anrufs löst ein Anrufereignis aus.

Ein Anrufereignis ist eine Echtzeit-Benachrichtigung, die Ihrer Anwendung mitteilt, was mit dem Anruf geschieht. Zum Beispiel:

• Wenn der Aufruf erstellt wird, erhalten Sie eine gestartet Ereignis.

• Wenn das Telefon zu klingeln beginnt, erhalten Sie ein Klingeln Ereignis. Wenn der Anruf angenommen wird, erhalten Sie ein beantwortet Ereignis.

• Wenn die Leitung besetzt ist, der Anruf abgewiesen wird oder der Anruf aus irgendeinem Grund fehlschlägt, erhalten Sie Ereignisse wie Besetzt, abgewiesenoder fehlgeschlagen.

Jedes dieser Ereignisse wird über einen Webhook an Ihren Server gesendet, so dass Sie programmgesteuert reagieren können. Sie können eine Benutzeroberfläche aktualisieren, Anrufdetails protokollieren, eine automatische Antwort auslösen oder die Abrechnung abwickeln.

Um diese Ereignisse zu erfassen, müssen Sie beim Einrichten Ihres Voice API-Anrufs eine Ereignis-Webhook-URL konfigurieren. Auf diese Weise POST Vonage automatisch detaillierte Ereignisdaten an Ihren Server, während der Anruf die verschiedenen Phasen durchläuft.

Wie wir unsere Ruby on Rails App mit Ngrok öffentlich zugänglich machen

In Fortsetzung des vorherigen Blog-BeitragUnsere Ruby on Rails-Anwendung läuft in der Entwicklung auf Port 3000, so dass wir lokal unter localhost:3000 darauf zugreifen können. Das funktioniert allerdings nur auf unserem Computer!

Sie können ngrok verwenden, um Ihren lokalen Server sicher über HTTP öffentlich zu machen. So, jetzt in einem separaten Registerkarte Ihres Rails-Servers einen ngrok-Tunnel auf Port 3000.

ngrok http 3000

Fügen Sie unbedingt Ihre ngrok-URL als config.host in der Datei development.rb hinzufügen. Wir verwenden die Umgebungsvariable VONAGE_SERVER_HOSTNAMEverwenden, um unsere Anwendung dynamischer zu machen.

Für weitere Hilfe, siehe wie man anfängt und ngrok in Rails benutzt.

# config/environments/development.rb

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

Setzen Sie nun in unserer .env-Datei Ihren VONAGE_SERVER_HOSTNAME auf Ihre ngrok-URL.

# .env

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

Bearbeiten Sie Ihre Vonage-Anwendung aus dem vorherigen Tutorial in dem Dashboard um die ngrok URL in Ihren Webhooks hinzuzufügen. Fügen Sie in das Feld Status-URL Ihre ngrok-URL ein, gefolgt von /anruf_ereignisse. Stellen Sie sicher, dass die Anfrage als POST gesendet wird.

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

Sobald Sie auf Speichern klicken, wird ngrok nun Anfragen an den Endpunkt /call_events an Ihre Rails-Anwendung weiterleiten! Aber es gibt ein kleines Problem: Unsere Rails-Anwendung hat diesen Endpunkt nicht.

Wie man Webhooks für Anrufereignisse in Rails handhabt

Jetzt, wo Vonage den Status an die Datei /call_events Endpunkt weiterleitet, müssen wir unsere Anwendung aktualisieren und eine Route erstellen, die dies verarbeitet.

# config/routes.rb


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


	...previous routes...

Aber was wird dort passieren? Unsere Anwendung akzeptiert das Anrufereignis und analysiert es nach den relevanten Informationen. Sie können sehen, wie ein typisches Anrufereignis aussieht:

{
"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"
}

Das Format der enthaltenen Daten hängt davon ab, welches Ereignis eingetreten ist. Siehe die vollständige Liste der Anrufereignisse für weitere Einzelheiten. Das wichtigste Feld ist der Status denn es gibt Aufschluss darüber, ob Ihre Nachricht zugestellt wurde und, falls nicht, was schief gelaufen ist.

Wir werden eine Logik erstellen, um unseren Anrufstatus auf der Grundlage des empfangenen Anrufereignisses zu aktualisieren. Lassen Sie uns einen neuen Controller in der Befehlszeile erstellen, um dies zu handhaben.

rails g controller CallEvents create

Unser Controller hat eine einzige, einfache erstellen Methode. Zunächst analysiert die Methode unser Anrufereignis und extrahiert die uuid; sie verwendet diese fremde ID, um den Anruf in unserer lokalen Datenbank zu finden. Anschließend aktualisiert sie den Status für diesen Anruf auf den aktuellen Status, den wir im Anrufereignis erhalten haben.

# 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

Sie können nun einen Anruf an Ihre Vonage-Nummer starten und Ihren Rails-Server beobachten, um zu sehen, wie sich der Anruf von Läuten zu beantwortet bis abgeschlossen. Und bei jedem Schritt aktualisiert ActiveRecord die Datenbank!

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

Schlussfolgerung

Sie haben es geschafft! Sie haben gelernt, wie Sie Ihre Ruby on Rails-Anwendung so einrichten, dass sie über ngrok auf einen Webhook wartet und dabei Ihre Datenbank aktualisiert! Im nächsten Beitrag werden wir auf dieser Anwendung weiter aufbauen, indem wir eingehende Anrufe annehmen.

Wenn Sie Fragen oder Vorschläge für weitere Ruby-Inhalte haben, schicken Sie uns eine Nachricht auf dem Gemeinschaft Slack. Sie können sich auch über unsere Inhalte und Veranstaltungen für Entwickler auf dem Laufenden halten X, früher bekannt als Twitter.