Text-to-Speech Voice-Anrufe mit PHP

Jahrelang war es schwierig, Telefonanrufe in Ihrem Code zu tätigen und zu empfangen (und erforderte in der Regel das Schreiben von Java und das Anschließen eines alten Telefons an Ihren Laptop, das als Gateway diente). Zum Glück ist das heute nicht mehr so schwierig, dank Diensten wie Vonage (Ehemals Nexmo).

Voice-Anrufe sind eine hervorragende Kommunikationsmethode, da sie viel unmittelbarer sind als E-Mail oder SMS. Wenn Sie jemandem dringend eine Nachricht zukommen lassen müssen, ist ein Telefonanruf der richtige Weg; ein klingelndes Telefon ist schwer zu ignorieren.

In diesem Beitrag werden Sie eine kleine Anwendung erstellen, mit der Sie einen ausgehenden Telefonanruf auslösen können. PHP-Klient.

Den vollständigen Code für diesen Beitrag finden Sie in unseren PHP-Bausteine Repository auf Github.

Voraussetzungen

Bevor Sie diesen Beitrag durcharbeiten, müssen Sie PHP installiert haben. Ich verwende PHP 7.4, aber der Code hier sollte auch mit PHP 5.6 und höher funktionieren. Sie benötigen außerdem Composer um den Nexmo-PHP-Client zu installieren.

Als nächstes benötigen Sie NPM zur Installation der Nexmo CLI.

Sie benötigen eine Möglichkeit, die von Ihnen entwickelte App der Öffentlichkeit zugänglich zu machen, damit Vonage mit ihr kommunizieren kann. Dies können Sie mit einem Tool wie ngrok. Wenn Sie mit dem Tool nicht vertraut sind, finden Sie hier eine fantastische ngrok-Einführung im Vonage-Blog zur Verfügung. Öffnen Sie zunächst ein Terminal und führen Sie ngrok http 8000. Notieren Sie sich Ihre ngrok URL, denn Sie müssen https://example.com mit ihr ersetzen müssen, wenn Sie Ihre Vonage-Anwendung konfigurieren.

Wenn Sie noch keine Vonage Voice Anwendung haben, müssen Sie eine Anwendung erstellen und eine Nummer kaufen und verknüpfen. Der einfachste Weg, dies zu tun, ist die Verwendung des Nexmo CLI-Werkzeug. Hier ist die Kurzversion:

• Installieren Sie das Vonage CLI-Tool, indem Sie npm install -g vonage-cli

• Authentifizieren Sie sich mit Ihrer Vonage CLI, indem Sie vonage config:set --apiKey=<api_key> --apiSecret=<api_secret>. Ersetzen von api_key und api_secret durch Ihre Anmeldedaten, die Sie in Ihrem Dashboard

• Erstellen Sie eine Anwendung und ersetzen Sie voice-answer-url und voice-event-url durch Ihre Endpunkte, indem Sie vonage apps:create "Test Application 1" --vbc --voice_answer_url=http://example.com/webhooks/answer. Notieren Sie sich die Anwendungs-ID, die zurückgegeben wird

• Finden Sie eine kaufbare Nummer durch Suchen: vonage numbers:search US

• Kaufen Sie eine der Nummern, die Sie in der Suche zurückerhalten haben, indem Sie vonage numbers:buy <number>. Notieren Sie sich die gekaufte Nummer

• Schließlich verknüpfen Sie die Nummer mit Ihrer Anwendung, indem Sie vonage apps:link <application_id> --number=<number>

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.

Erstellen Sie Ihren Arbeitsbereich

Lassen Sie uns den Arbeitsbereich einrichten, damit Sie mit der Entwicklung Ihrer Anwendung beginnen können. Dieses Tutorial verwendet das Slim-Framework um Anrufereignisse von Vonage zu empfangen und Anweisungen zurückzugeben, wie die Anrufe behandelt werden sollen. Verwenden Sie Composer, um ein Projekt mit Slim zu starten, indem Sie die folgenden Befehle ausführen:

Diese Befehle erstellen einen Ordner namens vonage-callserstellen, das Verzeichnis in das neu erstellte Verzeichnis wechseln und Slim in Ihr neues Projekt. Kopieren Sie die private.key das Sie beim Erstellen einer Anwendung gespeichert haben, in diesen Ordner. Er sollte sich auf der gleichen Ebene befinden wie composer.json.

