Renvoyer un appel via Voice Proxy avec Koa.js

Introduction

Ce tutoriel vous montre comment ajouter des fonctionnalités vocales à votre application. Nous utiliserons Koa, un framework web pour Node.js, pour créer un serveur qui gère les appels entrants et les événements, ainsi que l Voice API de Vonage de Vonage pour transférer les appels vers un autre numéro de téléphone. Commençons par le commencement.

Schéma du projet

À la fin de ce projet, voici à quoi devrait ressembler votre dossier de projet :

Conditions préalables

Pour suivre ce tutoriel, vous aurez besoin de :

• Node.js installé

• Ngrok est installé pour exposer votre serveur de développement local à l'internet.

• Un Account Vonage Developer pour accéder à notre Voice API.

  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.

Mise en place Ngrok

Pour pouvoir exposer des points d'accès à partir de nos machines locales sans avoir à déployer notre application dans un environnement réel, nous allons rendre notre serveur local accessible à l'internet à l'aide de ngrok

Une fois installé, dans une nouvelle fenêtre de terminal ou d'invite de commande, lancez ngrok sur le port 3000 :

ngrok http 3000

Configurer Vonage

Mise en place de laCLI Vonage

Vous pouvez créer et gérer des applications Vonage à l'aide de la CLI de Vonage. Installez-le si vous ne l'avez pas encore fait :

npm install @vonage/cli -g

Configuration de la clé et du secret de l'API

Exécutez la commande pour définir la configuration de la clé et du secret de l'API. Après cela, vous verrez Configuration saved sur votre terminal ou dans l'invite de commande.

Les VONAGE_KEY et VONAGE_SECRET se trouvent sur le tableau de bord de Vonage.

Vonage Dashboard

Créer une application

Utilisez la CLI pour créer une nouvelle application avec des capacités vocales et notez l'identifiant de l'application fourni lors de la création. Exécutez la commande pour créer une nouvelle Application Vonage.

Ensuite, une invite contenant plusieurs champs s'affiche et vous devez les remplir comme suit.

Vous devriez obtenir une réponse similaire à celle-ci :

Louer un numéro virtuel

Ensuite, nous aurons besoin d'un numéro virtuel qui servira de "visage public" pour les appels entrants. Ce numéro sera lié à notre application Vonage, et voici comment en acquérir un :

1. Recherchez les numéros disponibles dans la région souhaitée. Heureusement, il est possible d'acheter des numéros directement à partir de l'interface de programmation, comme ceci ! vonage numbers:search US (remplacez US par le code de votre pays si nécessaire).

2. Acheter un numéro : vonage numbers:buy 12079460000 US.

N'oubliez pas que certains numéros ne peuvent pas être achetés via la ligne de commande, vous devez donc les acheter via le tableau de bord. Vous pouvez le faire en allant sur le Tableau de bord Vonage et la page Acheter des Numbers. Cochez 'Voice' dans le filtre de recherche et sélectionnez le pays dans lequel vous souhaitez acheter un numéro.

Associer un numéro de téléphone virtuel à l'Applications

Une fois notre numéro choisi, il est temps de le connecter à notre application Vonage. Vous pouvez lier un numéro de téléphone virtuel directement à partir du tableau de bord de Vonage ou via le CLI. La liaison permet de s'assurer que les appels vers votre numéro virtuel sont correctement acheminés via votre application.

vonage apps:link --number=12079460000 APPLICATION_ID

Vous pouvez également le faire à partir du tableau de bord. Allez à la page Applications et cliquez sur l'application que vous avez créée précédemment. Cliquez sur le bouton 'Link' dans la section Voice à côté du numéro que vous souhaitez lier.

Créer le projet Node.js

1. Créez un nouveau répertoire pour votre projet et naviguez-y. (Exemple de dossier VoiceWithVonage)

2. Initialiser un nouveau projet Node.js avec npm init -y pour accepter tous les paramètres par défaut.

Installer les dépendances

Notre projet s'appuie sur quelques dépendances, que nous installerons avec une seule commande :

Variables d'environnement

Nous utiliserons des variables d'environnement pour stocker des informations sensibles telles que les clés d'API et les numéros de téléphone afin que notre application reste sécurisée et gérable.

Créez un fichier .env à la racine de votre projet et ajoutez vos variables référez-vous à l'article de Michael pour une meilleure explication de l'utilisation des variables d'environnement dans Node.js

