Erstellen eines Telefonstatusprüfers mit Nexmo und PHP

Die Arbeit in einer Webagentur bringt viele Herausforderungen mit sich, denn wir müssen mit mehreren verschiedenen Kunden jonglieren. Wir sollten uns immer auf diese Kunden konzentrieren, um sicherzustellen, dass ihre Anforderungen erfüllt werden und sie mit der Arbeit, die wir leisten, zufrieden sind. Was Sie also wahrscheinlich nicht wollen, sind Ablenkungen von außen. Genau das ist in unserem Büro fast täglich der Fall.

Das tägliche Szenario sah wie folgt aus. Ein Manager nimmt den Hörer ab, um einen Kunden anzurufen, das Telefon wählt nicht, der Manager schreit dann durch das Großraumbüro: "Die Telefone sind ausgefallen", was dann quer durch das Büro in Richtung des für das Telefonsystem verantwortlichen Technikers gespottet wird. Dieser würde seine Arbeit unterbrechen, niedergeschlagen zum Telefon gehen und nach fünf Minuten wieder an seinen Schreibtisch zurückkehren, nachdem er das Problem behoben hatte. Auch dies geschah fast täglich.

Das war aber nicht das einzige Szenario. Mein persönliches Lieblingsszenario war, dass Anrufe von Telefonen, die auf 87 enden, nicht mit unserem Telefonsystem verbunden werden konnten.

Nachdem dies etwa zum siebenundzwanzigsten Mal passiert war, wusste ich, dass es eine bessere Lösung für dieses Problem geben musste. Fünf Minuten mögen zwar nicht viel erscheinen, aber der Fluss und die Konzentration der Ingenieure waren trotzdem gestört, was dazu führte, dass man weitere zwanzig Minuten brauchte, um sich zu erinnern, wo man aufgehört hatte, und wieder in den Fluss zu kommen.

Also habe ich angefangen, etwas zu entwerfen.

Meine ursprüngliche Idee war es, ein einfaches Formular zu erstellen, in dem ein Manager oder Administrator eine benutzerdefinierte Telefonnummer eingeben kann, die dann versucht, das Telefonsystem anzurufen. Wenn die Nummer erfolgreich mit dem Telefonsystem verbunden wird, ist keine Aktion erforderlich. Wenn die Verbindung nicht zustande kommt, werden automatisch einige mögliche Lösungen vorgeschlagen, und wenn diese nicht funktionieren, wird der Techniker über das Problem benachrichtigt, der es weiter untersucht.

Phone number tree

Das ist es, was wir heute bauen werden. Ich werde Ihnen zeigen, wie Sie eine Anwendung mit PHP und der Voice API von Nexmo erstellen können. Für dieses Tutorial gehe ich davon aus, dass Sie zumindest etwas Erfahrung mit PHP haben. Also, lasst uns anfangen!

Erstellen der Anwendung

Bevor wir irgendeinen Code schreiben können, müssen wir eine Voice Application einrichten. Die Voice Application kümmert sich um Sicherheit und URL-Webhooks.

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.

Für unser Vorhaben benötigen wir einen Anwendungsnamen, eine Ereignis-URL und ein öffentliches/privates Schlüsselpaar.

Der Name der Anwendung wird nirgendwo in unserem Code referenziert, er wird nur für unsere eigene Verwaltung und Organisation innerhalb des Nexmo-Dashboards verwendet. Ich schlage vor, die Anwendung "Phone System Debugger" zu nennen.

Die Ereignis-URL wird später sehr wichtig werden. Damit wird unsere Anwendung bei jedem Schritt während eines Anrufs eine Statusabfrage senden. Im Moment kann dies nur eine Platzhalter-URL sein und wir werden später auf diese Option zurückkommen.

