Erstellen eines Voice-Proxys mit PHP und Vonage

Einführung

In diesem Vonage-Tutorial zur Anrufweiterleitung erfahren Sie, wie Sie einen Voice-Anruf so umleiten, 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 (um die Privatsphäre des Kunden zu schützen), und Sie wollen auch nicht, dass der Kunde die Nummer des Fahrers kennt, damit er keine Fahrten direkt buchen kann, ohne Ihren Dienst zu nutzen.

Glücklicherweise kann dies in nur wenigen Schritten mit der Vonage Voice API in PHP implementiert werden, also los geht's!

TLDR; der vollständige Quellcode ist auf GitHub verfügbar.

Voraussetzungen

• PHP8.3+

• Komponist

• Ein Vonage API-Konto

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

Legen Sie ein Verzeichnis an, das Ihren Code enthält, und erstellen Sie dann mit Composer ein neues Projekt:

composer init

Sie können alle interaktiven Fragen überspringen, indem Sie auf Return drücken, dann werden die Standardwerte verwendet. Verweigern Sie das interaktive Hinzufügen von Paketen; wir werden alles, was wir für dieses Projekt benötigen, im nächsten Schritt hinzufügen.

Der Composer erzeugt seine Konfigurationsdatei composer.jsonund einen Abhängigkeitsordner, Anbieter.

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

In diesem Beispiel werden wir Folgendes verwenden Schlank-ein leichtgewichtiges PHP-Webframework, um diese Webhooks zu implementieren. Als Nächstes ziehen wir also das Slim-Framework und eine PSR-7-kompatible Schnittstelle für die Anfrage-/Antwort-Klassen, dann vlucas/phpdotenvfür den Umgang mit Umgebungsvariablen.

composer require slim/slim
composer require slim/psr7
composer require vlucas/phpdotenv

Nun, da alle Abhängigkeiten geklärt sind, können wir mit dem Schreiben unseres Codes fortfahren.

Definieren Sie die Webhook-Endpunkte

Erstellen Sie in Ihrem Arbeitsverzeichnis eine public/index.php Datei mit dem folgenden Code:

<?php
use Psr\Http\Message\ResponseInterface as Response;
use Psr\Http\Message\ServerRequestInterface as Request;
use Slim\Factory\AppFactory;


require __DIR__ . '/../vendor/autoload.php';


$app = AppFactory::create();


$app->addBodyParsingMiddleware();
$app->addRoutingMiddleware();
$app->addErrorMiddleware(true, true, true);


// Forward a call via proxy
$app->get('/webhooks/answer', function (Request $request, Response $response) {
   // Code to process the inbound call
});


$app->post('/webhooks/events', function (Request $request, Response $response, array $args) {
   // Code that executes when an event is received
   error_log('event received: ' . $request->getBody());
   return $response->withStatus(204);
});


$app->run();

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

• /webhooks/answer: Vonage stellt eine GET Anfrage an diesen Endpunkt, wenn Sie einen eingehenden Anruf auf Ihrer virtuellen Nummer erhalten.

• /webhooks/events: Vonage stellt eine POST eine Anfrage an diesen Endpunkt, wenn ein wichtiges Ereignis eintritt (z. B. ein Anruf läutet, wird angenommen und beendet), um Ihre Anwendung über den Status des Anrufs zu informieren.

Siehe die Webhook-Referenz für weitere Details.

Eingehende Anrufe abwickeln

Wenn Sie einen eingehenden Anruf erhalten, stellt die API von Vonage 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 als Call Control Object (NCCO) im JSON-Format bereit. Das NCCO definiert die verschiedenen "Aktionen", die der Anruf ausführen muss, wie z. B. input die Erfassung 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 eingehende Anrufe unter unserer Vonage-Nummer empfangen können.

Testen Sie Ihre Anwendung mit einer talk Aktion, die Text-to-Speech (TTS) 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'
        ]  
    ];

    $response->getBody()->write(json_encode($ncco));
    return $response->withHeader('Content-Type', 'application/json');
});

Machen Sie Ihre Webhooks zugänglich

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

Ein großartiges 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 8080

Notieren Sie sich die öffentliche URL, die ngrok für Sie erstellt hat.

https://123example.ngrok-free.app -> http://localhost:8080

Bei der kostenlosen Version generiert ngrok bei jedem Neustart eine neue URL, und Sie müssen die Konfiguration Ihrer Voice API Anwendung aktualisieren. Lassen Sie es also für die Dauer dieses Tutorials laufen.

Als Nächstes müssen wir die Vonage-Seite einrichten!

Kaufen Sie eine Vonage-Nummer

