Aufbau einer Telefonkonferenz mit PHP und der Vonage Voice API

Einführung

In diesem Tutorial lernen Sie, wie Sie mit PHP und der Vonage Voice API eine Anwendung für Telefonkonferenzen erstellen können. Am Ende werden Sie eine Telefonnummer haben, die mehrere Teilnehmer anrufen können, um an demselben Live-Gespräch teilzunehmen.

Wir werden eine Vonage-Anwendung konfigurieren, eingehende Anrufe mit einem Call Control Object (NCCO) bearbeiten und dynamische Antworten von einem einfachen PHP-Endpunkt zurückgeben. Dieses Projekt ist ein praktischer Ausgangspunkt für den Aufbau von Team-Meeting-Linien, Event-Hotlines oder kollaborativen Voice-Erlebnissen.

Der vollständige Quellcode für dieses Tutorial ist im Vonage Community GitHub Repositoryzur Verfügung, so dass Sie das Tutorial nachvollziehen oder für Ihren eigenen Anwendungsfall anpassen können.

Voraussetzungen

• PHP8.3+

• 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.

Sind Sie bereit, mit dem Bau zu beginnen?

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

Beantwortung eines eingehenden Anrufs mit PHP

In diesem Beispiel rufen die Benutzer eine virtuelle Nummer von Vonage an, und Ihr Anwendungscode reagiert auf den eingehenden Anruf. Vonage verwendet dazu ein Call Control Object, oder NCCO.

Zunächst wird eine gesprochene Text-to-Speech-Ansage (TTS) eingespielt, dann nimmt der Benutzer an der Telefonkonferenz teil.

Um dies zu erreichen, fügen wir eine answer.php Datei in das public/ (unser Webroot-Verzeichnis) eine Datei hinzu, die den NCCO zurückgibt. Der NCCO ist JSON, daher muss PHP auch einen entsprechenden Content-Type Header enthalten:

<?php

$ncco = [
    [
        "action" => "talk",
        "text" => "Thank you for joining the call today. You will now be added to the conference.",
        "language" => "en-GB",
        "style" => 0,
        "premium" => true
    ],
    [
        "action" => "conversation",
        "name" => "weekly-team-meeting"
    ]
];

header("Content-Type: application/json");
echo json_encode($ncco);

Die Variable $ncco Variable enthält den NCCO, den Sie an den Vonage-Server zurückgeben, um ihm mitzuteilen, wie er einen eingehenden Anruf behandeln soll. Dieses Beispiel enthält eine "Talk"-Aktion, mit der der Benutzer begrüßt wird, gefolgt von einer "Conversation"-Aktion, mit der der Benutzer zur Telefonkonferenz hinzugefügt wird. Dieser Code verwendet header() um PHP dazu zu bringen, den Content-Type Header zu senden, gefolgt von dem JSON selbst.

Wenn Sie wissen möchten, was Sie sonst noch mit einem NCCO machen können, finden Sie die NCCO-Referenzdokumentation auf unserem Entwicklerportal.

Servieren Sie die Antwort

Jetzt können Sie mit dem Testen der beweglichen Teile der Anwendung beginnen. Starten Sie den PHP-Webserver aus dem public/ Verzeichnis:

cd public/
php -S localhost:8080

Überprüfen Sie, ob Ihre Anwendung den NCCO korrekt zurückgibt, wenn Sie eine Anfrage an http://localhost:8080/answer.php unter Verwendung Ihres bevorzugten HTTP-Clients (cURL, Postman oder sogar Ihr Browser wären hier ein gutes Werkzeug).

Den Code öffentlich zugänglich machen

Damit Vonage Ihre Anwendung über einen eingehenden Anruf benachrichtigen kann, muss diese in der Lage sein, den Code zu erreichen, also muss dieser Code öffentlich zugänglich sein. Eine Möglichkeit besteht darin, ihn auf einem Server bereitzustellen, aber für Entwicklungszwecke bevorzuge ich die Verwendung von ngrok um meine lokale Entwicklungsumgebung freizugeben. Sobald der Webserver läuft (meiner läuft auf Port 8080), führen Sie ngrok wie folgt aus:

ngrok http 8080

Dadurch erhalten Sie ein Dashboard mit einem Link zum Webinterface (sehr nützlich, klicken Sie darauf), die https-URL Ihres Tunnels (kopieren Sie diese, wir brauchen sie gleich) und einen Abschnitt, der die eingehenden Anfragen anzeigt, wenn Sie welche machen.

Probieren Sie Ihren neuen Tunnel aus, indem Sie Ihre Anwendung darüber aufrufen - Sie können die http://localhost:8080 durch Ihre ngrok https URL ersetzen und die Anfrage an /answer.php erneut.

Einrichten einer Nummer zum Anrufen

Kaufen Sie eine Vonage-Nummer

Erstellen einer Voice-fähigen Vonage-Applikation