Der Public Key/Private Key wird verwendet, um uns einen sicheren Zugang zur Nexmo API zu verschaffen, man kann ihn sich als digitalen Reisepass vorstellen. Wir müssen den privaten Schlüssel herunterladen und ihn in unserer Anwendung speichern, damit er später von der Nexmo-API verwendet werden kann.

Wenn Sie all diese Daten eingegeben und die Anwendung gespeichert haben, erhalten wir eine Anwendungs-ID und einen API-Schlüssel. Diese Angaben benötigen wir auch bei der Erstellung unserer Webanwendung.

Der Nexmo-Kunde

Einer der Vorteile der Verwendung von PHP ist, dass Nexmo seinen eigenen Drittanbieter-Client entwickelt hat, der die Interaktion zwischen unserer Anwendung und Nexmo übernehmen kann. Dies wird unseren Arbeitsaufwand verringern und kann später verwendet werden, um unsere gesamte Nexmo-Logik in einen einzigen kleinen Dienst zu abstrahieren.

Wir werden diesen Client als eine Abhängigkeit installieren, indem wir Composer. Composer ist ein Tool zur Verwaltung von Abhängigkeiten von Drittanbietern in Ihrem Projekt.

Um den Nexmo-Client nutzen zu können, müssen wir mehrere Anmeldedaten in den Client eingeben. Diese Anmeldeinformationen sind:

• API-Schlüssel

• API-Geheimnis

• Anwendungsschlüssel

• Speicherort der privaten Schlüsseldatei

Glücklicherweise verfügen wir bereits über diese Anmeldeinformationen, da wir sie bei der Erstellung unserer Voice Application erstellt haben.

For the purpose of a quick demonstration, we are just going to implement the client into an `index.php` script, with the main purpose of just sending a test call to ourselves. We will later expand on what we learn here.
 
<?php

use Nexmo\Client;

require_once 'vendor/autoload.php';

$basic = new Nexmo\Client\Credentials\Basic(
   'API_KEY',
   'API_SECRET'
);

$keypair = new Nexmo\Client\Credentials\Keypair(
 file_get_contents('PRIVATE_KEY_PATH'),
 'APPLICATION_ID'
);

$container = new Nexmo\Client\Credentials\Container([$basic, $keypair]);

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

$client->calls()->create([
   'to' => [[
       'type' => 'phone',
       'number' => 'YOUR_PHONE_NUMBER',
   ]],
   'from' => [
       'type' => 'phone',
       'number' => '447418347739',
   ],
   'ncco' => [
       [
           'action' => 'talk',
           'text' => 'Hello world',
       ]
   ]
]);
?>

Im obigen Beispiel haben wir also unsere Credentials in zwei verschiedene Klassen unterteilt: die Basic Credential Class, die die allgemeinen Nexmo Account-Details enthält, und die Key pair Credentials, die die Details unserer Voice Application enthalten.

Ihren API-Schlüssel und Ihr Geheimnis finden Sie auf der Seite 'Erste SchritteSeite in Ihrem Nexmo Account. Die Anwendungs-ID wurde generiert, als wir unsere Voice-Anwendung und den Inhalt unseres privaten Schlüssels erstellt haben, und kann von der Seite der Anwendungsverwaltung heruntergeladen werden.

Diese beiden Berechtigungsnachweisklassen werden dann als Array an die Berechtigungsnachweis-Containerklasse übergeben und der neu instanziierte Container wird an den Client übergeben. Jetzt können wir die Voice API vollständig nutzen.

Anschließend erstellen wir eine Anrufanfrage in einem Array, in dem wir angeben, wen wir anrufen wollen, von wem der Anruf kommt und was wir dem Empfänger mit dem NCCO-Objekt sagen wollen.

Nachdem wir nun den Nexmo Client hinzugefügt und ein einfaches Beispiel erstellt haben, sollten Sie nun einen Eindruck davon bekommen, wie leistungsfähig dieses Tool sein kann.

