Wie man eine einfache IVR mit Ruby on Rails erstellt

Wir haben dieses Beispiel mit Ruby 3.0.0 und Ruby on Rails 6.1.4.1 und der Vonage Voice API erstellt.

Haben Sie schon einmal ein Unternehmen angerufen und wurden aufgefordert, den Menüaufforderungen zu folgen? Wenn ja, dann haben Sie mit einer Interactive Voice Response (IVR) interagiert. Die IVR reagiert auf Eingaben des Anrufers, in der Regel in Form von Zifferntastatur-Eingaben. Mit Ruby on Rails und der Vonage Voice API können Sie Ihre eigene IVR erstellen.

In dieser Anleitung werden wir eine kleine Rails-Anwendung erstellen, die einen einfachen IVR-Dienst hostet. Nachdem wir fertig sind, können Sie diese Anwendung erweitern, um alles zu bauen, was Sie brauchen. In diesem Tutorial wird unsere Anwendung eine numerische Eingabe (auch DTMF-Code genannt) vom Anrufer akzeptieren und dann dem Anrufer die eingegebene Eingabe vorsprechen.

Voraussetzungen

Sie benötigen Folgendes, um diesem Tutorial folgen zu können:

• Ruby on Rails

• ngrok damit Vonage auf den Dienst zugreifen kann, der lokal auf Ihrem Rechner läuft

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.

Erste Schritte

Erstellen einer Rails-Anwendung

Als Erstes müssen wir eine neue Rails-Anwendung erstellen. Sie können dies auf Ihrer Kommandozeile mit dem folgenden Befehl tun:

Der obige Befehl erstellt unsere Rails-App in /vonage-rails-ivr-demound überspringt auch die Installation einer Datenbank. In diesem Tutorial werden wir unsere Daten nicht persistieren, also brauchen wir sie nicht.

Wechseln Sie die Verzeichnisse in den vonage-rails-ivr-demo Ordner und führen Sie bundle install über die Befehlszeile aus. Vonage hat zwar ein robustes Ruby SDK gemund ein Rails-Initialisierungs-Gembesitzt, müssen wir beides für diese Anwendung nicht installieren.

Einen IVR-Controller erstellen

Nachdem unsere Anwendung nun erstellt wurde, besteht der nächste Schritt darin, den Controller zu erstellen, der auf zwei Routen mit Nexmo Anrufsteuerungsobjekten (NCCO). Die erste Route wird den Anruf entgegennehmen und den Anrufer auffordern, eine Nummer auf seiner Tastatur zu drücken. Die zweite Route wird die Nummer, die der Anrufer eingegeben hat, wiedergeben.

Um unseren Controller zu erstellen, führen Sie Folgendes in der Befehlszeile aus:

Sobald dies abgeschlossen ist, öffnen Sie die Anwendung in Ihrem bevorzugten Code-Editor und bearbeiten Sie die neu generierte /app/controllers/ivr_controller.rb. Wir werden nun Methoden für unsere beiden Routen hinzufügen. Zuerst erstellen wir die #answer Methode, die den Anruf entgegennehmen wird:

# 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

Wie oben gezeigt, bietet die #answer Methode zwei NCCO-Anweisungen bereit. Die erste ist die talk Aktion, bei der der Aufrufer von der Anwendung begrüßt wird. Ich habe das Gebietsschema Vereinigte Staaten und den Stil Nummer 9 gewählt. Die Voice API bietet eine solide Auswahl an Sprach- und Stiloptionen, mehr dazu im Text-to-Speech-Leitfaden. Anmerkung: Der frühere Parameter voiceName ist jetzt veraltet. Lesen Sie mehr.

Die zweite Aktion ist die input Aktion, und wir haben den optionalen Parameter submitOnHash auf true gesetzt, damit die Eingabe endet, wenn der Benutzer die Rautetaste auf seinem Telefon drückt. Wir versehen auch den erforderlichen eventUrl Parameter mit einer URL, die auf unsere andere Route verweist, die auf die Benutzereingabe reagieren wird.

Schließlich sehen wir, dass die #answer Methode eine konstante Variable namens BASE_URL verwendet, die derzeit als leere Zeichenkette definiert ist. Später in dieser Schritt-für-Schritt-Anleitung werden wir das mit unserer ngrok extern zugänglichen URL ausfüllen.

