Appels vocaux par synthèse vocale avec PHP

Pendant des années, passer et recevoir des appels téléphoniques dans votre code était difficile à réaliser (et impliquait généralement d'écrire du Java et de brancher un vieux téléphone sur votre ordinateur portable pour servir de passerelle !) Heureusement, ce n'est plus aussi difficile aujourd'hui grâce à des services tels que Vonage (anciennement Nexmo).

Les appels vocaux sont une excellente méthode de communication, car ils sont beaucoup plus immédiats que les courriels ou les SMS. Si vous devez transmettre un message à quelqu'un de manière urgente, l'appel téléphonique est le meilleur moyen de le faire ; il est difficile d'ignorer la sonnerie d'un téléphone.

Dans ce billet, vous allez créer une petite application que vous pourrez utiliser pour déclencher un appel téléphonique sortant à l'aide de notre client PHP.

Le code complet de ce billet est disponible dans notre section blocs de construction PHP sur Github.

Conditions préalables

Vous devez installer PHP avant de lire ce billet. J'utilise PHP 7.4, mais le code ici devrait fonctionner avec PHP 5.6 et plus. Vous aurez également besoin de Composer pour installer le client PHP Nexmo.

Ensuite, vous aurez besoin de NPM pour installer le fichier Nexmo CLI.

Vous aurez besoin d'un moyen d'exposer l'application que vous développez au public afin que Vonage puisse communiquer avec elle. Vous pouvez le faire en utilisant un outil tel que ngrok. Si vous n'êtes pas familier avec cet outil, il existe une fantastique introduction à ngrok disponible sur le blog de Vonage. Pour l'instant, ouvrez un terminal et exécutez ngrok http 8000. Notez votre ngrok car vous devrez remplacer https://example.com par celle-ci lors de la configuration de votre application Vonage.

Enfin, si vous n'avez pas déjà un service de Voice vous devrez créer une application et acheter et lier un numéro. La façon la plus simple de le faire est d'utiliser l'outil outil CLI de Nexmo. Voici la version courte :

• Installez l'outil CLI de Vonage en exécutant npm install -g vonage-cli

• Authentifiez-vous avec votre CLI Vonage en exécutant vonage config:set --apiKey=<api_key> --apiSecret=<api_secret>. En remplaçant api_key et api_secret par vos informations d'identification trouvées sur votre tableau de bord

• Créer une application, en remplaçant voice-answer-url et voice-event-url par vos points d'extrémité en exécutant vonage apps:create "Test Application 1" --vbc --voice_answer_url=http://example.com/webhooks/answer. Notez l'identifiant de l'application qu'elle renvoie

• Trouvez un numéro achetable en effectuant une recherche : vonage numbers:search US

• Achetez l'un des Numbers donnés lors de la recherche en exécutant vonage numbers:buy <number>. Notez le numéro acheté.

• Enfin, reliez le numéro à votre application en exécutant vonage apps:link <application_id> --number=<number>

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.

This tutorial also uses a virtual phone number. To purchase one, go to Numbers > Buy Numbers and search for one that meets your needs.

Ready to start building?

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

Créez votre espace de travail

Configurons l'espace de travail pour que vous puissiez commencer à développer votre application. Ce tutoriel utilise le framework Slim pour recevoir les événements d'appel de Vonage et renvoyer des instructions sur la façon dont les appels doivent être traités. Utilisez composer pour démarrer un projet avec Slim en exécutant les commandes ci-dessous :

Ces commandes créeront un dossier appelé vonage-callschanger de répertoire dans le répertoire nouvellement créé et installer Slim dans votre nouveau projet. Copiez le fichier private.key que vous avez sauvegardé lors de la création d'une application dans ce dossier. Il doit être au même niveau que composer.json.

Ensuite, vous devez démarrer le serveur PHP local afin de pouvoir effectuer des appels HTTP vers votre application. Pour ce faire, ouvrez un nouveau terminal et exécutez php -t public -S localhost:8000. Votre application écoute maintenant le port 8000 sur votre machine locale et est disponible via l'internet grâce à la commande ngrok que vous avez lancée plus tôt.

A ce stade, vous avez une application Slim démarrée, à l'écoute et exposée à l'internet. Cette configuration est tout ce qu'il y a à faire pour commencer à servir des réponses à Vonage pour lui indiquer comment traiter les appels téléphoniques.

Création de votre BCN

Les appels téléphoniques de Vonage sont contrôlés à l'aide d'objets de contrôle d'appel Nexmo (ou NCCO). Un NCCO définit une liste d'actions que le système Vonage doit suivre lorsqu'un appel est traité. Il existe un grand nombre d'actions différentes, telles que :

• Connecter un appel à un autre numéro avec connect.

• Enregistrer un appel avec record.

• Créer une conférence téléphonique avec conversation.

• Générer un message texte-parole avec talk.

• Plus d'autres - voir notre référence NCCO pour une liste complète.

Pour commencer, vous allez générer un simple NCCO :

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

Créez un fichier nommé index.php avec le contenu suivant. L'exemple de code ci-dessous démarre l'application Slim, définit un gestionnaire, puis demande à Slim d'utiliser ce gestionnaire chaque fois que vous recevez une GET demande à /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();

Lorsque Vonage fait une GET demande à votre answer_urlvous ajoutez un gestionnaire qui correspond à ces demandes ($router->get('/webhook/answer')) et renvoie une réponse JSON (return response()->json()).

Tant que vous renvoyez JSON dans le bon format, Vonage sait comment traiter l'appel. C'est tout ce qu'il y a à faire ! Enregistrez vos modifications, puis appelez le numéro que vous avez acheté pour entendre votre message de synthèse vocale.

Passer un appel sortant

Vous avez bien commencé, mais nous voulions passer un appel sortant, et pas seulement répondre aux appels entrants. Heureusement pour vous, vous avez déjà fait le gros du travail. Lorsque vous faites un appel sortant, Vonage appelle quand même votre centre d'appels pour savoir comment traiter l'appel. answer_url pour savoir comment traiter l'appel.

Pour déclencher un appel sortant, vous devez faire une POST à l'API de Vonage qui contient to, from et answer_url ainsi que des informations d'authentification.

Bien que vous puissiez créer cet appel à la main, le client PHP de client PHP Nexmo le rend extrêmement facile. Installons-le donc avec Composer. Exécutez la commande suivante dans le même répertoire que votre composer.json :

Une fois le client Nexmo installé, vous pouvez ajouter un nouveau point de terminaison que vous appellerez pour déclencher un nouvel appel sortant. Vous aurez besoin de l'ID de l'application et de la clé privée que vous avez enregistrée précédemment pour authentifier vos appels API, puis nous devons passer un appel à l'API Voice de Vonage. Vous devez copier private.key dans le même dossier que votre composer.json et remplacer APPLICATION_ID et YOUR_VONAGE_NUMBER par vos valeurs. (N'oubliez pas de fournir votre propre ngrok au lieu de example.com également !)