Außerdem benötigen Sie eine Vonage-Applikation, in der die Anrufkonfiguration gespeichert ist und die mit der/den gewünschten Nummer(n) verknüpft werden kann. Diese Trennung ist sehr nützlich, wenn Sie wollen, dass Numbers aus verschiedenen Ländern an der gleichen Telefonkonferenz teilnehmen.

Vonage-Applikationen verwenden öffentliche/private Schlüssel. In diesem Beispiel nehmen Sie lediglich einen eingehenden Anruf entgegen, sodass Sie den privaten Schlüssel vorerst nicht benötigen. Es ist jedoch ratsam, Ihre private.key Datei in Ihrem Arbeitsverzeichnis zu speichern, für den Fall, dass Sie weitere Funktionen auf diesem Beispiel aufbauen möchten.

Beim Erstellen der Anwendung müssen Sie ihr einen Namen geben und einige wichtige Webhook-Endpunkte konfigurieren:

• Die Antwort-URL ist der answer.php Endpunkt, den Sie bereits erstellt haben.

• Setzen Sie die Ereignis-URL auf event.php. Wir werden diese Datei im nächsten Abschnitt erstellen.

Verknüpfen Sie die Anwendung mit Ihrer Vonage-Nummer

Nachdem Sie Ihre Vonage-Applikation erstellt haben, werden Ihre verfügbaren virtuellen Numbers am unteren Rand des Bildschirms angezeigt - einschließlich der Nummer, die Sie im vorherigen Schritt erworben haben.

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.

Wenn 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 gemacht haben, auch funktioniert. Rufen Sie die Nummer an und prüfen Sie, ob Sie die Begrüßung hören; wenn ja, bitten Sie eine andere Person, anzurufen und ein Gespräch zu führen.

Wenn es beim ersten Mal nicht klappt, machen Sie sich keine Sorgen. Der nächste Schritt besteht darin, die Ereignisbehandlung zu erstellen, damit Sie sehen können, was vor sich geht - und wenn es Fehler gibt, werden Sie sie so sehen.

Handle Call Events

Um die Dinge einfach zu halten, erwartet die Anwendung, dass ihre Ereignis-URL/event.php-und wenn Sie dies bereits getestet haben, haben Sie gesehen, dass einige fehlgeschlagene Anfragen dort ankommen.

Um einen einfachen Event-Handler zu erstellen, erstellen Sie eine Datei public/event.php und fügen Sie den folgenden Code hinzu:

<?php

$post_params = json_decode(file_get_contents("php://input"), true);
$input_params = $_GET;

if (is_array($post_params)) {
    $input_params = array_merge($input_params, $post_params);
}

if (isset($input_params['status'])) {
    error_log("Status: " . $input_params['status']);
}
error_log("Event data: " . json_encode($input_params));

Es ist möglich, die Ereignis-URL so zu konfigurieren, dass sie entweder GET oder POST Anfragen zu verwenden, so dass dieser Code beides verarbeiten kann! Er ist sehr einfach und schreibt die Daten in den error_logWenn Sie also den lokalen PHP-Webserver verwenden, wie ich es in diesem Beispiel getan habe, werden Sie die Ereignisse in der Ausgabe des Webserverprozesses sehen. In einer realen Anwendung können Sie Ihre Ereignis-URL mit etwas Formellerem verknüpfen.

Start der Party-Telefonkonferenz

Wenn Sie es noch nicht ausprobiert haben, rufen Sie einfach Ihre Vonage Nummer an. Laden Sie dann Ihre Freunde, Familie und Kollegen ein, dasselbe zu tun. Sie werden sehen, wie die Ereignisse während der Anrufe ankommen event.phpund die verschiedenen Anrufe, die entgegengenommen werden, mit Anfragen an answer.php.

Ihr nächster Schritt?

Es gibt ein paar Dinge, die Sie als Nächstes tun sollten:

• Sehen Sie sich die NCCO-Dokumentation wie Sie diese Anrufe aufzeichnen, Warteschleifenmusik abspielen oder dem Anruf einen bestimmten Moderator zuweisen können.

• Sehen Sie sich den Code für dieses Projekt auf GitHub.

• Sehen Sie sich unsere anderen Codeschnipsel für die Arbeit mit der Vonage Voice API.

Schlussfolgerung

In diesem Tutorial haben wir eine PHP-gestützte Telefonkonferenz mit der Vonage Voice API aufgebaut. Sie haben eine Voice-Anwendung konfiguriert, Webhooks für eingehende Anrufe verarbeitet und einen NCCO zurückgegeben, um mehrere Anrufer in dasselbe Gespräch zu schalten.

Von hier aus können Sie dieses Projekt um die Aufzeichnung von Anrufen, die Zuweisung von Moderatoren, die Wiedergabe von Warteschleifenmusik oder die dynamische Generierung von Konferenzraumnamen erweitern. Sie können diesen Workflow auch mit der Messages API kombinieren, um Erinnerungen zu senden, oder die Authentifizierung um zu kontrollieren, wer teilnehmen kann.