Création d'un vérificateur d'état de téléphone avec Nexmo et PHP

Travailler dans une agence web présente de nombreux défis, car nous devons jongler avec de nombreux clients différents. Nous devons toujours nous concentrer sur ces clients, afin de nous assurer que leurs besoins sont satisfaits et qu'ils sont satisfaits du travail que nous faisons. C'est pourquoi nous ne voulons pas de distractions extérieures. C'est ce qui s'est produit presque quotidiennement dans notre bureau.

Le scénario quotidien était le suivant. Un cadre décroche le téléphone pour appeler un client, le téléphone ne compose pas, le cadre crie alors à travers le bureau ouvert "Les téléphones sont en panne", ce qui est ensuite raillé à travers le bureau vers l'ingénieur en charge du système téléphonique. Ce dernier arrêtait ce qu'il faisait, se dirigeait vers le téléphone en signe de défaite et retournait à son bureau cinq minutes plus tard après avoir résolu le problème. Là encore, cela se produisait presque tous les jours.

Ce n'était pas le seul scénario. Mon scénario préféré était qu'à une époque, les appels provenant de téléphones se terminant par 87 ne parvenaient pas à se connecter à notre système téléphonique.

Après environ la vingt-septième fois que cela s'est produit, j'ai su qu'il devait y avoir une meilleure solution à ce problème. Même si cinq minutes peuvent sembler peu, le flux et la concentration des ingénieurs étaient toujours perturbés, ce qui entraînait vingt minutes supplémentaires pour reprendre là où vous vous étiez arrêté, vous souvenir de ce que vous étiez en train de faire et vous remettre dans le flux.

J'ai donc commencé à dessiner.

Mon idée initiale était de créer un simple formulaire dans lequel un responsable ou un administrateur pourrait définir un numéro de téléphone personnalisé, et ce numéro essaierait alors d'appeler le système téléphonique. Si le numéro se connecte avec succès au système téléphonique, aucune action n'est requise. Si nous ne parvenons pas à nous connecter, certaines solutions possibles sont automatisées et, si elles ne fonctionnent pas, la solution de repli consiste à notifier le problème à l'ingénieur pour qu'il procède à une enquête plus approfondie.

Phone number tree

C'est ce que nous allons construire aujourd'hui. Je vais vous montrer comment créer une application en utilisant PHP et l'API Voice de Nexmo. Pour ce tutoriel, je vais supposer que vous avez au moins une certaine expérience de PHP. Alors, commençons !

Création de l'application

Avant d'écrire le moindre code, nous devons mettre en place une Voice Application. L'Application Voice gère la sécurité et les URL webhooks.

Vonage API Account

To complete this tutorial, you will need a Vonage API account. If you don’t have one already, you can sign up today and start building with free credit. Once you have an account, you can find your API Key and API Secret at the top of the Vonage API Dashboard.

Ready to start building?

Experience seamless connectivity, real-time messaging, and crystal-clear voice and video calls—all at your fingertips.

Pour ce que nous faisons, nous aurons besoin d'un nom d'application, d'une URL d'événement et de générer une paire de clés publique/privée.

Le nom de l'application ne sera référencé nulle part dans notre code, il est purement utilisé pour notre propre gestion et organisation dans le tableau de bord Nexmo. Je suggère d'appeler l'application "Débogueur du système téléphonique".

L'URL de l'événement deviendra très importante par la suite. Elle enverra à notre application une demande d'état à chaque étape d'un appel. Pour l'instant, il peut s'agir d'une URL de remplacement. Nous reviendrons sur cette option plus tard.

La clé publique/clé privée sera utilisée pour nous donner un accès sécurisé à l'API Nexmo, comme un passeport numérique. Nous devrons télécharger la clé privée et la stocker dans notre application pour qu'elle puisse être utilisée ultérieurement par l'API Nexmo.

Une fois que vous avez saisi tous ces détails et sauvegardé l'application, nous recevrons alors un identifiant d'application et une clé API. Nous aurons également besoin de ces détails lors de la construction de notre application web.

Le client Nexmo

L'un des avantages de l'utilisation de PHP est que Nexmo a construit son propre client tiers, qui peut gérer l'interaction entre notre application et Nexmo. Cela réduira notre charge de travail et pourra être utilisé plus tard pour abstraire toute notre logique Nexmo en un seul petit service.

Nous allons installer ce client en tant que dépendance à l'aide de Composer. Composer est un outil permettant de gérer les dépendances tierces dans votre projet.

Pour utiliser le client Nexmo, nous devons injecter plusieurs informations d'identification dans le client. Ces informations sont les suivantes

• Clé API

• Secret de l'API

• Clé d'application

• Emplacement du fichier de la clé privée

Heureusement, nous disposons déjà de ces informations d'identification, car nous les avons générées lors de la création de notre Voice Application.

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',
       ]
   ]
]);
?>

Dans l'exemple ci-dessus, nous avons transféré nos informations d'identification dans deux classes distinctes : la classe d'informations d'identification de base, qui contient les informations générales relatives à votre compte Nexmo, et la classe d'informations d'identification de la paire de clés, qui contient les informations relatives à notre application vocale.

Votre clé API et votre code secret se trouvent sur la page d'accueil du site.Démarrage' sur votre Account Nexmo. L'identifiant de l'application a été généré lors de la création de notre application vocale et le contenu de notre clé privée, et peut être téléchargé à partir de la page de gestion de l'application.

Ces deux classes de justificatifs sont ensuite transmises à la classe de conteneur de justificatifs sous la forme d'un tableau et le conteneur nouvellement instancié est transmis au client. Nous pouvons maintenant utiliser pleinement l'API Voice.

