Recevoir un appel vocal entrant avec PHP

Dans notre dernier article de blog sur PHP et Voice, nous avons expliqué comment passer un appel vocal sortant en utilisant la synthèse vocale (Text-To-Speech). appel vocal sortant en utilisant le Text-To-Speech. Dans ce billet, nous allons changer de direction et écrire une application qui gère les appels vocaux entrants et renvoie une réponse dynamique.

Le code source de ce billet est disponible sur Github.

Conditions préalables

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.

Vous devez installer PHP avant de lire ce billet. J'utilise PHP 7.2, mais le code ici devrait fonctionner avec PHP 5.6 et plus. Vous aurez également besoin de Composer pour télécharger nos dépendances.

Enfin, vous aurez besoin du CLI de Vonage de Vonage. Nous l'utiliserons pour configurer notre Account Vonage et acheter un numéro de téléphone.

Recevoir un appel téléphonique avec PHP

Avant d'entrer dans les détails du fonctionnement, nous commencerons par créer une application PHP pour gérer les appels vocaux entrants. Lorsqu'un appel vocal est reçu, Voice adresse une demande à votre application pour savoir comment répondre à cet appel.

Nous allons utiliser le cadre Slim pour gérer les requêtes entrantes, alors installons-le maintenant avec composer:

Une fois cette opération terminée, créez un nouveau fichier nommé index.php avec le contenu suivant. Ce fichier créera une nouvelle application Slim et enregistrera un seul point de terminaison (/webhook/answer) qui accepte une requête GET avec un paramètre from et renvoie la valeur from dans le corps de la requête.

<?php
use \Psr\Http\Message\ServerRequestInterface as Request;
use \Psr\Http\Message\ResponseInterface as Response;

require 'vendor/autoload.php';

$app = new \Slim\App;
$app->get('/webhook/answer', function (Request $request, Response $response) {
    $params = $request->getQueryParams();
    return $response->withJson($params['from']);
});

$app->run();

Enregistrez ce fichier et ouvrez une nouvelle fenêtre de terminal. Démarrons le serveur PHP intégré et servons notre application sur le port 8000.

Si vous visitez http://localhost:8000/webhook/answer?from=14155550100vous verrez le from renvoyé dans le corps de la réponse.

C'est un bon début, mais Vonage ne saura pas quoi faire si nous ne répondons qu'avec le numéro de téléphone de l'appelant. Pour indiquer à Vonage comment traiter l'appel, nous devons renvoyer un code NCCO.

Pour simplifier les choses, nous utiliserons la synthèse vocale pour lire le numéro de téléphone de l'appelant, chiffre par chiffre. Tout d'abord, nous divisons le numéro en un tableau de caractères, puis nous les associons à l'aide d'espaces :

$fromSplitIntoCharacters = implode(" ", str_split($params['from']));

Ensuite, nous définissons un NCCO qui utilise l'action pour lire ces caractères. talk pour lire ces caractères :

$ncco = [
    [
        'action' => 'talk',
        'text' => 'Thank you for calling from '.$fromSplitIntoCharacters
    ]
];

Enfin, nous renvoyons ce NCCO au lieu de $params['from']:

return $response->withJson($ncco);

Lorsque nous mettons tout cela ensemble, index.php ressemble à ce qui suit :

<?php
use \Psr\Http\Message\ServerRequestInterface as Request;
use \Psr\Http\Message\ResponseInterface as Response;

require 'vendor/autoload.php';

$app = new \Slim\App;
$app->get('/webhook/answer', function (Request $request, Response $response) {
    $params = $request->getQueryParams();
    $fromSplitIntoCharacters = implode(" ", str_split($params['from']));

    $ncco = [
        [
            'action' => 'talk',
            'text' => 'Thank you for calling from '.$fromSplitIntoCharacters
        ]
    ];

    return $response->withJson($ncco);
});

$app->run();