$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);
});

Une fois que vous avez fait cela, faites une GET demande à /makeCall/ pour déclencher un appel texte-parole sortant via Nexmo.

OCNC dynamiques

Vous avez accompli ce que vous aviez prévu de faire, mais c'est un peu ennuyeux. Vous diffusez le même message à chaque appel. Pour le rendre dynamique, vous pourriez lire l'heure actuelle, mais voici une idée un peu plus intéressante. Chaque fois que vous passez un appel sortant, vous adressez une requête à la Base de données Chuck Norris et lisez la réponse à votre appel.

Pour ce faire, vous utiliserez une bibliothèque HTTP légère appelée Guzzle. Pour utiliser Guzzle, vous devez l'installer à l'aide de Composer. Exécutez la commande suivante dans le même répertoire que votre composer.json:

Une fois Guzzle installé, vous devez envoyer une requête à la base de données Chuck Norris et utiliser la réponse pour alimenter votre BCN. Par défaut, vous allez limiter la recherche aux blagues d'intellos. Ajoutez ce qui suit au début de votre /answer handler :

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

Cela renverra une blague aléatoire de la catégorie "nerdy". L'étape suivante consiste à mettre à jour le NCCO pour utiliser la valeur de $apiResponse:

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

Désormais, chaque fois que Vonage adressera une requête à votre answer_url vous récupérerez une blague aléatoire dans la base de données de Chuck Norris et l'utiliserez comme réponse en synthèse vocale. Vous pouvez tester cela maintenant en passant un appel téléphonique à votre numéro Vonage ou en déclenchant un appel sortant via le point de terminaison makeCall point de terminaison.

Félicitations ! Vous venez de créer un système d'appel vocal textuel capable de gérer les appels entrants et sortants. À l'avenir, vous pourrez personnaliser la réponse en fonction de la personne qui appelle, de l'heure de la journée ou de toute autre chose à laquelle vous pouvez penser.

Quelle est la prochaine étape ?

Quelle est la prochaine étape ? Vous pourriez étendre votre application pour en faire un système d'alerte critique basé sur la Voice en passant en boucle par une liste de contacts pour diffuser des appels et demander aux destinataires d'appuyer sur un numéro pour confirmer la réception de vos messages.