Wie man mit Ruby on Rails ausgehende Telefonanrufe tätigt

Einführung

Möchten Sie in Ruby on Rails ausgehende Telefonanrufe tätigen? Mit der Vonage Voice API können Sie eine programmatische Anruflösung erstellen, die Text-to-Speech, Anrufaufzeichnung und Live-Sprachinteraktionen in nur wenigen Codezeilen unterstützt.

Diese Anleitung zeigt, wie man mit Ruby on Rails und dem Vonage SDK ausgehende Text-to-Speech-Telefonanrufe sendet.

TL;DR Überspringen Sie den Anfang und finden Sie den gesamten Schnellstart-Code auf 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.

Voraussetzungen

• Ruby und Rails installiert auf Ihrem Rechner. Für alle Fragen zu den Rails-Konventionen ist die Dokumentation sehr ausführlich.

• Ein Vonage API-Konto.

• Eine virtuelle Vonage-Nummer mit Sprachfunktionen.

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.

Wie Sie Ihre Ruby on Rails-Anwendung einrichten

Wenn Sie die vorherigen Artikel noch nicht gelesen haben, müssen Sie eine neue Rails-Anwendung erstellen und ein paar Einstellungen vornehmen. Wenn Sie die Einrichtung bereits vorgenommen haben, fahren Sie mit dem Abschnitt "Einrichten von Umgebungsvariablen" fort.

Ein neues Rails-Projekt erstellen

Beginnen Sie mit der Erstellung einer neuen Rails-Anwendung:

rails new vonage-voice-quickstart

Navigieren Sie in das Projektverzeichnis:

cd vonage-voice-quickstart

Installieren Sie die Vonage Voice API für Ruby on Rails

Bearbeiten Sie die Gemfile und fügen Sie das Vonage SDK zusammen mit dotenv für die Verwaltung von Umgebungsvariablen hinzu:

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

Installieren Sie nun die Abhängigkeiten:

bundle install

Verwendung von ngrok zur Handhabung von Webhooks für Sprachanrufe

Vonage muss wissen, was zu tun ist, wenn ein Anruf angenommen wird, und wir sagen es ihm mit den Informationen in der antwort_url die wir in unserem NCCO angeben. Keine Sorge, dazu später mehr. Für den Moment müssen Sie nur verstehen, dass unsere Ruby on Rails-Anwendung in der Entwicklung auf Port 3000 läuft, so dass wir lokal unter localhost:3000 darauf zugreifen können. Das funktioniert allerdings nur auf unserem Computer! Wir müssen unsere antwort_url auch für Vonage zugänglich machen. Sie können ngrok verwenden, um Ihren lokalen Server auf sichere Weise über HTTP öffentlich zugänglich zu machen. Also jetzt, in einem separaten Registerkarte von dem aus Sie Ihren Rails-Server betreiben werden, einen ngrok-Tunnel auf Port 3000 öffnen.

ngrok http 3000

Fügen Sie Ihre ngrok-URL als config.host in Ihrer entwicklung.rb Datei ein. Wir verwenden die Umgebungsvariable VONAGE_SERVER_HOSTNAMEverwenden, um unsere Anwendung dynamischer zu gestalten. Wir werden sie später im Tutorial definieren.

# config/environments/development.rb

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

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

Erstellen einer Vonage-Anwendung

Für dieses Lernprogramm, aktivieren Sie die Sprachfunktion und fügen Sie Ihre ngrok-URLs in den Webhook-Bereich ein. Wie das aussehen soll, sehen Sie weiter unten im Abschnitt Sprachfähigkeiten aktivieren.

Stellen Sie sicher, dass Sie einen privaten Schlüssel erzeugen, indem Sie auf "Öffentlichen und privaten Schlüssel erzeugen" klicken. Dadurch wird eine private.key-Datei auf Ihren Computer heruntergeladen. Verschieben Sie dann die private.key-Datei in das Stammverzeichnis Ihrer Rails-Anwendung.

Notieren Sie sich die Anwendungs-ID, wenn Ihre Anwendung erstellt wird. Sie benötigen die Anwendungs-ID in dem Schritt Umgebungsvariablen.

Aktivieren von Sprachfunktionen in Vonage

Wenn ngrok läuft, können Sie nun die Voice API in Ihrer Vonage Anwendung aktivieren. Schalten Sie den Abschnitt Voice ein. Sie können vorerst Platzhalter-URLs für die Webhooks hinzufügen. Wir werden diese in weiteren Blogbeiträgen aktualisieren.

• Antwort-URL: https://example.com/inbound_calls

• Veranstaltung URL: https://example.com/call_events

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

Einrichten von Umgebungsvariablen

Erstellen Sie eine .env Datei und fügen Sie Ihre Vonage-Anmeldedaten hinzu:

# .env

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

Halten Sie Ihre Anmeldeinformationen sicher>> Übertragen Sie niemals .env Dateien an Ihr Projektarchiv! Stellen Sie sicher, dass .env und private.key in Ihrem .gitignore.

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

So definieren Sie das Rails-Modell und den Controller

Generierung eines Rails-Modells für Anrufe

Nun müssen wir unser Aufrufmodell erstellen, das die Attribute und deren Speicherung in der Datenbank definiert. Wir werden den Ruby on Rails-Generator verwenden, um unsere Modelle zu generieren und unsere Controller zu generieren.

