Gestion des entrées au clavier (DTMF) avec PHP

Dans ce tutoriel, nous allons voir tout ce qu'il faut savoir pour mettre en place une application PHP qui peut recevoir des appels entrants et capturer les entrées utilisateur saisies via le clavier.

En suivant ce tutoriel, vous obtiendrez une application simple qui peut être étendue pour inclure des éléments interactifs plus complexes et vous donner une longueur d'avance dans la création de menus interactifs pour vos appelants.

Le code de ce tutoriel se trouve sur GitHub.

Conditions préalables

TL;DR - Vous aurez besoin des éléments suivants :

• Un numéro de téléphone qui n'est pas déjà associé à une autre application.

• PHP (>5.6), Composer et le Slim

• ngrok

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.

Voici la version longue :

Si vous voulez nous suivre, vous aurez besoin d'un Account Nexmo pour commencer, alors inscrivez-vous dès maintenant si vous n'en avez pas déjà un.

Recevoir un appel téléphonique avec Numbers est facturé 0,0045 €/min et vous devrez louer un numéro à appeler. Nous verrons cela plus tard.

Le code de l'exemple utilise le cadre Slim pour gérer les requêtes. Nous l'avons choisi en raison de sa simplicité et de sa lisibilité, mais si vous êtes familier avec PHP et que vous souhaitez gérer cela d'une autre manière, vous pouvez utiliser quelque chose de différent. Vous devrez installer Slim à l'aide de Composer donc assurez-vous que vous l'avez également configuré.

Le code que vous allez créer devrait fonctionner avec n'importe quelle version de PHP 5.6 ou supérieure.

Notre méthode recommandée pour travailler avec Nexmo, du point de vue de l'administration, est d'utiliser notre outil de ligne de commande, Nexmo-CLI.

Afin de rendre le code de notre machine locale accessible au monde extérieur, nous allons utiliser ngrokassurez-vous donc qu'il est également installé.

Réception de l'appel entrant

Lorsque Numbers reçoit un appel sur un numéro que vous avez loué, une requête HTTP est envoyée à une URL (un "webhook", que vous spécifiez) qui contient toutes les informations nécessaires pour recevoir l'appel et y répondre. Cette URL est communément appelée URL de réponse.

Nous recueillerons également les données DTMF de nos appelants. DTMF signifie Multifréquence à deux tons et, dans le cas de ce tutoriel, se produit lorsqu'un utilisateur appuie sur un numéro de son clavier.

Chaque fois qu'une entrée DTMF est collectée auprès de l'utilisateur, elle est envoyée à une URL différente dans votre application, que nous devrons également spécifier.

Ensuite, nous commencerons par écrire le code nécessaire pour traiter ces demandes.

Pour installer Slim à l'aide de Composer, exécutez la commande suivante dans le dossier du projet dans votre terminal :

Ensuite, dans votre dossier principal, créez un nouveau fichier appelé index.php et ajoutez-y le code suivant :

<?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('/webhooks/answer', function (Request $request, Response $response) {
    $uri = $request->getUri();
    $ncco = [
        [
            'action' => 'talk',
            'text' => 'Please enter a digit'
        ],
        [
            'action' => 'input',
            'maxDigits' => 1,
            'eventUrl' => [
                $uri->getScheme().'://'.$uri->getHost().'/webhooks/dtmf'
            ]
        ]
    ];

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

$app->run();

Avec ce code, nous mettons en place une nouvelle URL dans notre application, webhooks/answerqui répondra à tous les appels entrants à votre numéro de téléphone avec les instructions fournies dans le $ncco tableau.

Le $ncco effectuera ces étapes une fois que l'appel aura été pris :

1. Lisez le texte "Veuillez entrer un chiffre".

2. Capturer le chiffre saisi par l'appelant

3. Transmettre l'entrée qui a été capturée à la route qui gère l'entrée, /webhooks/dtmf

Traiter les données de l'utilisateur

Ajoutons le code permettant de gérer les DTMF entrants en index.php:

Après le code que nous avons saisi ci-dessus, et avant $app->run(); ajoutez ce qui suit :

$app->post('/webhooks/dtmf', function (Request $request, Response $response) {
    $params = $request->getParsedBody();

    $ncco = [
        [
            'action' => 'talk',
            'text' => 'You pressed '.$params['dtmf']
        ]
    ];

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

La fonction de cet itinéraire permet d'effectuer les étapes suivantes :

1. Recevoir la contribution de /webhooks/answer

2. Analyse le corps de la demande dans une variable, $params

3. Créez un nouveau $ncco qui répond à l'appelant et lui indique le numéro qu'il a composé.

À titre de référence, votre fichier final index.php devrait ressembler exactement à celui-ci.

Maintenant que vous êtes prêt à exécuter le code, vous pouvez le faire en entrant la commande suivante dans votre terminal :

Cela permettra de démarrer un serveur et d'acheminer le trafic vers votre site web. http://localhost:3000 vers votre fichier index.php fichier.

Exposez votre application avec ngrok

Afin de permettre à Nexmo de faire des requêtes à votre application, vous devez exposer au monde entier le code qui s'exécute sur votre machine locale.

ngrok est notre outil de prédilection pour cela, et nous avons fourni une excellente introduction à l'outil que vous pouvez lire pour vous mettre à niveau si vous ne l'avez pas encore utilisé.

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

Acheter un numéro et créer une application

Le code étant terminé et notre application étant accessible au monde entier, nous devons maintenant nous procurer un numéro de téléphone et y associer ce code, qui sera exécuté localement.

Commençons par acheter un numéro via le CLI de Nexmo :

Vous pouvez utiliser un autre code de pays si vous le souhaitez. Notez le numéro que vous achetez, car nous en aurons besoin à l'étape suivante.

Nous devons maintenant créer une application Nexmo, qui est un conteneur pour tous les paramètres nécessaires à votre application. Dans ce cas, nous devons indiquer à Nexmo l'URL à laquelle adresser une requête lorsqu'un appel entrant est reçu (l'élément answer_url), et où envoyer toute information sur l'événement concernant l'appel (l'URL event_urlPour en savoir plus sur les événements, reportez-vous à la section Flux d'appels pour en savoir plus sur les événements).

Utilisez le CLI Nexmo pour créer votre application en vous assurant de remplacer <your_ngrok_url> par votre propre URL générée par ngrok :

La réponse que vous obtiendrez en retour contiendra une énorme sortie de clé privée et, au-dessus, un identifiant d'application. Vous pouvez ignorer la clé privée car elle n'est pas nécessaire pour traiter les appels entrants.

Notez l'identifiant de la demande (qui ressemble à ceci : e7a25242-77a1-42cd-a32e-09febcb375f4) et associez-le à votre nouveau numéro :

Voilà tout ce qu'il faut pour associer le code ci-dessus à votre application et numéro Nexmo. Vous pouvez le tester en composant le numéro que vous avez acheté et en suivant les étapes qui vous sont énoncées comme par magie à l'autre bout du fil !

Conclusion

En seulement trente lignes de PHP, vous avez maintenant une application qui peut recevoir un appel entrant et collecter les données DTMF de l'appelant. Comment pourriez-vous développer cette application à partir de maintenant ?

Si vous souhaitez en savoir plus sur les possibilités offertes par les appels vocaux entrants et sur la manière dont vous pouvez les rendre plus complexes en ajoutant des fonctions telles que l'enregistrement audio, vous pouvez en apprendre davantage sur le fonctionnement de vos NCCO 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.