Fügen wir nun unsere zweite und letzte Controller-Aktion hinzu, #event. Diese wird auf die Anrufereingabe reagieren, indem sie dem Anrufer die von ihm gewählte Nummer zurückspricht:

# 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

Insgesamt sieht unser Controller dann wie folgt aus:

# 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

Routen definieren

Als nächstes müssen wir unsere Routen definieren. Dazu bearbeiten wir die Datei /config/routes.rb Datei bearbeiten und die beiden URL-Pfade hinzufügen, die unseren beiden Controller-Aktionen entsprechen:

# routes.rb

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

ngrok konfigurieren

Ab Rails 6 müssen Sie Ihrer ngrok-Tunnel-URL die Berechtigung geben, auf Ihre Entwicklungsumgebung zuzugreifen. Die NGROK_URL wird im folgenden Schritt durch Ihre tatsächliche ngrok URL ersetzt. Fügen Sie das Folgende zu Ihrer development.rb Datei hinzu.

Anmerkung: Sie müssen Ihren Rails-Server nach der Bearbeitung neu starten development.rb neu starten, damit die Änderungen wirksam werden.

#development.rb

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

Jetzt ist unsere Rails-Anwendung einsatzbereit. Richten wir nun unsere ngrok-URL für den externen Zugriff ein. Diese benötigen wir für den letzten Schritt, d.h. die Erstellung unserer Vonage-Anwendung und unserer von Vonage bereitgestellten Telefonnummer.

Verbindung zur Außenwelt

ngrok einrichten

Es gibt mehrere Möglichkeiten, unseren lokalen Entwicklungsserver von außen zugänglich zu machen, aber eine der einfachsten ist ngrok. Sie können lesen diesen Artikel für eine genauere Erklärung, wie ngrok funktioniert.

Für unsere Zwecke müssen wir es jedoch nur zum Laufen bringen und die URL kopieren, die es uns liefert.

Um ngrok zu starten, öffnen Sie ein neues Terminal-Fenster und führen Sie folgendes in der Kommandozeile aus:

Sie sehen nun eine ngrok-Protokollierungsschnittstelle in Ihrem Terminalfenster. Am oberen Rand der Schnittstelle befindet sich eine Zeile, die mit Forwarding beginnt und zwei URLs enthält. Die erste ist die von außen zugängliche ngrok-URL, die mit ngrok.io gefolgt von http://localhost:3000wobei es sich um Ihren lokalen Entwicklungsserver handelt. Wenn Sie oder Vonage nun die ngrok.io URL kontaktieren, wird sie an Ihren lokalen Server weitergeleitet.

Jetzt wäre ein guter Zeitpunkt, um zurück zur ivr_controller.rb zurückzukehren und die leere Zeichenkette durch Ihre ngrok-URL für die BASE_URL Konstante zu ersetzen. Sie sollten auch Ihre ngrok-URL für NGROK_URL in der development.rb Datei ersetzen. Wir werden sie auch im nächsten Schritt verwenden, wenn wir unseren Vonage Account, die Telefonnummer und die Voice Anwendung einrichten.

Verbinden Sie sich mit Vonage

Einen Vonage Account einrichten

Damit unsere Voice-Anwendung funktioniert, benötigen wir einen Vonage Account, eine von Vonage eingerichtete Telefonnummer, eine Vonage Anwendung und schließlich müssen wir unsere Anwendung mit unserer Telefonnummer verknüpfen.

Sie können kostenlos einen Account bei Vonage erstellen, und als zusätzlichen Bonus erhalten Sie eine Gutschrift von 2 Euro auf Ihr Konto, damit Sie Ihre neue Anwendung nutzen können. Besuchen Sie das Vonage API Entwickler Dashboard und folgen Sie den Anmeldeschritten, wenn Sie noch kein Vonage API Developer Account haben. Sobald Sie die Anmeldung abgeschlossen haben, sehen Sie Ihr Vonage API Developer Dashboard.

Klicken Sie im Menü auf der linken Seite auf den Voice menu Eintrag. Sie sehen dann die folgenden Optionen:

voice menu options

Klicken Sie auf die Option Getting started und Sie werden auf eine Seite weitergeleitet, auf der Sie die Text-to-Speech-Funktion testen oder eine neue Vonage-Anwendung einrichten können. Suchen Sie das folgende Create an application Formular:

create application form

Füllen Sie das Formular mit den folgenden Angaben aus:

• Application name Textfeld eingeben vonage-rails-ivr-demo

Wenn Sie fertig sind, klicken Sie auf die Create Application Schaltfläche.

Nachdem die Anwendung erstellt wurde, können Sie ein öffentliches/privates Schlüsselpaar erzeugen. Wir werden sie in diesem Lernprogramm nicht verwenden, aber es ist gut zu wissen, wo sie sich befinden, falls Sie diese Anwendung um weitere Funktionen erweitern möchten.

Sie haben nun eine Vonage Voice-Anwendung erstellt. Als Nächstes müssen Sie eine Vonage-Telefonnummer erwerben und sie mit dieser Anwendung verknüpfen. Klicken Sie auf die Schaltfläche Configure application Wie unten zu sehen:

configure application button

Dadurch werden Sie auf die Einstellungsseite für Ihre Anwendung weitergeleitet. In der zweiten Hälfte der Seite können Sie Ihre Anwendung mit den von Vonage bereitgestellten Telefonnummern verknüpfen. Klicken Sie auf die Schaltfläche Buy numbers und Sie werden auf eine Seite weitergeleitet, auf der Sie das Land, die Funktionen, den Typ und die vier Ziffern, die die Nummer haben soll, auswählen können.

buy numbers menu

Für unsere Zwecke: Wählen Sie das Land, in dem Sie sich gerade befinden, damit der Anruf für Sie ein Ortsgespräch ist; wählen Sie Voice für die Merkmale und entweder Handy oder Festnetz für den Typ. Für das Textfeld brauchen Sie nichts einzugeben. Number Textfeld eingeben. Wenn Sie auf Searchklicken, wird eine Liste der verfügbaren Telefonnummern angezeigt.

Wählen Sie eine aus, indem Sie auf die Schaltfläche Buy und klicken Sie auf die schwarze Buy und klicken Sie in der Bestätigungsaufforderung noch einmal auf die schwarze Schaltfläche.

Sobald Sie die Nummer besitzen, können Sie sie mit Ihrer vonage-rails-ivr-demo Voice-Anwendung verknüpfen. Klicken Sie dazu auf die Option Your applications in der linken Leiste. Navigieren Sie zurück zu Ihrer Anwendungsseite. Jetzt sehen Sie Ihre neu erworbene Telefonnummer in der zweiten Hälfte der Seite, wie unten dargestellt:

link numbers menu

Klicken Sie einfach auf die weiße link Schaltfläche. Die Schaltfläche wird rot und ändert sich in unlink. Ihre Vonage-Telefonnummer ist nun mit Ihrer Anwendung verknüpft. Der letzte Schritt besteht darin, die Vonage-Anwendung so zu konfigurieren, dass sie Anrufe annimmt und an die IVR-Rails-Anwendung weiterleitet. Klicken Sie auf die Schaltfläche edit Schaltfläche im oberen Bereich unter dem Namen Ihrer Anwendung. Sie werden zu einer Seite namens Edit vonage-rails-ivr-demo. Scrollen Sie, bis Sie den folgenden Abschnitt Capabilities finden:

Voice API Capabilities Form

Füllen Sie das Formular mit den folgenden Angaben aus:

• Answer URL Textfeld erneut Ihre ngrok-URL ein: https://[ngrok url here]/answer

• Event URL Textfeld Ihre ngrok-URL ein: https://[ngrok url here]/event

Blättern Sie zum unteren Ende der Seite und klicken Sie auf die save-changes Schaltfläche.

Mit diesem letzten Schritt sind Sie fertig! Sie haben nun eine voll funktionsfähige einfache IVR-Rails-Anwendung, die von Vonage betrieben wird. Sie können sie ausprobieren, indem Sie Ihren Rails-Server starten und mit dem ebenfalls laufenden ngrok Ihre Anwendung unter der soeben erworbenen Telefonnummer anrufen.

Weitere Lektüre

Wenn Sie mehr über das Gesprochene erfahren möchten, sollten Sie sich mit den folgenden Themen befassen:

• NCCO-Referenz

• Voice API Übersicht

• Voice API-Referenzhandbuch

• Aufbau einer Twitter IVR mit der Nexmo Voice API