Als Nächstes müssen Sie den lokalen PHP-Server starten, damit Sie HTTP-Aufrufe für Ihre Anwendung tätigen können. Öffnen Sie dazu ein neues Terminal und führen Sie php -t public -S localhost:8000. Ihre Anwendung lauscht nun am Port 8000 auf Ihrem lokalen Rechner und ist über das Internet erreichbar, dank des ngrok Befehl, den Sie zuvor ausgeführt haben.

Zu diesem Zeitpunkt haben Sie eine Slim-Anwendung gebootet, die das Internet abhört und ihm ausgesetzt ist. Diese Einrichtung ist alles, was zu tun ist, um Antworten an Vonage zu senden, um es anzuweisen, wie die Anrufe zu behandeln sind.

Erstellung Ihres NCCO

Vonage-Telefonanrufe werden über Nexmo Call Control Objects (oder NCCOs) gesteuert. Ein NCCO definiert eine Liste von Aktionen, die das Vonage-System bei der Bearbeitung eines Anrufs durchführen soll. Es stehen viele verschiedene Aktionen zur Verfügung, wie zum Beispiel:

• Einen Anruf mit einer anderen Nummer verbinden mit connect.

• Aufzeichnung eines Gesprächs mit record.

• Erstellen Sie eine Telefonkonferenz mit conversation.

• Generieren Sie eine Text-zu-Sprache-Nachricht mit talk.

• Und andere - siehe unsere NCCO-Referenz für eine vollständige Liste.

Zu Beginn werden Sie einen einfachen NCCO erstellen:

[
  {
    "action": "talk",
    "voiceName": "Amy",
    "text": "The amount of visible light from a lamp is measured in lumens"
  }
]

Erstellen Sie eine Datei mit dem Namen index.php mit dem folgenden Inhalt. Das folgende Codebeispiel bootet die Slim-Anwendung, definiert einen Handler und weist dann an Slim an, diesen Handler zu verwenden, wenn Sie eine GET Anfrage an /webhook/answer:

<?php

use \Psr\Http\Message\ServerRequestInterface as Request;
use \Psr\Http\Message\ResponseInterface as Response;
use Slim\Factory\AppFactory;
require __DIR__ . '/vendor/autoload.php';

$app = AppFactory::create();

