Construire un proxy vocal avec PHP et Voice

Introduction

Ce tutoriel sur le renvoi d'appel de Vonage vous montre comment faire suivre un appel vocal de manière à ce qu'il semble provenir d'un autre numéro.

Ce n'est pas aussi douteux que cela en a l'air : il existe de nombreuses raisons commerciales convaincantes de vouloir cacher le vrai numéro d'un appelant aux autres parties de l'appel.

Un exemple classique est celui d'un service de taxi en ligne. Pour que l'expérience de réservation soit aussi fluide que possible, vous souhaitez que le client et le chauffeur puissent communiquer entre eux. Mais vous ne voulez pas que le chauffeur connaisse le numéro réel du client (pour protéger la vie privée du client), et vous ne voulez pas non plus que le client connaisse le numéro du chauffeur, de sorte qu'ils ne peuvent pas réserver des courses directement sans passer par votre service.

Heureusement, cela peut être mis en œuvre en quelques étapes seulement en utilisant l Voice API de Vonage de Vonage en PHP, alors commençons !

TLDR ; le code source complet code source est disponible sur GitHub.

Conditions préalables

• PHP8.3+

• Compositeur

• Un Account API de Vonage

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.

Installer les dépendances

Créez un répertoire qui contiendra votre code, puis utilisez Composer pour générer un nouveau projet :

composer init

Vous pouvez ignorer toutes les questions interactives en appuyant sur la touche retour, qui utilisera les valeurs par défaut. Refusez d'ajouter des paquets de manière interactive ; nous ajouterons tout ce dont nous avons besoin pour ce projet à l'étape suivante.

Composer génère son fichier de configuration composer.jsonet un dossier de dépendances, vendor.

Pour travailler avec les appels entrants en utilisant l'API Voice de Vonage, vous devrez fournir des webhooks afin que Vonage puisse envoyer des données à votre application.

Dans cet exemple, nous utiliserons Slim-un framework web PHP léger, pour implémenter ces webhooks. Ensuite, nous allons utiliser le framework Slim et une interface compatible avec la interface compatible PSR-7 pour les classes de requête/réponse, puis vlucas/phpdotenvpour la gestion des variables d'environnement.

composer require slim/slim
composer require slim/psr7
composer require vlucas/phpdotenv

Maintenant que toutes les dépendances sont triées, nous pouvons passer à l'écriture de notre code.

Définir les points de terminaison du Webhook

Dans votre répertoire de travail, créez un fichier public/index.php contenant le code suivant :

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


require __DIR__ . '/../vendor/autoload.php';


$app = AppFactory::create();


$app->addBodyParsingMiddleware();
$app->addRoutingMiddleware();
$app->addErrorMiddleware(true, true, true);


// Forward a call via proxy
$app->get('/webhooks/answer', function (Request $request, Response $response) {
   // Code to process the inbound call
});


$app->post('/webhooks/events', function (Request $request, Response $response, array $args) {
   // Code that executes when an event is received
   error_log('event received: ' . $request->getBody());
   return $response->withStatus(204);
});


$app->run();

Ce code crée une nouvelle application Slim et définit deux routes. Ces routes correspondent aux points d'arrivée des webhooks suivants :

• /webhooks/answer: Vonage fait une GET demande à ce point d'extrémité lorsque vous recevez un appel entrant sur votre numéro virtuel.

• /webhooks/events: Vonage fait une POST demande à ce point de terminaison chaque fois qu'un événement important se produit (comme la sonnerie, la réponse et la fin de l'appel) pour mettre à jour votre application sur l'état de l'appel.

Voir la Référence pour les webhooks pour plus de détails.

Traiter les appels entrants

Lorsque vous recevez un appel entrant, l'API de Vonage effectue une GET demande à votre point de terminaison /webhooks/answer et s'attend à ce que la réponse contienne des instructions sur la façon de traiter l'appel.

Vous fournissez ces instructions sous la forme d'un objet de contrôle d'appel (NCCO) au format JSON. Le NCCO définit les différentes "actions" que l'appel doit effectuer, par exemple input collecter les chiffres que l'utilisateur pourrait appuyer sur le clavier de son téléphone ou stream la diffusion d'un son dans l'appel. Vous trouverez la liste complète des actions dans le document Référence NCCO.

Avant de nous occuper de la logique du proxy, assurons-nous d'abord que nous pouvons recevoir des appels entrants sur notre numéro Vonage.

Testez votre application avec une action talk qui utilise la synthèse vocale pour lire un message à votre interlocuteur. Définissez et renvoyez le NCCO suivant dans votre /webhooks/answer route handler :

$app->get('/webhooks/answer', function (Request $request, Response $response) {
    $ncco = [
        [
            'action' => 'talk',
            'text' => 'Thank you for calling. Everything appears to be working properly'
        ]  
    ];

    $response->getBody()->write(json_encode($ncco));
    return $response->withHeader('Content-Type', 'application/json');
});

Rendre vos Webhooks accessibles

Pour que les API de Vonage fassent des demandes à vos points d'extrémité de crochet Web, ils doivent être accessibles sur Internet.

Un excellent outil pour exposer votre environnement de développement local à l'Internet public est ngrok. Notre tutoriel vous montre comment l'installer et l'utiliser.

Lancez ngrok à l'aide de la commande suivante :

ngrok http 8080

Notez l'URL publique que ngrok a créée pour vous.

https://123example.ngrok-free.app -> http://localhost:8080