Nous avons ensuite créé une demande d'appel dans un tableau en indiquant qui nous voulons appeler, de qui vient l'appel et ce que nous allons dire au destinataire à l'aide de l'objet NCCO.

Maintenant que nous avons ajouté le client Nexmo et créé un exemple simple, vous devriez avoir un aperçu de la puissance de cet outil.

Pour ce que nous faisons, je ne vais pas explorer le NCCO, mais c'est un outil très puissant. Je vous conseille vivement de lire la documentation et de vous amuser ; vous découvrirez ainsi toutes les possibilités offertes par l'API Voice.

Nous allons maintenant développer ce que nous avons créé ici pour répondre aux critères que j'ai énoncés précédemment. En sautant quelques zones de configuration, je vais écrire les exemples suivants comme si j'utilisais un framework, je vais garder cela assez abstrait donc vous pouvez utiliser n'importe quel framework que vous aimez. Je recommande personnellement l'utilisation de Symfony ou Slim pour ce que nous faisons ici. Nous avons juste besoin d'avoir accès à un routeur pour écouter les requêtes de l'API.

<?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,
                ]
            ]
        ]);
    }
}

Ce que j'ai fait ici, c'est abstraire ce que nous avons fait dans notre simple script et l'emballer dans une classe de service réutilisable. Nous allons maintenant appeler cette classe dans notre contrôleur avec un message et un numéro de téléphone, que l'utilisateur saisira dans un formulaire.

Ce que je n'ai pas encore abordé, c'est la façon dont nous allons connaître l'état actuel de notre système téléphonique à partir d'un appel via Nexmo, et c'est là que l'Url d'événement de Nexmo entre en jeu.

Le webhook webhook d'événement est envoyé après chaque événement au cours d'un appel. Ce que nous allons faire dans notre application, c'est réagir en fonction de l'état actuel de l'appel. L'événement auquel nous voulons réagir est "failed" et nous allons ignorer tous les autres statuts pour le moment.

Nous allons donc créer un contrôleur qui sera appelé lorsqu'un webhook d'événement est envoyé et qui vérifiera le statut de cet événement. Si le statut est "échoué", nous enverrons une alerte à l'utilisateur.

Tout d'abord, nous avons besoin d'un moyen pour Nexmo d'envoyer l'événement à notre application alors que nous sommes toujours en train de développer localement. Je recommande d'utiliser un outil appelé Ngrok. Numbers est un outil gratuit permettant d'ouvrir un numéro de port à l'adresse web accessible au public.

Ngrok Example

J'ai configuré Ngrok pour qu'il transmette mon port 8080 et j'ai mis à jour mon application pour qu'elle utilise l'adresse de Ngrok.

Ngrok url

Enfin, nous allons créer une fonction qui récupère les données de notre requête et vérifie l'état de l'événement.

Cet exemple de code n'étant pas très excitant, nous allons maintenant ajouter la possibilité de nous envoyer un SMS lorsque le webhook de l'événement renvoie le statut "échoué".

Pour ce faire, nous pouvons utiliser le client Nexmo existant pour configurer et envoyer facilement un SMS à notre numéro de téléphone portable. Cet ajout est très facile à réaliser, nous allons donc étendre notre service Nexmo pour y inclure la fonctionnalité SMS.

<?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
       ]);
    }
}

Avec huit lignes supplémentaires, nous avons maintenant facilement ajouté la fonctionnalité d'envoi de messages SMS à notre téléphone portable. Tout ce que nous avons fait, c'est passer un tableau contenant le numéro que nous voulons appeler, la personne d'où il provient et le message que nous voulons envoyer. Remarquez que le numéro de la personne qui appelle est une chaîne de caractères, ce qui est pris en charge par la fonctionnalité de messagerie de Numbers.

Il existe une autre façon d'ajouter la prise en charge des SMS à notre application. Pour l'instant, cette API n'est pas prise en charge par le client Nexmo, mais elle permet d'ajouter WhatsApp, Facebook Messenger et Viber. Cela n'est pas nécessaire pour notre application ; cependant, je recommande d'étudier l'API de messagerie si vous cherchez un moyen d'étendre votre application.

/**
* 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!!!');
   }
}

Enfin, je viens d'ajouter un appel à la nouvelle fonction SMS dans notre classe de contrôleur qui sera appelée lorsque le Webhook d'événement renvoie un statut d'échec. Et voilà ! Nous avons un simple vérificateur d'état de téléphone.

Récapitulons ce que nous avons accompli : Nous avons créé une application qui prend un numéro de téléphone, tente d'appeler ce numéro et, en fonction de l'état de cet appel, alerte quelqu'un si l'appel échoue.

J'ai créé un Github repo avec tout ce que nous avons couvert dans cet article. Donc, si vous avez trouvé quelque chose de confus ou si vous avez des problèmes avec votre application, n'hésitez pas à télécharger et à jouer avec cet exemple.

Nous ne faisons qu'effleurer la surface de ce que vous pouvez faire avec cet outil. Les améliorations possibles pourraient consister à valider un numéro avant de tenter d'appeler le système, ce qui peut être réalisé avec Number Insight de Nexmo. Vous pourriez ajouter un lien entre les appels téléphoniques et leur statut, les stocker dans une base de données et afficher les appels dans un tableau.

Si vous souhaitez vous inspirer de la manière dont vous pouvez développer cette application, n'hésitez pas à consulter mon projet Nexmo Status sur GitHubqui était la première itération du débogueur de téléphone. Si vous avez des questions, n'hésitez pas à laisser un commentaire.