Erstellen einer Voice-fähigen Vonage-Applikation

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

Bevor Sie auf Neue Anwendung generierenklicken, stellen Sie sicher, dass Sie die Option Voice aktiviert haben und die Antwort- und Ereignis-URLs wie unten gezeigt definiert haben, indem Sie Ihren ngrok-Link aus den obigen Schritten verwenden.

Correct configuration for a voice-enabled Vonage ApplicationBeachten Sie, dass wir HTTP GET für die Antwort-URL und HTTP POST für die Ereignis-URL verwenden.

Wenn Sie mit Ihrer Einrichtung zufrieden sind, gehen Sie weiter und Erzeugen Sie eine neue Anwendung.

Screenshot of Create Application

Verknüpfen Sie die Anwendung mit Ihrer Vonage-Nummer

Nachdem Sie Ihre Vonage-Applikation erstellt haben, werden Ihre verfügbaren virtuellen Numbers unten auf dem Bildschirm angezeigt, einschließlich der im vorherigen Schritt erworbenen Number.

Wählen Sie die Nummer aus, die Sie für dieses Lernprogramm verwenden möchten, und klicken Sie dann auf den Verknüpfen um Ihre virtuelle Nummer mit der Vonage Application zu verknüpfen.

Screenshot of the Vonage Dashboard showing available phone numbers to link to the application we createdWenn Sie nun Ihre virtuelle Nummer anrufen, sucht Vonage nach Anweisungen für den Anrufablauf unter der URL, die Sie als Antwort-URLangegeben haben, und sendet Ereignis-Webhooks an Ihre Ereignis-URL.

Als Nächstes wollen wir überprüfen, ob alles, was wir bisher getan haben, gut funktioniert.

Rufen Sie Ihre virtuelle Vonage-Nummer an

Während ngrok auf Port 8080 in einem Terminalfenster läuft, starten Sie Ihre PHP-Anwendung auf demselben Port in einem anderen:

cd public
php -S localhost:8080

Rufen Sie Ihre Vonage-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.

Implementierung der Voice-Proxy-Logik

Um die Anrufer-ID zu verschleiern, verbinden wir einen eingehenden Anruf mit der Nummer unseres Empfängers und verwenden unsere virtuelle Vonage-Nummer, um die echte Nummer des eingehenden Anrufers zu verbergen.

In Ihrer index.php Datei erstellen Sie zwei Stringkonstanten, um die FROM_NUMBER und TO_NUMBER. Der folgende Codeausschnitt bezieht diese Werte aus der Umgebung, was eine gute Vorgehensweise ist.

$dotenv = Dotenv\Dotenv::createImmutable(__DIR__ . '/../');
$dotenv->load();

define('FROM_NUMBER', $_ENV['FROM_NUMBER']);
define('TO_NUMBER', $_ENV['TO_NUMBER']);

Als nächstes erstellen Sie eine .env Datei im Stammverzeichnis Ihres Arbeitsverzeichnisses und weisen Sie die Werte für diese beiden Konstanten zu. 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 07700900004lautet, ist das korrekte Format 447700900004.

// Your Vonage virtual number

FROM_NUMBER=4474example01

// A landline or mobile number you can use for testing. This should differ from the number you will use to make the initial call.

TO_NUMBER=4478example02

Schließlich aktualisieren wir die NCCO, um eine connect Aktion, die Vonage anweist, den eingehenden Anrufer mit dem Empfänger zu verbinden. In Ihrer index.php Datei aktualisieren Sie den /webhooks/answer Endpunkt mit dem Folgenden:

// Forward a call via proxy
$app->get('/webhooks/answer', function (Request $request, Response $response) {
    $ncco = [
        [
            'action' => 'connect',
            'from' => FROM_NUMBER,
            'endpoint' => [
                [
                    'type' => 'phone',
                    'number' => TO_NUMBER,
                ]
            ]
        ]
        
    ];

    $response->getBody()->write(json_encode($ncco));
    return $response->withHeader('Content-Type', 'application/json');
});

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:

cd public
php -S localhost:8080

Rufen Sie Ihre virtuelle Vonage-Nummer an. Wenn der Anruf angenommen wird, sollte sofort Ihre zweite Nummer angerufen werden. Dieser Anruf sollte von Ihrer Vonage-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

Schlussfolgerung

In diesem Tutorial haben wir mit PHP und der Vonage Voice API einen Voice-Proxy gebaut, der Anrufe weiterleitet und dabei die Anrufer-IDs maskiert. Von hier aus können Sie diese Lösung mit Anrufaufzeichnung, dynamischem Routing oder datenbankgestützter Nummernzuordnung erweitern.