Für unsere Zwecke werde ich mich nicht mit dem NCCO befassen, aber es ist ein wirklich leistungsfähiges Instrument. Ich würde Ihnen wirklich empfehlen, die Dokumentation zu lesen und ein wenig herumzuspielen; das wird Ihnen die Möglichkeiten, die Sie mit der Voice API erreichen können, deutlich vor Augen führen.

Wir werden nun das, was wir hier geschaffen haben, weiter ausbauen, um die Kriterien zu erfüllen, die ich zuvor dargelegt habe. Ich überspringe einige Bereiche der Einrichtung und werde die folgenden Beispiele so schreiben, als würde ich ein Framework verwenden. Ich werde es ziemlich abstrakt halten, also verwenden Sie bitte ein beliebiges Framework. Ich persönlich empfehle die Verwendung von Symfony oder Slim für das, was wir hier tun. Wir müssen lediglich Zugriff auf einen Router haben, um API-Anfragen abzuhören.

<?php

namespace App\Service;

use Nexmo\Client;

class NexmoService
{
    /** @var Client */
    private $client;

    public function __construct(Client $client)
    {
        $this->client = $client;
    }

    public function makeCall(string $message, string $fromNumber)
    {
        $this->client->calls()->create([
            'to' => [[
                'type' => 'phone',
                'number' => $_ENV['DEFAULT_RECEIVER_NUMBER'],
            ]],
            'from' => [
                'type' => 'phone',
                'number' => $fromNumber,
            ],
            'ncco' => [
                [
                    'action' => 'talk',
                    'text' => $message,
                ]
            ]
        ]);
    }
}

Ich habe hier also abstrahiert, was wir in unserem einfachen Skript getan haben, und es in eine wiederverwendbare Serviceklasse gepackt. Wir rufen diese Klasse nun in unserem Controller mit einer Nachricht und einer Telefonnummer auf, die der Benutzer in ein Formular eingibt.

Was ich noch nicht behandelt habe, ist, wie wir den aktuellen Status unseres Telefonsystems von einem Anruf über Nexmo erfahren können, und hier kommt Nexmos Event Url ins Spiel.

Der Ereignis-Webhook wird nach jedem Ereignis während eines Anrufs gesendet. In unserer Anwendung werden wir auf der Grundlage des aktuellen Status des Anrufs reagieren. Das Ereignis, auf das wir reagieren wollen, ist "fehlgeschlagen", und wir werden alle anderen Status vorerst ignorieren.

Wir werden also einen Controller erstellen, der aufgerufen wird, wenn ein Ereignis-Webhook gesendet wird, und der den Status dieses Ereignisses überprüft. Wenn der Status "fehlgeschlagen" ist, dann werden wir einfach eine Warnung an den Benutzer ausgeben.

Zunächst brauchen wir eine Möglichkeit, wie Nexmo das Ereignis tatsächlich an unsere Anwendung senden kann, während wir noch lokal entwickeln. Ich empfehle die Verwendung eines Tools namens Ngrok. Ngrok ist ein kostenloses Tool zum Öffnen einer Portnummer für die öffentlich zugängliche Webadresse.

Ngrok Example

Ich habe Ngrok so eingerichtet, dass es meinen Port 8080 weiterleitet, und meine Anwendung aktualisiert, um die Ngrok-Adresse zu verwenden.

Ngrok url

Schließlich werden wir eine Funktion erstellen, um die Daten aus unserer Anfrage zu erhalten und den Status des Ereignisses zu überprüfen.

Dieses Codebeispiel ist nicht sehr aufregend, daher werden wir jetzt die Möglichkeit hinzufügen, uns eine SMS zu senden, wenn der Ereignis-Webhook den Status "fehlgeschlagen" zurückgibt.

Dazu können wir den bestehenden Nexmo-Client nutzen, um ganz einfach eine SMS an unsere Handynummer einzurichten und zu versenden. Dieser Zusatz ist sehr einfach zu machen, also werden wir unseren Nexmo-Dienst um die SMS-Funktionalität erweitern.

