Comment construire un SVI simple avec Java et le framework Spark

Un SVI est le nom technique donné à un appel téléphonique automatisé où vous entrez des chiffres sur le clavier de votre téléphone et l'appel répond de manière appropriée - en vous lisant des informations, ou en vous connectant à un numéro, ou quoi que ce soit d'autre. L'avantage est que vous pouvez les créer avec Nexmo Voice !

Dans ce tutoriel, vous allez construire un petit microservice pour héberger un SVI de base. Je vous expliquerai tout ce que vous devez savoir pour mettre en place un service Spark capable de recevoir des appels entrants et de capturer les données saisies par l'utilisateur via le clavier.

L'idée est de construire un très petit SVI qui permet à l'utilisateur de saisir un code DTMF. Dans ce Dans ce Dans ce cas, l'appel vous lira simplement le numéro que vous avez saisi.

Je trouve qu'il est très utile d'avoir un script ou un organigramme à portée de main lors de la création d'un SVI. Voici le script pour votre service :

[Caller dials Nexmo number]

IVR: Welcome to my Nexmo IVR! Please enter a digit.

[Caller enters '5']

IVR: You entered 5. Thank you for calling!

[IVR hangs up]

Le code de ce tutoriel se trouve sur GitHub.

Exigences

Avant de commencer, vous devez disposer des éléments suivants :

• La CLI Nexmo. (Vous pouvez vous en passer en utilisant le Nexmo Dashboard, mais cela rend la vie beaucoup beaucoup plus facile).