Sur le plan gratuit, ngrok génère une nouvelle URL à chaque redémarrage, et vous devrez mettre à jour la configuration de votre application Voice API. Laissez-le donc en marche pendant toute la durée de ce tutoriel.

Ensuite, configurons les choses du côté de Vonage !

Acheter un Numbers Vonage

Créer une application Voice-Enabled de Vonage

Vous devez maintenant créer une application Vonage basée sur la Voice. Dans ce contexte, une application n'est pas la même que l'application dont vous venez d'écrire le code. Il s'agit plutôt d'un conteneur pour les informations de configuration et de sécurité dont vous avez besoin pour utiliser l'API Voice.

Avant de cliquer sur Générer une nouvelle applicationassurez-vous d'avoir activé la fonction Voice et que vous avez défini les URL de réponse et d'événement comme indiqué ci-dessous, en utilisant votre lien ngrok des étapes précédentes.

Correct configuration for a voice-enabled Vonage ApplicationNotez que nous utilisons HTTP GET pour l'URL de la réponse et HTTP POST pour l'URL de l'événement.

Une fois que vous êtes satisfait de votre configuration, allez-y et Générer une nouvelle application.

Screenshot of Create Application

Liez l'Applications à votre numéro Vonage

Votre application Vonage étant maintenant créée, vos numéros virtuels disponibles apparaîtront au bas de l'écran, y compris celui que vous avez acheté à l'étape précédente.

Sélectionnez le numéro que vous souhaitez utiliser pour ce tutoriel, puis cliquez sur le bouton lier à côté pour relier votre numéro virtuel et l'Application Vonage.

Screenshot of the Vonage Dashboard showing available phone numbers to link to the application we createdPar conséquent, lorsque vous appellerez votre numéro virtuel, Vonage cherchera des instructions de flux d'appels à l'URL que vous avez spécifié comme suit URL de réponseet enverra des webhooks d'événement à votre URL d'événement.

Ensuite, vérifions que tout ce que nous avons fait jusqu'à présent fonctionne bien.

Appelez votre numéro virtuel Vonage

Avec ngrok fonctionnant sur le port 8080 dans une fenêtre de terminal, lancez votre application PHP sur le même port dans une autre :

cd public
php -S localhost:8080

Appelez votre numéro Vonage. Si tout fonctionne correctement, vous devriez entendre le message que vous avez défini dans votre NCCO, puis l'appel se termine.

Mise en œuvre de la logique de proxy Voice

Pour masquer l'identité de l'appelant, nous connecterons un appel entrant au numéro de notre destinataire cible et utiliserons notre numéro virtuel Vonage pour masquer le numéro réel de l'appelant entrant.

Dans votre fichier index.php créez deux constantes de type chaîne de caractères pour stocker les valeurs FROM_NUMBER et TO_NUMBER. L'extrait de code ci-dessous extrait ces valeurs de l'environnement, ce qui est une bonne pratique à suivre.

$dotenv = Dotenv\Dotenv::createImmutable(__DIR__ . '/../');
$dotenv->load();

define('FROM_NUMBER', $_ENV['FROM_NUMBER']);
define('TO_NUMBER', $_ENV['TO_NUMBER']);

Créez ensuite un fichier .env à la racine de votre répertoire de travail et attribuez les valeurs de ces deux constantes. Les deux nombres doivent inclure le code du pays et omettre les zéros initiaux. Par exemple, au Royaume-Uni, le code du pays est le suivant 44. Par conséquent, si mon numéro de téléphone portable est le suivant 07700900004le format correct est 447700900004.

// Your Vonage virtual number

FROM_NUMBER=4474example01

// A landline or mobile number you can use for testing. This should differ from the number you will use to make the initial call.

TO_NUMBER=4478example02

Enfin, mettons à jour le NCCO pour y inclure une action connect qui demande à Vonage de connecter l'appelant entrant au destinataire. Dans votre fichier index.php mettez à jour le point de terminaison /webhooks/answer avec ce qui suit :

// Forward a call via proxy
$app->get('/webhooks/answer', function (Request $request, Response $response) {
    $ncco = [
        [
            'action' => 'connect',
            'from' => FROM_NUMBER,
            'endpoint' => [
                [
                    'type' => 'phone',
                    'number' => TO_NUMBER,
                ]
            ]
        ]
        
    ];

    $response->getBody()->write(json_encode($ncco));
    return $response->withHeader('Content-Type', 'application/json');
});

Tester le Voice Proxy

Assurez-vous que ngrok fonctionne toujours dans une fenêtre de terminal et relancez votre application PHP dans une autre :

cd public
php -S localhost:8080

Appelez votre numéro virtuel Vonage. Lorsque l'appel est pris, votre deuxième numéro doit sonner immédiatement. Cet appel doit provenir de votre numéro Vonage et non du numéro que vous avez utilisé pour passer l'appel.

Voilà, c'est fait ! Vous avez maintenant mis en œuvre un proxy vocal simple qui cache le numéro réel de l'appelant.

Pour en savoir plus

Si vous souhaitez en savoir plus sur l'API Voice, consultez les ressources suivantes :

• Aperçu de l'API Voice

• Référence de l'API Voice

• Référence NCCO

Conclusion

Dans ce tutoriel, nous avons construit un proxy vocal en utilisant PHP et l'API Voice de Vonage pour transférer les appels tout en masquant l'identité de l'appelant. À partir de là, vous pouvez étendre cette solution avec l'enregistrement des appels, le routage dynamique ou le mappage des numéros à partir d'une base de données.