Sprachbenachrichtigungen

Ein ständig klingelndes Telefon ist schwerer zu überhören als eine Textnachricht oder ein Push-Benachrichtigung, wenn Sie also sicherstellen müssen, dass kritische Warnungen um die richtige Person zu erreichen, ist ein Telefonanruf eine der besten Möglichkeiten.

In diesem Leitfaden erfahren Sie, wie Sie eine Liste von Personen telefonisch kontaktieren, eine Nachricht übermitteln und sehen, wer den Erhalt der Nachricht bestätigt hat. Diese sprachbasierten kritischen Benachrichtigungen sind nachhaltiger als eine Textnachricht, so dass Ihre Nachricht mit größerer Wahrscheinlichkeit wahrgenommen wird. Durch die Bestätigung des Empfängers können Sie außerdem sicher sein, dass Ihre Nachricht angekommen ist.

Voraussetzungen

Um diesen Leitfaden durcharbeiten zu können, benötigen Sie:

Erste Schritte

Wir beginnen mit der Registrierung einer Vonage Number, die Sie mit dieser Anwendung verwenden können. Folgen Sie den Anweisungen für Erste Schritte mit Applications. Hier erfahren Sie, wie Sie eine Nummer kaufen, eine Anwendung erstellen und beide miteinander verknüpfen.

Sie müssen die URL Ihres öffentlich zugänglichen Webservers oder ngrok-Endpunkts angeben, wenn Sie Ihre Anwendung konfigurieren, sowohl als Teil der answer_url und die event_url. Diese Dateien heißen answer.php und event.php jeweils in diesem Projekt. Wenn Ihre ngrok-URL zum Beispiel lautet https://25b8c071.ngrok.io dann wäre Ihre Konfiguration wie folgt:

  • antwort_url https://25b8c071.ngrok.io/answer.php
  • ereignis_url https://25b8c071.ngrok.io/event.php

Wenn Sie eine Anwendung erstellen, erhalten Sie einen Schlüssel, den Sie für die Authentifizierung verwenden können. Speichern Sie diesen in einer Datei namens private.key und bewahren Sie ihn sicher auf! Sie werden ihn später für ausgehende Anrufe benötigen.

Sobald die Anwendung erstellt, konfiguriert und mit einer Telefonnummer verknüpft ist, sehen Sie sich den Code an und probieren Sie ihn dann aus.

Bringen Sie Ihrer Applikation das "Sprechen" bei

Wenn ein Mensch per Telefon mit Ihrer Anwendung verbunden ist, steuern Sie mit Vonage Call Control Objects (NCCOs), was der Mensch hört. Diese können sowohl für eingehende als auch für ausgehende Anrufe verwendet werden - sobald der Anruf läuft, macht es keinen großen Unterschied mehr, welcher Anruf es war.

Wenn ein Anruf an die Nummer getätigt wird, die wir zuvor mit ihr verknüpft haben. Vonage stellt eine Anfrage an die answer_url die Sie in der Anwendung konfiguriert haben, und erwartet, dass die Antwort ein Array von NCCOs ist.

Werfen Sie einen Blick auf answer.php im Repository. Dies ist der Code, der die NCCOs zurückgibt: in diesem Fall einige Text-to-Speech-Meldungen und auch eine Aufforderung zur Benutzereingabe.

$ncco = [
    [
        "action" => "talk",
        "voiceName" => "Jennifer",
        "text" => "Hello, here is your message. I hope you have a nice day."
    ],
    [
        "action" => "talk",
        "voiceName" => "Jennifer",
        "text" => "To confirm receipt of this message, please press 1 followed by the pound sign"
    ],
    [
        "action" => "input",
        "type": ["dtmf"],
        "dtmf": {
            "submitOnHash" => "true",
            "timeout" => 10
        }
    ],
    [
        "action" => "talk",
        "voiceName" => "Jennifer",
        "text" => "Thank you, you may now hang up."
    ]
];