• A JDK installé (j'ai réalisé ce projet avec le JDK 8).

• Maven pour construire votre code Java.

• Ngrok pour que Nexmo puisse accéder au service fonctionnant sur votre machine de développement

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.

Pour commencer

Tout d'abord, il faut créer un projet Maven à l'aide de la commande suivante :

L'exécution de cette commande créera un fichier de projet Maven et un fichier source au bon endroit - cela ressemble un peu à ceci :

ivr-demo
├───pom.xml
└───src
    └───main
        └───java
            └───com
                └───nexmo
                    └───xwithy
                        └───App.java

Ouvrez pom.xml dans votre éditeur de code préféré (j'utilise VSCode) et commencez par changer la version cible de Java de 1.7 à 1.8 :

<maven.compiler.source>1.8</maven.compiler.source>
<maven.compiler.target>1.8</maven.compiler.target>

Ajoutez ensuite les dépendances Nexmo et Spark à la section <dependencies> :

<dependency>
    <groupId>com.nexmo</groupId>
    <artifactId>client</artifactId>
    <version>4.4.0</version>
</dependency>

<dependency>
    <groupId>com.sparkjava</groupId>
    <artifactId>spark-core</artifactId>
    <version>2.7.2</version>
</dependency>

<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-simple</artifactId>
    <version>1.7.21</version>
</dependency>

Je vous recommande maintenant de compiler le projet, juste pour télécharger les dépendances et vous assurer que tout va bien dans votre projet :

Vous devriez voir un grand nombre de résultats alors que Maven télécharge tout ce dont il a besoin, et ensuite le message BUILD SUCCESS. Si ce n'est pas le cas, vérifiez votre fichier XML pour vous assurer que vous avez entré la configuration ci-dessus correctement et au bon endroit.

Prenons des appels téléphoniques

Je vais expliquer comment construire le code étape par étape, mais il peut être utile de jeter un coup d'œil au résultat final, que vous pouvez trouver sur GitHub. Tout est dans une classe, et j'ai ajouté beaucoup de commentaires, donc j'espère que ce ne sera pas trop difficile à suivre.

Presque tout se passe à l'intérieur de notre méthode main qui est exécutée lorsque nous lançons la App classe. Spark peut fonctionner un peu différemment de ce à quoi vous êtes habitué. Vous enregistrez la manière dont vous souhaitez que Spark se comporte en appelant des méthodes statiques, puis Spark hébergera votre application web jusqu'à ce que vous lui disiez d'arrêter !

Ajoutez la ligne suivante dans votre méthode main méthode :

port(4567);

La ligne ci-dessus indique à Spark le port TCP sur lequel vous souhaitez héberger votre service. J'ai choisi 4567. Vous pouvez choisir un autre numéro, mais assurez-vous de prendre note du numéro que vous choisissez - vous en aurez besoin plus tard ! (Choisissez un numéro supérieur à 1024 - cela vous évitera peut-être quelques problèmes.)

La prochaine chose à faire est d'enregistrer un point de terminaison HTTP que Nexmo appellera. Ce point sera hébergé à l'adresse /inbound et sera appelé par Nexmo lorsque quelqu'un appelle votre numéro virtuel Nexmo. Mettez le code suivant dans votre main après l'appel port appel :

post("/inbound", (req, res) -> {
    res.type("application/json");
    return new Ncco(
        TalkAction.builder("Welcome to my Nexmo IVR!").build()
    ).toJson();
});

Lorsque Numbers appelle ce numéro, votre application doit renvoyer une réponse JSON qui ressemble à ceci :

[
  {
    "text": "Welcome to my Nexmo IVR!",
    "action": "talk"
  }
]

Cela indiquera à Nexmo de répondre à l'appel et de lire un message amical. Vous pouvez tester ceci maintenant, en compilant et en exécutant ce qui suit à partir de votre invite de commande :

Spark imprimera quelques messages de log, et lorsqu'il aura terminé, vous pourrez le tester en utilisant la commande curl sur la ligne de commande, comme suit :

La commande curl ci-dessus envoie une requête HTTP POST à votre serveur et imprime la réponse. Si vous n'êtes pas très à l'aise avec la ligne de commande, ou si vous préférez simplement une application visuelle, vous pouvez utiliser Postman pour faire la même chose.

Vous pouvez arrêter le service à tout moment en entrant Ctrl-C. Vous devrez procéder ainsi, puis recompiler et réexécuter chaque fois que vous modifierez votre code source et que vous voudrez tester votre service.

Vous avez maintenant une application qui peut gérer les appels entrants de Nexmo Voice. Il est temps de connecter un numéro de téléphone Nexmo à votre application.

Connectez Nexmo à votre service

Vous souvenez-vous de la Exigences ci-dessus, où je disais qu'il fallait installer Ngrok ? Heureusement, mon collègue Aaron a écrit un excellent guide sur l'utilisation de Ngrok et Nexmo. Vous devriez le lire ! Vous pouvez lancer Ngrok en ouvrant un onglet de console (vous devez le lancer en même temps que votre service Java) et en lançant la commande suivante :

Vous remarquerez dans le résultat qu'il y a deux lignes appelées "Forwarding" ; l'une contient une URL HTTP, et l'autre est HTTPS. Prenez note de l'URL HTTPS - vous en aurez besoin dans une minute. L'autre élément à noter est la ligne "Interface Web". Je vous recommande d'ouvrir cette URL dans votre navigateur dès maintenant - parce que vous êtes sur le point de vérifier que Ngrok est connecté à votre service Java IVR.

En utilisant curl (ou Postman), lancez une requête similaire à celle que vous avez faite ci-dessus, mais cette fois-ci en utilisant l'URL de Ngrok qui vient de vous être donnée, avec l'option /inbound à la fin de celle-ci. La mienne ressemble à ceci :

Vous devriez voir le même résultat que précédemment. Cela signifie que Nexmo sera en mesure d'atteindre votre service (alors que Ngrok et votre service sont toujours en cours d'exécution).

Nous espérons que vous avez un Account Nexmo, et que l'outil Nexmo CLI est installé. Si ce n'est pas le cas, c'est le moment ! Lorsque vous êtes prêt ...

Acheter un Numbers Nexmo

Vous pouvez commencer à louer un numéro Nexmo en lançant la commande suivante nexmo suivante sur votre ligne de commande :

Si vous aimez le numéro qu'il a sélectionné pour vous, tapez "confirmer" et appuyez sur Entrée. Si vous préférez choisir un numéro à partir d'une liste, je vous recommande d'utiliser le tableau de bord Nexmo. Prenez note du numéro.

Créer une application Nexmo Voice

Vous devez maintenant créer une application Nexmo Voice, qui regroupe un ou plusieurs numéros Nexmo avec une certaine configuration webhook. N'oubliez pas de changer le nom d'hôte Ngrok pour celui qui vous a été donné ci-dessus !

La commande ci-dessus met en place une application Nexmo qui sait comment appeler votre service lorsqu'un appel entrant est reçu. Vous avez également sauvegardé la clé privée dans un fichier local private.key. Vous ne l'utiliserez pas dans ce tutoriel, mais elle pourra vous être utile plus tard lorsque vous ajouterez d'autres fonctionnalités à votre service.

Notez votre numéro d'identification de la demande. Vous en aurez besoin ensuite.

Liez votre Numbers Nexmo

En utilisant le numéro de téléphone et l'identifiant de l'application qui vous ont été communiqués ci-dessus, exécutez la commande suivante :

Tester votre service

Maintenant, si vous appelez le numéro de Nexmo depuis votre téléphone portable, Nexmo devrait décrocher et vous devriez entendre le message "Bienvenue dans mon SVI Nexmo", puis l'appel raccrochera.

Si cela ne fonctionne pas, consultez la console Ngrok dans votre navigateur à l'adresse http://localhost:4040/ et assurez-vous que l'appel a été reçu par Ngrok et transmis avec succès au service Java fonctionnant sur votre machine de développement.

En faire un IVR

Votre SVI n'est pas encore très utile ! Je vais vous montrer comment permettre à l'utilisateur d'entrer des données à partir de son clavier (on appelle cela un DTMF, ce qui signifie Dual Tone Modulated Frequency, mais ce n'est pas vraiment important).

