Weiterleitung eines Anrufs über Voice Proxy mit PHP

Der heutige Beitrag zeigt Ihnen, wie Sie einen Voice-Anruf so umleiten können, dass er von einer anderen Nummer zu kommen scheint.

Dies ist nicht so zweifelhaft, wie es klingt: Es gibt viele zwingende geschäftliche Gründe, warum Sie die tatsächliche Nummer eines Anrufers vor den anderen Gesprächsteilnehmern verbergen möchten.

Ein klassisches Beispiel ist ein Online-Taxidienst. Um die Buchung so reibungslos wie möglich zu gestalten, möchten Sie, dass Ihr Kunde und Ihr Fahrer miteinander kommunizieren können. Aber Sie wollen nicht, dass der Fahrer die echte Nummer des Kunden kennt (weil Sie die Privatsphäre des Kunden schützen wollen) und umgekehrt wollen Sie nicht, dass Ihr Kunde die Nummer des Fahrers kennt und direkt Fahrten bucht, ohne Ihren Dienst zu nutzen.

Glücklicherweise ist dies in PHP mit der Nexmo Voice API wirklich einfach zu bewerkstelligen, also lasst uns loslegen! Der vollständige Quellcode ist auf Github verfügbar.

Schritte:

1. Abhängigkeiten installieren

2. Definieren Sie die Webhook-Endpunkte

3. Anrufereignisse protokollieren

4. Machen Sie Ihre Webhooks zugänglich

5. Kaufen Sie eine Nummer

6. Erstellen Sie eine Nexmo Voice API Anwendung

7. Verknüpfen Sie die Anwendung mit Ihrer Nexmo-Nummer

8. Rufen Sie Ihre virtuelle Nexmo-Nummer an

9. Implementierung der Proxy-Logik

10. Testen Sie den Voice-Proxy

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.

In diesem Lernprogramm wird auch eine virtuelle Telefonnummer verwendet. Um eine zu erwerben, gehen Sie zu Rufnummern > Rufnummern kaufen und suchen Sie nach einer Nummer, die Ihren Anforderungen entspricht.

Sind Sie bereit, mit dem Bau zu beginnen?

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

Abhängigkeiten installieren

Um mit eingehenden Anrufen über die Voice API von Nexmo zu arbeiten, müssen Sie Folgendes bereitstellen Webhooks bereitstellen, damit Nexmo Daten an Ihre Anwendung senden kann.

Wir verwenden slim um diese Webhooks zu programmieren: ein leichtes Web-Framework für PHP. Sie können mehr darüber erfahren slim hier.

Installieren Sie slim mit composer:

composer require slim/slim:^3.8

Definieren Sie die Webhook-Endpunkte

Erstellen Sie eine Datei namens index.php die den folgenden Code enthält:

<?php
use \Psr\Http\Message\ResponseInterface as Response;
use \Psr\Http\Message\ServerRequestInterface as Request;
require 'vendor/autoload.php';

$app = new \Slim\App;
$app->get('/webhooks/answer', function (Request $request, Response $response) {
  /* Code to process the inbound call */
});

$app->post('/webhooks/events', function (Request $request, Response $response) {
  /* Code that executes when an event is received */
});

$app->run();

Dieser Code erstellt eine neue slim Anwendung und definiert zwei Routen. Diese Routen entsprechen den folgenden Webhook-Endpunkten:

• /webhooks/answer: Nexmo's APIs stellen eine GET Anfrage an diesen Endpunkt, wenn Sie einen eingehenden Anruf auf Ihrer virtuellen Nummer erhalten.

• /webhooks/events: Nexmo's APIs stellen eine POST Anfrage an diesen Endpunkt, wenn ein wichtiges Ereignis eintritt (z.B. ein Anruf ringing, sein answered und completed), um Ihre Anwendung über den Status des Anrufs zu informieren.

Anrufereignisse protokollieren

Behandeln wir zunächst den /webhooks/events Endpunkt beschäftigen. Jedes Mal, wenn wir über ein Ereignis benachrichtigt werden, wollen wir es protokollieren. Dies wird Ihnen später bei der Fehlersuche helfen.

Dieses Beispiel verwendet den in PHP integrierten Web-Entwicklungsserver und die Funktion error_log() Funktion zur Ausgabe von Daten in eine Protokolldatei (event.log).

Erstellen Sie eine php.ini Datei im Stammverzeichnis Ihrer Anwendung, die die folgenden Einstellungen enthält:

error_log = ./event.log
log_errors = on
date.timezone = UTC

Aktualisieren Sie dann den /webhooks/events Handler, um eingehende Ereignisdaten zu protokollieren:

$app->post('/webhooks/events', function (Request $request, Response $response) {
    error_log($request->getBody());
});

Eingehende Anrufe abwickeln

Wenn Sie einen eingehenden Anruf erhalten, stellt die API von Nexmo eine GET Anfrage an Ihren /webhooks/answer Endpunkt und erwartet, dass die Antwort Anweisungen enthält, wie der Anruf zu verarbeiten ist.

Sie stellen diese Anweisungen in Form eines Nexmo Call Control Object (NCCO) im JSON-Format bereit. Das NCCO definiert die verschiedenen "Aktionen", die der Anruf ausführen muss, wie z.B. input das Sammeln von Ziffern, die der Benutzer auf seiner Telefontastatur drückt oder stream das Abspielen von Audio in den Anruf. Die vollständige Liste der Aktionen finden Sie in der NCCO-Referenz.

Bevor wir uns mit der Proxy-Logik beschäftigen, müssen wir zunächst sicherstellen, dass wir einen eingehenden Anruf auf unserer Nexmo-Nummer empfangen können.

Testen Sie Ihre Anwendung mit einer talk Aktion, die TTS (text-to-speech) verwendet, um Ihrem Anrufer eine Nachricht vorzulesen. Definieren Sie und geben Sie den folgenden NCCO in Ihrem /webhooks/answer Route-Handler:

$app->get('/webhooks/answer', function (Request $request, Response $response) {

    $ncco = [
        [
            'action' => 'talk',
            'text' => 'Thank you for calling. Everything appears to be working properly',
        ],
    ];
    return $response->withJson($ncco);
});

Machen Sie Ihre Webhooks zugänglich

Damit die Nexmo-APIs Anfragen an Ihre Webhook-Endpunkte stellen können, müssen sie über das Internet zugänglich sein.

Ein hervorragendes Werkzeug, um Ihre lokale Entwicklungsumgebung dem öffentlichen Internet zugänglich zu machen, ist ngrok. Unser Lehrgang zeigt Ihnen, wie Sie es installieren und verwenden können.

Starten Sie ngrok mit dem folgenden Befehl:

ngrok http 3000

Notieren Sie sich die öffentlichen URLs, die ngrok für Sie erstellt wurden. Diese ähneln den folgenden (unterscheiden sich aber von ihnen):

http://066d53c9.ngrok.io -> localhost:3000
https://066d53c9.ngrok.io -> localhost:3000

Bei dem kostenlosen Tarif ändern sich bei jedem Neustart ngrok ändern sich die URLs und Sie müssen die Konfiguration Ihrer Voice API-Anwendung aktualisieren. Lassen Sie sie also für die Dauer dieses Tutorials laufen.

Kaufen Sie eine Nummer

Sie benötigen eine virtuelle Nexmo-Nummer, um Anrufe zu erhalten. Wenn Sie noch keine Nexmo-Nummer haben, können Sie diese einfach über die Vonage CLI.

Sie können die Vonage CLI mit dem Node-Paketmanager, npm:

npm install -g vonage-cli

Konfigurieren Sie dann die Vonage CLI mit Ihrem API-Schlüssel und -Geheimnis über das Entwickler-Dashboard:

vonage config:set --apiKey=YOUR_API_KEY --apiSecret=YOUR_API_SECRET

Um zu sehen, welche Numbers verfügbar sind, verwenden Sie vonage number:searchund geben Sie dabei Ihre zweistellige Landesvorwahl ein. Zum Beispiel, GB für Großbritannien oder US für die USA. Sie müssen sicherstellen, dass die von Ihnen erworbene Nummer für Sprachanrufe geeignet ist:

vonage number:search COUNTRY_CODE --features=VOICE

Wählen Sie eine Nummer aus der Liste und kaufen Sie sie mit dem folgenden Befehl:

vonage number:buy <NUMBER>

Sie werden aufgefordert, Ihren Kauf zu bestätigen. Notieren Sie sich die Nummer, die Sie gekauft haben.

Erstellen einer Nexmo Voice API Applikation

Sie müssen nun eine Nexmo Voice API Application erstellen. Eine Anwendung ist in diesem Zusammenhang nicht dasselbe wie die Anwendung, für die Sie gerade den Code geschrieben haben. Stattdessen handelt es sich um einen Container für die Konfigurations- und Sicherheitsinformationen, die Sie für die Nutzung der Voice API benötigen.

Hierfür verwenden Sie wieder die Vonage CLI. Sie müssen die folgenden Informationen angeben:

• Ein Name für Ihre Anwendung