// Vonage expect you to return JSON with the correct headers
header('Content-Type: application/json');
echo json_encode($ncco);

Dies zeigt einige verschiedene Arten von NCCOs in Aktion und gibt Ihnen hoffentlich eine Vorstellung davon, was Sie mit einem NCCO alles machen können (eine detaillierte NCCO-Referenz ist verfügbar, wenn Sie neugierig sind!). Dies sind alles JSON-Objekte, und Ihr Code erstellt die Ausgabe und sendet sie dann als Antwort mit den richtigen JSON-Headern.

Dies ist ein guter Zeitpunkt, um Ihre Vonage-Nummer von einem anderen Telefon aus anzuwählen und die oben genannten Funktionen zu testen! Ändern Sie ruhig noch etwas und schauen Sie, was Sie sonst noch tun können.

Ereignisse während eines Anrufs verfolgen

Wenn Sie Ihre Anwendung unbeaufsichtigt telefonieren lassen, ist es hilfreich, Informationen über den Status des Telefongesprächs zu erhalten. Um dies zu ermöglichen, sendet Vonage Webhooks an die event_url die Sie beim Einrichten der Anwendung konfiguriert haben. Diese Webhooks enthalten Statusaktualisierungen, um Sie darüber zu informieren, dass das Telefon klingelt, abgenommen wurde usw.

Der Code hierfür befindet sich in event.php in unserem Projekt: Es prüft auf bestimmte Zustände und schreibt Informationen darüber in eine Protokolldatei.

<?php

// Vonage sends a JSON payload to your event endpoint, so read and decode it
$request = json_decode(file_get_contents('php://input'), true);

// Work with the call status
if (isset($request['status'])) {
    switch ($request['status']) {
    case 'ringing':
        record_steps("UUID: {$request['conversation_uuid']} - ringing.");
        break;
    case 'answered':
        record_steps("UUID: {$request['conversation_uuid']} - was answered.");
        break;
    case 'complete':
        record_steps("UUID: {$request['conversation_uuid']} - complete.");
        break;
    default:
        break;
    }
}

function record_steps($message) {
    file_put_contents('./call_log.txt', $message.PHP_EOL, FILE_APPEND | LOCK_EX);
}

Die record_steps() Funktion ist ein sehr einfaches Protokollierungsbeispiel, das in eine Textdatei schreibt. Sie können dies durch Ihr bevorzugtes Protokoll ersetzen.

Sie können sich ansehen, was passiert ist, als Sie Ihre Anwendung früher aufgerufen haben, indem Sie den Inhalt von call_log.txt. Diese Datei enthält eine Aufzeichnung jedes Status, den ein bestimmter Telefonanruf oder ein "Gespräch" durchlaufen hat. Jede Zeile enthält die Kennung des Gesprächs; dies wird sehr wichtig, wenn wir viele ausgehende Anrufe auf einmal tätigen, um unsere Nachricht weiterzugeben. Wir werden immer noch wissen wollen, welches Ereignis zu welchem Gespräch gehört!

Sie können verschiedene Dinge ausprobieren, wenn Sie Ihre Nummer anrufen, und dabei die Protokolldatei beobachten. Wie wäre es damit?

  • Geben Sie eine Zahl ein, die nicht 1 bei Aufforderung
  • Nehmen Sie den Anruf nicht entgegen, sondern lassen Sie ihn auf die Mailbox sprechen

Ihre Anwendung ist bereit, die Anrufe zu verarbeiten, sobald wir sie getätigt haben, so dass es an der Zeit ist, den Übertragungsteil des Projekts zu erstellen.

Ausgehende Anrufe tätigen

Wir müssen unsere Botschaft verbreiten an mehrere Personen zu senden, um zu vermeiden, dass eine wichtige Nachricht nur an eine Person geht und übersehen wird. Das Skript durchläuft daher in einer Schleife alle Kontakte, die Sie in config.php und bittet darum, dass jeder von ihnen einen Anruf erhält.