// .env
VONAGE_API_KEY= Your Vonage API key, used for authenticating API requests.
VONAGE_API_SECRET= Your Vonage API secret
VONAGE_APPLICATION_ID= The ID of your Vonage application. Vonage applications allow you to manage your communication services and define how they interact with your web application.
VONAGE_PRIVATE_KEY= The path to your Vonage application's private key file. When you create a Vonage application that uses voice capabilities, you generate a public/private key pair. The private key authenticates your application when making API requests. It will  look like nameOfTheFile.key.
FROM_NUMBER= The Vonage virtual number (purchased through Vonage) that calls will come from. It is the number displayed to the user receiving the call.
YOUR_SECOND_NUMBER= The destination phone number to which the call will be forwarded. It should be in [E.164 format](https://en.wikipedia.org/wiki/E.164).

Initialiser Vonage

Le SDK du serveur Vonage facilite l'intégration aux services de Vonage. Initialisez-le dans votre projet pour activer la fonctionnalité vocale, en veillant à ce que les valeurs de substitution soient remplacées par vos informations d'identification API stockées dans votre fichier .env dans votre fichier

Créez un fichier appelé forward_a_call.js et le code ci-dessous.

// forward_a_call.js
require("dotenv").config();
const { Vonage } = require("@vonage/server-sdk");

// Initialize the Vonage Server SDK with your credentials
const vonage = new Vonage({
 apiKey: process.env.VONAGE_API_KEY,
 apiSecret: process.env.VONAGE_API_SECRET,
 applicationId: process.env.VONAGE_APPLICATION_ID,
 privateKey: process.env.VONAGE_PRIVATE_KEY,
});

Mise en place du Koa

Nous commençons par mettre en place notre environnement serveur :

require("dotenv").config();
const Koa = require("koa");
const Router = require("@koa/router");
const koaBody = require("koa-bodyparser");

const app = new Koa();
const router = new Router();

app.use(koaBody());

Ici, nous importons les modules nécessaires et initialisons notre application Koa. dotenv charge les variables d'environnement (comme vos identifiants API Vonage et vos numéros de téléphone) à partir d'un fichier .env à partir d'un fichier

L'intergiciel koaBodyparser est utilisé pour analyser le corps des requêtes entrantes, ce qui est essentiel pour lire les données JSON dans notre webhook /event.

De plus, nous utilisons @koa/router, un middleware de routage, pour définir et gérer les routes au sein de notre application. Cela nous permet de spécifier des actions pour différents chemins, tels que /answer pour répondre aux appels et /event pour traiter les événements webhook.

Répondre aux appels avec le BCN

L'itinéraire est défini comme la réponse aux appels entrants. /answer est défini comme la réponse aux appels entrants. Lorsque la plateforme Vonage reçoit un appel à votre numéro virtuel, elle demande à ce point d'extrémité de récupérer des instructions, connues sous le nom de NCCO (Call Control Object), sur le traitement de l'appel. /answer de récupérer des instructions, connues sous le nom de NCCO (Call Control Object), sur le traitement de l'appel.

Dans cet exemple, le NCCO demande à Vonage de diffuser d'abord un message (" Veuillez patienter pendant que nous connectons votre appel "), puis de connecter l'appel à un autre numéro spécifié (YOUR_SECOND_NUMBER), en utilisant votre numéro Vonage (FROM_NUMBER) comme identifiant de l'appelant.

router.get("/answer", async (ctx) => {
  const ncco = [
    {
      action: "talk",
      text: "Please wait while we connect your call.",
    },
    {
      action: "connect",
      eventUrl: [],
      from: process.env.FROM_NUMBER,
      endpoint: [
        {
          type: "phone",
          number: process.env.YOUR_SECOND_NUMBER,
        },
      ],
    },
  ];
  ctx.body = ncco;
});

Traiter les événements, appliquer les itinéraires et démarrer le serveur

L'itinéraire /event capture et enregistre les événements liés à l'appel. Ce point d'accès est essentiel pour le débogage et le suivi du cycle de vie de vos appels. Les événements peuvent inclure des statuts d'appel tels que "répondu", "terminé" ou "échoué". L'enregistrement de ces événements permet de mieux comprendre le flux des appels et de résoudre les problèmes éventuels.

Enfin, nous appliquons nos routes à l'application Koa et démarrons le serveur.

router.post("/event", async (ctx) => {
  console.log(ctx.request.body);
  ctx.status = 204; // No content to send back
});

app.use(router.routes()).use(router.allowedMethods());

app.listen(3000, () => console.log("Server running on port 3000"));

L'application écoute sur le port 3000 et enregistre un message dans la console une fois que le serveur s'exécute. Ici, les routes que nous avons définies deviennent accessibles, permettant à la plateforme Vonage d'interagir avec notre serveur sur la base des URL spécifiées dans le tableau de bord Vonage pour les webhooks de réponse et d'événement de notre application.

Exécuter et tester l'application

Une fois que tout est en place, démarrez votre serveur en exécutant la commande :

Testez le renvoi d'appel en composant votre numéro virtuel Vonage. L'appel doit être redirigé vers le numéro spécifié dans votre fichier .env fichier

Conclusion et connexion avec nous

Félicitations ! Vous êtes maintenant passé maître dans l'art du renvoi d'appel avec Vonage. Si vous avez des questions ou des suggestions, ou si vous voulez partager ce que vous avez construit, rejoignez notre Communauté Slack des développeurs de Vonage ou contactez-nous sur X, anciennement connu sous le nom de Twitter.

Pour en savoir plus

Élaborer un plan d'évasion avec l'API Voice de Vonage et obtenir un appel fantôme

Transférer un appel avec le NCCO