Demander des commentaires

Tout d'abord, revenez à l'appel get que vous avez écrit, et ajoutez un second paramètre à l'appel du constructeur Ncco pour qu'il ressemble à ceci :

return new Ncco(
    TalkAction.builder("Welcome to my Nexmo IVR! Please enter a digit.")
            .build(),
    InputAction.builder()
            .maxDigits(1)
            .timeOut(5)
            .eventUrl(pathToUrl(req, "/input"))
            .build()
).toJson();

Cette action d'entrée demande à Nexmo d'attendre 5 secondes que l'utilisateur saisisse un chiffre sur son clavier. Lorsque le chiffre est saisi, Nexmo appelle votre serveur à l'adresse /input avec les détails du code DTMF saisi par l'utilisateur. Vous écrirez le gestionnaire pour /input dans un instant.

J'ai également modifié l'appel à TalkAction, de sorte que nous avons défini bargeIn à true. Cela signifie qu'un auditeur pressé n'a pas besoin d'attendre la fin du message pour saisir le code DTMF.

L'autre point à noter est la méthode pathToUrl utilisée pour générer une URL absolue vers votre service. Il s'agit d'une méthode utilitaire de 10 lignes que j'ai écrite. Collez-la dans votre classe App à partir du sur GitHub. Je n'expliquerai pas son fonctionnement ici, car ce n'est pas vraiment l'objet de ce tutoriel !

Traiter les données

Maintenant que vous avez demandé à Nexmo d'appeler /input lorsque l'utilisateur saisit un code DTMF, vous devez gérer cet appel. Saisissez le code suivant à la fin de votre méthode main méthode :

post("/input", (req, res) -> {
    InputEvent input = InputEvent.fromJson(req.body());

    res.type("application/json");
    String message = "You entered " + input.getDtmf();
    return new Ncco(TalkAction.builder(message).build()).toJson();
});

Le code ci-dessus est très similaire à votre gestionnaire /inbound existant, mais dans ce cas, il analyse le JSON reçu dans un InputEvent dans la requête, et en extrait le code DTMF. Il répond ensuite à l'utilisateur en lui lisant un message lui indiquant le code qu'il a saisi.

Testez votre application en appelant votre numéro Nexmo et en entrant un code sur le clavier lorsqu'on vous le demande !

Conclusion

Il s'agit d'un exemple très simple de réponse à un code DTMF, mais vous pouvez l'adapter à votre application. Vous pourriez par exemple rechercher un enregistrement dans une base de données avec un identifiant saisi par l'utilisateur, ou construire un standard téléphonique pour transmettre un appel à quelqu'un de votre organisation. Les possibilités sont nombreuses !

Pour plus d'informations, consultez notre documentation primée à l'adresse suivante Nexmo Developer.

Si vous construisez un service Spark plus important, je ne vous recommande pas de mettre tout votre code dans une seule méthode main méthode ! Heureusement, l'équipe Spark a écrit un article de blog décrivant les meilleures pratiques pour les grandes Applications.

Si vous avez des commentaires, ou si vous voulez de l'aide pour ce tutoriel, je suis @judy2k sur Twitter - envoyez-moi un DM. Vous pouvez également envoyer un courriel à notre équipe chargée des relations avec les développeurs à l'adresse suivante devrel@nexmo.comou rejoindre la communauté communauté Nexmo Slack.