Um zu telefonieren, müssen Sie Ihre PHP-Anwendung mit Informationen über Ihre Vonage-Zugangsdaten, die Anwendung selbst und die Personen, die Sie anrufen möchten, konfigurieren.

Kopieren config.php.example zu config.php und bearbeiten, um Ihre eigenen Werte für hinzuzufügen:

  • API-Schlüssel und Geheimnis, die Sie unter Ihr Armaturenbrett
  • Die ID der Anwendung, die Sie zu Beginn dieses Handbuchs erstellt haben
  • Die Vonage-Nummer, von der Ihre Benutzer angerufen werden sollen
  • Die öffentliche URL Ihrer Anwendung
  • Ein Array mit Namen und Numbers der Personen, die die Rundmail erhalten sollen

Vergewissern Sie sich auch, dass Sie den Schlüssel, den Sie bei der Erstellung der Anwendung erzeugt haben, in private.key auf der obersten Ebene des Projekts.

Außerdem müssen Sie Folgendes ausführen composer install um die Projektabhängigkeiten einzubringen. Dies umfasst die Vonage PHP-Server-SDK die einige Hilfsprogramme bietet, um die Arbeit mit den Vonage-APIs zu erleichtern.

Zurück im Repo, der Code, den wir für diesen Schritt benötigen, befindet sich in broadcast.php:

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

$basic  = new \Nexmo\Client\Credentials\Basic($config['api_key'], $config['api_secret']);
$keypair = new \Nexmo\Client\Credentials\Keypair(
    file_get_contents(__DIR__ . '/private.key'),
    $config['application_id']
);

$client = new \Nexmo\Client(new \Nexmo\Client\Credentials\Container($basic, $keypair));

$contacts = $config['contacts'];

foreach ($contacts as $name => $number) {
    $client->calls()->create([
        'to' => [[
            'type' => 'phone',
            'number' => $number
        ]],
        'from' => [
            'type' => 'phone',
            'number' => $config['from_number']
        ],
        'answer_url' => [$config['base_url'] . '/answer.php'],
        'event_url' => [$config['base_url'] . '/event.php'],
        'machine_detection' => 'continue'
    ]);

    // Sleep for half a second
    usleep(500000);
}

Der Code in broadcast.php verwendet Ihren konfigurierten API-Schlüssel und Ihr Geheimnis, die Anwendungs-ID und die private.key Datei, die Sie zuvor gespeichert haben, um eine Nexmo\Client Objekt. Damit steht eine Schnittstelle zur Verfügung, über die ein Anruf getätigt und das Kaufoptionen erforderlich.

Sie werden wahrscheinlich feststellen, dass es eine Anweisung für eine kurze Pause mit der usleep() Methode. Damit soll vermieden werden, dass die API-Grenzwert.