<?php

namespace App\Service;

use Nexmo\Client;

class NexmoService
{
    /** @var Client */
    private $client;

    public function __construct(Client $client)
    {
        $this->client = $client;
    }

    public function makeCall(string $message, string $fromNumber)
    {
        $this->client->calls()->create([
            'to' => [[
                'type' => 'phone',
                'number' => $_ENV['DEFAULT_RECEIVER_NUMBER'],
            ]],
            'from' => [
                'type' => 'phone',
                'number' => $fromNumber,
            ],
            'ncco' => [
                [
                    'action' => 'talk',
                    'text' => $message,
                ]
            ]
        ]);
    }
    
    public function sendSMS(string $message)
    {
       $this->client->message()->send([
           'to' => $_ENV['MOBILE_NUMBER'],
           'from' => 'Phone Debugger',
           'text' => $message
       ]);
    }
}

Mit acht zusätzlichen Zeilen können wir nun ganz einfach SMS-Nachrichten an unser Mobiltelefon senden. Alles, was wir getan haben, ist ein Array mit der Nummer, die wir anrufen wollen, der Person, von der sie kommt, und der Nachricht, die wir senden wollen, zu übergeben. Beachten Sie, dass unsere Absendernummer nur eine Zeichenkette ist; dies wird von Nexmo's Nachrichtenfunktionalität unterstützt.

Es gibt eine weitere Möglichkeit, SMS-Unterstützung zu unserer Anwendung hinzuzufügen. Dies geschieht über die Messaging API, die derzeit nicht vom Nexmo-Client unterstützt wird, aber WhatsApp, Facebook Messenger und Viber unterstützt. Für unsere Anwendung ist dies nicht erforderlich; ich empfehle jedoch, die Messaging API zu untersuchen, wenn Sie nach einer Möglichkeit suchen, Ihre Anwendung zu erweitern.

/**
* Route: api/event-webhook
*/
public function postEvent(Request $request)
{
   //Get data as an array
   $data = $request->getContent();

   if (isset($data['status']) && $data['status'] === 'failed') {
       $this->nexmoService->sendSMSMessage('Phone System is down!!!');
   }
}

Schließlich habe ich noch einen Aufruf der neuen SMS-Funktion in unserer Controller-Klasse hinzugefügt, die aufgerufen wird, wenn der Event-Webhook einen fehlgeschlagenen Status zurückgibt. Und voilà! Wir haben einen einfachen Telefonstatus-Checker.

Um zu rekapitulieren, was wir erreicht haben: Wir haben eine Anwendung erstellt, die eine Telefonnummer annimmt, versucht, diese Nummer anzurufen, und, basierend auf dem Status dieses Anrufs, jemanden benachrichtigt, wenn der Anruf fehlschlägt.

Ich habe ein Github-Repositorium mit allem, was wir in diesem Artikel behandelt haben. Wenn Sie also etwas verwirrend finden oder Probleme mit Ihrer Anwendung haben, können Sie das Beispiel gerne herunterladen und damit herumspielen.

Jetzt kratzen wir nur an der Oberfläche dessen, was Sie mit diesem Tool tun können. Mögliche Erweiterungen könnten darin bestehen, eine Nummer zu validieren, bevor man versucht, das System anzurufen, was mit Nexmos Number Insight erreicht werden kann. Sie könnten eine Verbindung zwischen Anrufen und ihrem Status herstellen und sie in einer Datenbank speichern und die Anrufe in einer Tabelle anzeigen.

Wenn Sie sich inspirieren lassen möchten, wie Sie diese Anwendung ausbauen können, schauen Sie sich bitte mein Nexmo Status Projekt auf GitHubwelches die erste Iteration des Telefon-Debuggers war. Wenn Sie irgendwelche Fragen haben, können Sie gerne einen Kommentar hinterlassen.