• Die öffentliche URL zu Ihrem /webhooks/answer Endpunkt (z. B. https://066d53c9.ngrok.io/webhooks/answer)

• Die öffentliche URL zu Ihrem /webhooks/events Endpunkt (z. B. https://066d53c9.ngrok.io/webhooks/events)

• Name und Speicherort der Datei, die Ihre Sicherheitsnachweise enthält

Geben Sie im gleichen Verzeichnis wie Ihre PHP-Anwendung den folgenden Befehl ein und geben Sie die entsprechenden URLs für Ihre Webhook-Endpunkte an:

vonage apps:create “My Voice Proxy” --voice_answer_url=ANSWER_URL --voice_event_url=EVENT_URL

Dies konfiguriert eine Voice API Anwendung mit Ihren Webhooks. Die Voice Application wird durch eine eindeutige Anwendungs-ID identifiziert: Notieren Sie sich diese, da Sie sie im nächsten Schritt benötigen. Sie sollten auch Ihren privaten Schlüssel kopieren, den Sie durch Ausführen von:

vonage apps:show

Verknüpfen Sie die Anwendung mit Ihrer Nexmo-Nummer

Als nächstes müssen Sie Ihre Voice API-Anwendung mit Ihrer Nexmo-Nummer verknüpfen.

Führen Sie den folgenden Befehl aus und ersetzen Sie APPLICATION_ID durch den vom Befehl vonage apps:create den Sie im vorangegangenen Schritt ausgeführt haben:

vonage apps:link APPLICATION_ID --number=NEXMO_NUMBER

Verifizieren Sie, dass die Nummer und die Anwendung verknüpft sind, indem Sie den vonage apps:show Befehls. Sie können diese Informationen auch in der Entwickler-Dashboard.

Rufen Sie Ihre virtuelle Nexmo-Nummer an

Wenn ngrok auf Port 3000 in einem Terminalfenster läuft, starten Sie Ihre PHP-Anwendung auf demselben Port in einem anderen:

php -S localhost:3000 -c php.ini

Rufen Sie Ihre Nexmo-Nummer an. Wenn alles in Ordnung ist, sollten Sie die Nachricht hören, die Sie in Ihrem NCCO definiert haben, und dann wird der Anruf beendet.

Prüfen Sie die event.log und notieren Sie, welche Ereignisse während des Anrufs aufgezeichnet wurden.

Implementierung der Proxy-Logik

Um einen Voice-Proxy einzurichten, können wir den eingehenden Anruf mit der Nummer des Empfängers verbinden und unsere virtuelle Nexmo-Nummer verwenden, um die echte Nummer des eingehenden Anrufers zu verbergen.

Erstellen Sie zwei String-Konstanten, um diese Numbers zu speichern:

• FROM_NUMBER: Ihre virtuelle Nexmo-Nummer

• TO_NUMBER: Eine Festnetz- oder Mobilfunknummer, die Sie zu Testzwecken verwenden können. Diese sollte sich von der Nummer unterscheiden, die Sie für den ersten Anruf verwenden werden.

define(FROM_NUMBER, /* Your Nexmo number */);
define(TO_NUMBER, /* Your target number */;

Beide Numbers sollten den Ländercode enthalten und führende Nullen weglassen. Im Vereinigten Königreich lautet der Ländercode zum Beispiel 44. Wenn meine Handynummer also lautet 07700 900004lautet, ist das korrekte Format 447700900004.

Verwenden Sie die NCCO connect Aktion, um den eingehenden Anrufer mit dem Empfänger zu verbinden. Ersetzen Sie die aktuelle NCCO in Ihrem /webhooks/answer Endpunkt durch die folgende:

    $ncco = [
        [
            'action' => 'connect',
            'from' => FROM_NUMBER,
            'endpoint' => [
                [
                    'type' => 'phone',
                    'number' => TO_NUMBER,
                ],
            ],
        ],
    ];

Testen des Voice-Proxys

Stellen Sie sicher, dass ngrok noch in einem Terminalfenster läuft und starten Sie Ihre PHP-Anwendung in einem anderen Fenster neu:

php -S localhost:3000 -c php.ini

Rufen Sie Ihre virtuelle Nexmo-Nummer an. Wenn der Anruf angenommen wird, sollte sofort Ihre zweite Nummer angerufen werden. Dieser Anruf sollte von Ihrer Nexmo-Nummer ausgehen und nicht von der Nummer, über die Sie den Anruf getätigt haben.

Das war's! Sie haben nun einen einfachen Voice-Proxy implementiert, der die echte Nummer des Anrufers verbirgt.

Weitere Lektüre

Wenn Sie mehr über die Voice API erfahren möchten, sollten Sie sich die folgenden Ressourcen ansehen:

• Voice API Übersicht

• Voice API-Referenz

• NCCO-Referenz