Testen Sie Ihre Anwendung jetzt, indem Sie php broadcast.php und alle von Ihnen angegebenen Telefonnummern auf einmal klingeln zu sehen. Sie können die gesprochene Nachricht ändern, indem Sie die NCCOs ändern, die an den Benutzer zurückgegeben werden. Sie können auch verschiedene Stimmen und Sprachen festlegen (siehe die vollständige Liste der Optionen im Abschnitt NCCO Referenzabschnitt.

Sie können GET-Parameter zu der answer_url wenn Sie zusätzliche Parameter haben, die Sie an diesen Kontext weitergeben wollen. Sie könnten zum Beispiel den Namen der Person hinzufügen und dann darauf zugreifen, wenn die Anfrage in answer.php.

Es gibt noch einige andere Möglichkeiten, die Sie mit Ihrer Anwendung nutzen können, wie z. B. die Verwendung einer Aufzeichnung anstelle der Text-to-Speech-Funktion oder die Aufzeichnung von Antworten der Benutzer. Die nächsten Abschnitte zeigen, wie Sie diese Aktivitäten angehen können.

Verwenden einer Aufnahme anstelle von Text-to-Speech

Um eine aufgezeichnete Nachricht anstelle (oder zusätzlich!) der Text-to-Speech-Funktion von Vonage zu nutzen, verwenden Sie einen NCCO mit der Aktion stream. stream ermöglicht es Ihnen, eine Audiodatei für den Anrufer abzuspielen. Die "streamUrl" verweist auf Ihre Audiodatei.

[
    "action" => "stream",
    "streamUrl" => ["https://example.com/audioFile.mp3"]
],

Wenn Sie die Aufzeichnung testen und sie zu laut oder zu leise ist, können Sie die Lautstärke der Aufzeichnung während des Anrufs durch Einstellen des "Pegels" anpassen. Der Standardwert ist "0", und Sie können die Lautstärke in Schritten von 0,1 auf -1 oder 1 erhöhen.

[
    "action" => "stream",
    "level" => "-0.4",
    "streamUrl" => ["https://example.com/audioFile.mp3"]
],

Weitere Informationen finden Sie auf der NCCO-Referenzdokumente für Stream.

Umgang mit Anrufbeantwortern und Voicemail

Wenn Sie nachverfolgen möchten, welche Numbers auf die Mailbox gegangen sind, anstatt beantwortet zu werden, können Sie die machine_detection Parameter beim ausgehenden Anruf, wie Sie in broadcast.php. Es gibt zwei Optionen, die Sie dafür einstellen können, continue oder hangup. Wenn Sie protokollieren möchten, dass der Anruf auf der Mailbox eingegangen ist, wählen Sie continueund eine HTTP-Anfrage wird an Ihren Ereignis-Webhook gesendet (die URL, die in event_url).

'answer_url' => ['https://example.com/answer.php'],
'event_url' =>  ['https://example.com/event.php'],
'machine_detection' => 'continue'

Unter event.php sucht das Skript nach dem Status "Maschine" und protokolliert das Ereignis entsprechend.

Bestätigung des Empfangs der Nachricht

Sie werden bemerkt haben, dass Sie als Benutzer nach der Zustellung der Nachricht aufgefordert werden, einige Tasten zu drücken, um zu bestätigen, dass Sie die Nachricht erhalten haben. Dies wird erreicht durch eine talk Aktion, die dem Benutzer Anweisungen gibt, gefolgt von einer input Aktion, um die Tastendrücke zu erfassen.

[
    "action" => "input",
    "type": ["dtmf"],
    "dtmf": {
        "submitOnHash" => "true",
        "timeout" => 10
    }
],

Durch die Einstellung submitOnHash auf true setzen, wird der Aufruf zum nächsten NCCO weitergehen, wenn das Rauten- oder Pfundzeichen (#) eingegeben wird. Andernfalls wartet der Aufruf auf den angegebenen timeout Anzahl der Sekunden (Standardwert ist 3), bevor automatisch weitergeschaltet wird.

In Ihrem Ereignisskript sehen Sie einen Code, der die Eingabeaktion behandelt. Die Daten aus der Eingabeaktion kommen unter dem dtmf Taste, mit der gedrückten Zahl als Wert.

if (isset($request['dtmf'])) {
  switch ($request['dtmf']) {
      case '1':
          record_steps("UUID: {$request['conversation_uuid']} - confirmed receipt.");
          break;
      default:
          record_steps("UUID: {$request['conversation_uuid']} - other button pressed ({$request['dtmf']}).");
          break;
  }
}

In diesem Beispiel wird protokolliert, was passiert ist, aber in Ihren eigenen Applications können Sie die Benutzereingaben speichern oder auf sie reagieren, um sie Ihren eigenen Bedürfnissen anzupassen.

Ihre Bewerbung für den Rundruf

Sie haben jetzt ein funktionierendes Sprachalarmierungssystem, mit dem Sie eine Text-to-Speech- oder aufgezeichnete Nachricht senden, protokollieren können, welche Anrufe angenommen bzw. an die Mailbox weitergeleitet werden, und eine Empfangsbestätigung von den Benutzern erhalten, die die Nachricht erhalten haben.

Nächste Schritte und weitere Lektüre