Wir brauchen 6 Felder:

• to: der Empfänger des Anrufs

• from: der Absender des Anrufs

• textInhalt eines Text-to-Speech-Anrufs

• uuiddie eindeutige Kennung einer einzelnen Call-Instanz (ein einzelner Teil eines Telefonats)

• statusOb ein Anruf erfolgreich zugestellt worden ist oder nicht. Weitere Informationen finden Sie in der API-Referenz

• conversation_uuid: der eindeutige Bezeichner für ein ganzes Gespräch, das mehrere Telefonanrufe umfassen kann (jeder Teilnehmer an einem Telefonanruf hat eine eindeutige uuid, die conversation_uuid fasst sie zusammen)

• is_inboundOb der Anruf von unserer Anwendung gesendet oder von unserer Anwendung empfangen wird, wird in den folgenden Blogbeiträgen eine Rolle spielen

Führen Sie den folgenden Rails-Generator aus und migrieren Sie:

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

Erstellen wir unseren Controller, der unsere Logik verarbeitet.

rails g controller OutboundCalls new create show

Und wir müssen unsere Datenbank mit dem neuen Modell aktualisieren.

rails db:migrate

Zum Schluss fügen wir unsere Routen für ausgehende Anrufe hinzu.

# config/routes.rb

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

Initialisierung des Vonage Ruby-Clients

Um den Ruby-Client und die Sprach-API zu nutzen, müssen wir eine Instanz mit unseren Vonage-Zugangsdaten initialisieren, die in unserer Umgebungsdatei gespeichert sind. Neben der Sprach-API ermöglicht uns der Ruby-Client einen einfachen Zugriff auf mehr als 15 Vonage-APIs. Sie können mehr über die unterstützten APIs.

Bevor wir den Ruby-Client in einer vollständigen Rails-Anwendung aktivieren, wollen wir sehen, wie wir ihn allgemeiner in Ruby-Code verwenden können. Um den Client zu verwenden, müssen wir lediglich eine Instanz mit den in unserer Umgebungsdatei gespeicherten Anwendungsinformationen initialisieren.

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

Wie man in Ruby einen ausgehenden Sprachanruf tätigt

Nachdem unser Client nun initialisiert ist, ist es ganz einfach, einen ausgehenden Anruf zu erstellen. Wir rufen die voice Methode auf, um dem Client mitzuteilen, dass er die Sprach-API verwenden soll, und rufen dann create mit den erforderlichen Feldern auf.

Die Sprach-API erstellt einen Aufruf mit den to und from Feldern, und wenn der Anruf angenommen wird, sucht sie nach weiteren Anweisungen in den Feldern answer_url. Sie benötigt ein NCCO-Anrufobjekt, eine json-Datei mit Optionen wie Abspielen einer Nachricht, Verbindung mit einer anderen Nummer, Annahme von Benutzereingaben usw.

Weitere Informationen finden Sie in der Call Control Object-Leitfaden.

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'
  ]
)

Ausgehende Anrufe in einer Ruby on Rails-Anwendung tätigen

Hinzufügen einer Benutzeroberfläche zum Erstellen eines Anrufs

Nachdem wir uns nun damit beschäftigt haben, wie man den Vonage Ruby-Client verwendet, um ausgehende Anrufe zu tätigen, wollen wir nun die Funktionalität für ausgehende Anrufe in unsere Rails-App mit einem einfachen Formular und Controller integrieren. Wir brauchen eine schöne UI, um die to, from, und text Felder. Sie können das Formular kopieren und zu Ihrer /app/views/outbound_calls/new.html.erb Ansicht und zugehörige CSS.

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

Handhabung von NCCO-Antworten für die Sprachautomatisierung

Nun wollen wir die Logik implementieren, damit unser Formular funktioniert. Zunächst müssen wir eine leere Call-Instanz erstellen, um das Formular in den Index zu laden. Wenn das Formular dann abgeschickt wird, rufen wir die create-Methode auf, die den Call in unserer Datenbank speichert und ihn dann über die make_call Methode.

Siehe die vollständige outbound_calls_controller.rb Datei, um zu sehen, wie der gesamte Code zusammenarbeitet.

#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

Die Methode make_call Methode leitet dann den Telefonanruf mit der Sprach-API ein. Hier erstellen wir eine dynamische answer_urlMethode, die mit unserer show Methode entspricht.

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

Wenn die API in der Show-Methode nachschaut, findet sie den NCCO, der ihr sagt, dass sie den Roboteraufrufer auslösen soll.

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

Ausführen der Anwendung

Starten Sie Ihren Rails-Server:

rails s

Jetzt besuchen:

http://localhost:3000/outbound_calls/new

Füllen Sie das Formular aus und drücken Sie auf Anrufen. Sie sollten einen Sprachanruf mit dem von Ihnen eingegebenen Text erhalten!

*Die Absendernummer muss eine virtuelle Nummer von Vonage sein

Schlussfolgerung

Sie haben es geschafft! Sie haben eine Ruby on Rails-Anwendung eingerichtet, um ausgehende Sprachanrufe zu tätigen. In zukünftigen Beiträgen werden wir Anrufereignisse behandeln, eingehende Anrufe empfangen und weitere fortgeschrittene Sprachinteraktionen sehen.

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.