$app->get('/webhook/answer', function (Request $request, Response $response) {
    $ncco = [
        [
            'action' => 'talk',
            'voiceName' => 'Amy',
            'text' => 'The amount of visible light from a lamp is measured in lumens'
        ]
    ];

    $response->getBody()->write(json_encode($ncco));

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

$app->run();

Wenn Vonage eine GET Anfrage an Ihr answer_urlsendet, fügen Sie einen Handler hinzu, der diese Anfragen abgleicht ($router->get('/webhook/answer')) und eine JSON-Antwort zurückgibt (return response()->json()).

Solange Sie JSON im richtigen Format zurückgeben, weiß Vonage, wie der Anruf zu behandeln ist. Das ist alles, was Sie tun müssen! Speichern Sie Ihre Änderungen und rufen Sie die Nummer an, die Sie gekauft haben, um Ihre Text-to-Speech-Nachricht zu hören.

Einen ausgehenden Anruf tätigen

Sie haben einen guten Anfang gemacht, aber wir wollten einen ausgehenden Anruf tätigen und nicht nur auf eingehende Anrufe reagieren. Zu Ihrem Glück haben Sie den größten Teil der Arbeit bereits erledigt. Wenn Sie einen ausgehenden Anruf tätigen, tätigt Vonage immer noch einen Anruf bei Ihrem answer_url um herauszufinden, wie der Anruf behandelt werden soll.

Um einen ausgehenden Anruf auszulösen, müssen Sie eine POST Anfrage an die Vonage-API stellen, die Folgendes enthält to, from und answer_url zusammen mit einigen Authentifizierungsinformationen enthält.

Sie könnten diesen Aufruf zwar von Hand erstellen, aber der Nexmo PHP-Klient macht es extrem einfach. Installieren wir ihn also mit Composer. Führen Sie den folgenden Befehl in demselben Verzeichnis wie Ihre composer.json aus:

Sobald Sie den Nexmo-Client installiert haben, können Sie einen neuen Endpunkt hinzufügen, den Sie aufrufen, um einen neuen ausgehenden Anruf auszulösen. Sie benötigen die Anwendungs-ID und den privaten Schlüssel, den Sie zuvor gespeichert haben, um Ihre API-Anrufe zu authentifizieren, und dann müssen wir die Vonage Voice API anrufen. Sie müssen die Datei private.key in denselben Ordner wie Ihr composer.json und ersetzen Sie APPLICATION_ID und YOUR_VONAGE_NUMBER durch Ihre Werte. (Vergessen Sie nicht, Ihre eigene ngrok URL anstelle von example.com auch!)

$app->get('/makeCall/{number}', function (Request $request, Response $response, array $args) {
    $keypair = new \Nexmo\Client\Credentials\Keypair(
        file_get_contents(__DIR__ . '/private.key'),
        'APPLICATION_ID'
    );

    $client = new \Nexmo\Client($keypair);

    $client->calls()->create([
        'to' => [[
            'type' => 'phone',
            'number' => $args['number']
        ]],
        'from' => [
            'type' => 'phone',
            'number' => 'YOUR_VONAGE_NUMBER'
        ],
        'answer_url' => ['https://afb8ad306a73.ngrok.io/webhook/answer']
    ]);

    return $response
        ->withHeader('Content-Type', 'application/json')
        ->withStatus(200);
});

Sobald Sie das getan haben, stellen Sie einen GET Anfrage an /makeCall/ um einen ausgehenden Text-to-Speech-Anruf über Nexmo auszulösen.

Dynamische NCCOs

Sie haben erreicht, was Sie sich vorgenommen haben, aber es ist ein bisschen langweilig. Jedes Mal, wenn Sie einen Anruf tätigen, senden Sie die gleiche Nachricht. Um es dynamisch zu machen, könnten Sie die aktuelle Uhrzeit vorlesen, aber hier ist eine etwas interessantere Idee. Jedes Mal, wenn Sie einen ausgehenden Anruf tätigen, stellen Sie eine Anfrage an die Chuck Norris Datenbank und lesen die Antwort auf Ihren Anruf aus.

Zu diesem Zweck verwenden Sie eine leichtgewichtige HTTP-Bibliothek namens Guzzle. Um Guzzle zu verwenden, müssen Sie es mit Composer installieren. Führen Sie den folgenden Befehl im gleichen Verzeichnis wie Ihr composer.json:

Nachdem Sie Guzzle installiert haben, müssen Sie eine Anfrage an die Chuck Norris Datenbank stellen und die Antwort verwenden, um Ihr NCCO zu füllen. Sie werden die Suche standardmäßig auf Nerd-Witze beschränken. Fügen Sie das Folgende am Anfang Ihres /answer Handler hinzu:

$client = new GuzzleHttp\Client();
$apiResponse = json_decode($client->get('http://api.icndb.com/jokes/random?limitTo=[nerdy]')->getBody());

Dies gibt einen zufälligen Witz aus der Kategorie "Nerdy" zurück. Der nächste Schritt besteht darin, die NCCO zu aktualisieren, um den Wert aus $apiResponse:

$ncco = [
    [
        'action' => 'talk',
        'voiceName' => 'Amy',
        'text' => $apiResponse->value->joke
    ]
];

Jedes Mal, wenn Vonage nun eine Anfrage an Ihr answer_url einen zufälligen Witz aus der Chuck Norris-Datenbank ab und verwendet diesen als Text-to-Speech-Antwort. Sie können das jetzt testen, indem Sie entweder einen Anruf an Ihre Vonage-Nummer tätigen oder einen ausgehenden Anruf über den makeCall Endpunkt auslösen.

Herzlichen Glückwunsch! Sie haben gerade ein Text-to-Speech-Sprachanrufsystem erstellt, das sowohl eingehende als auch ausgehende Anrufe verarbeiten kann. In Zukunft können Sie die Antwort auf der Grundlage des Anrufers, der Tageszeit oder anderer denkbarer Faktoren anpassen.

Was kommt als Nächstes?

Und wie geht es weiter? Sie könnten Ihre Anwendung erweitern zu ein sprachbasiertes Warnsystem für kritische Situationen erweitern, indem Sie eine Liste von Kontakten in einer Schleife durchlaufen, um Anrufe zu senden und die Empfänger eine Nummer drücken zu lassen, um den Empfang Ihrer Nachrichten zu bestätigen.