Visiter http://localhost:8000/webhook/answer?from=14155550100 et vous verrez la page suivante s'afficher :

[
  {
    "action": "talk",
    "text": "Thank you for calling from 1 4 1 5 5 5 5 0 1 0 0"
  }
]

Vous venez d'écrire une application qui reçoit un appel téléphonique entrant et y répond par un contenu dynamique. Vous venez d'écrire une application qui reçoit un appel téléphonique entrant et y répond par un contenu dynamique. Vous pouvez personnaliser votre réponse en utilisant l'un des paramètres fournis par Vonage, notamment to, from et conversation_uuid.

Exposer votre application avec ngrok

Nous avons construit une application qui répond comme nous l'avions prévu, mais il y a un gros problème pour l'instant. Vonage est censé lui adresser une requête lorsqu'un appel est reçu, mais elle tourne sur notre machine locale !

Ne vous inquiétez pas, ngrok peut vous sauver la mise. Si vous n'êtes pas familier avec ngrok, il y a une fantastique introduction à ngrok sur le blog de Vonage.

Une fois ngrok installé, lancez ngrok http 8000 pour exposer votre application à l'internet. Vous devrez noter l'URL générée car nous devrons la fournir à Vonage. ngrok générée car nous devrons la fournir à Vonage (elle ressemblera à quelque chose comme http://abc123.ngrok.io).

Configurez votre Account Vonage

Une fois que votre application est exposée à l'Internet, la dernière chose à faire est de la relier à un numéro de téléphone Vonage. Commençons par acheter un numéro de téléphone à l'aide de la CLI de Vonage. Tout d'abord, recherchez un numéro :

Ensuite, achetez l'un des Numbers listés comme disponibles :

L'étape suivante consiste à créer une application Vonage, qui est un conteneur pour tous les paramètres nécessaires à votre application. Dans ce cas, nous devons indiquer à Vonage l'URL à laquelle adresser une requête lorsqu'un appel est reçu (answer_url) et où envoyer toute information sur l'événement concernant l'appel (event_url).

Nous pouvons utiliser l'interface de programmation Nexmo pour créer une application, en veillant à remplacer http://abc123.ngrok.io par votre propre URL. Nous fournissons un nom, puis un answer_url et event_url pour l'application :

Notez l'identifiant de votre application (il ressemblera à aaaaaaaa-bbbb-cccc-dddd-0123456789ab), puis poursuivez votre lecture.

La dernière chose à faire est de lier le numéro que vous avez acheté à l'application que vous venez de créer. Cela indiquera à Vonage que lorsqu'un appel est reçu, il doit faire une GET demande à la base de données de l'application answer_url de l'application pour savoir comment procéder à l'appel.

Une fois de plus, nous pouvons utiliser l'interface CLI de Numbers pour effectuer cette opération, en remplaçant le numéro de téléphone et l'identifiant d'application de l'exemple par les vôtres :

C'est tout ce que nous devions faire pour que Vonage associe notre application PHP à un appel téléphonique entrant. Essayez-le maintenant en appelant le numéro de téléphone que vous avez acheté.

Conclusion

Ensemble, nous venons de construire une application capable de recevoir un appel téléphonique entrant et de générer dynamiquement une réponse en seulement 22 lignes de code !

Si vous souhaitez en savoir plus sur les appels vocaux avec PHP et Vonage, vous pouvez trouver des exemples de blocs de construction dans Nexmo Developer. Par ailleurs, si vous souhaitez rendre votre réponse aux appels entrants plus complexe (par exemple en enregistrant l'audio de l'appelant), vous pouvez en savoir plus sur les NCCOs dans la référence NCCO

Comme toujours, si vous avez des questions sur cet article, n'hésitez pas à envoyer un e-mail à devrel@nexmo.com ou à rejoindre le canal Slack de la communauté Nexmo. rejoignez le canal Slack de la communauté Nexmooù nous vous attendons et sommes prêts à vous aider.