Voice Enabling a Text-only Chatbot (en anglais)

Vue d'ensemble

Découvrez ici comment ajouter une interaction vocale à votre chatbot textuel existant.

Cette application utilise l'API Voice de Vonage pour la reconnaissance vocale et la synthèse vocale afin de permettre à votre chatbot d'écouter les demandes vocales des appelants et de lire les réponses.

Plus de quarante locales linguistiques sont prises en charge pour activer vocalement votre chatbot.

Ce didacticiel contient deux exemples de code d'application Voice API et une simple application de chatbot textuel ; la première application Voice API se connectera au service de l'application de chatbot simple qui simule des demandes/réponses dont le seul but est d'illustrer comment un chatbot réel peut être activé par la voix, et le deuxième exemple d'application Voice API a les mêmes capacités vocales de base que le premier, vous mettrez à jour cette application pour l'intégrer à votre chatbot réel pour les demandes/réponses en utilisant le premier comme référence.

Le code des deux applications Voice API prend en charge les appels vocaux entrants ou sortants des/vers les utilisateurs, selon les besoins de votre cas d'utilisation du chatbot.

Dans ce tutoriel, nous utiliserons et ferons référence au dépôt GitHub de Dépôt GitHub des applications de l'API Voice et le dépôt GitHub simulateur de chatbot simple dépôt GitHub.

Conditions préalables

Vous aurez besoin de :

• Node.js,

• Ngrok,

• un compte API Vonage,

• Optionnellement Heroku pour un déploiement hébergé.

La configuration de chaque élément prérequis est détaillée comme suit.

Installation de Node.js

• Installez nvm (Node Version Manager) ; si vous utilisez le système d'exploitation Windows, lisez ces notes importantes

• Installez la version 16 de Node.js avec la commande : nvm install 16

• Utilisez la version 16 de Node.js avec la commande : nvm use 16

  • Nous avons testé les Applications avec la version 16.15.1 de Node.js.

Installation de Ngrok

Pour commencer rapidement les tests, vous pouvez exécuter l'application Voice API et l'application simple de simulateur de chatbot sur votre ordinateur local ; cependant, elles doivent être accessibles depuis Internet pour utiliser l'API Voice de Vonage, par exemple, pour recevoir des appels webhook pour des événements tels que des appels vocaux entrants, des appels pris, des transcriptions de reconnaissance vocale. Pour ce faire, vous devez installer le service de tunneling Internet ngrok.

Chaque application aura besoin de son propre tunnel ngrok.

Pour configurer ngrok :

• Installer ngrok,

• Assurez-vous que vous utilisez la dernière version de ngrok et non pas une version de ngrok déjà installée,

• S'inscrire à un compte Account,

• Verify votre adresse e-mail à partir de l'e-mail envoyé par ngrok,

• Récupérer votre Authoken,

• Exécutez la commande ngrok config add-authtoken <your-authtoken>

• Mise en place des deux tunnels

• • Exécuter ngrok config edit

  • • Pour un Account ngrok libre, ajoutez les lignes suivantes au fichier de configuration de ngrok (sous la ligne authoken) :

tunnels:
  	six:
  		proto: http
  		addr: 6000
  	eight:
  		proto: http
  		addr: 8000

• Pour un Account ngrok payantvous pouvez définir des noms d'hôtes ngrok qui ne changeront jamais à chaque nouveau lancement de ngrok ; ajoutez les lignes suivantes au fichier de configuration de ngrok (sous la ligne authoken) - définissez les noms d'hôtes (ils doivent être uniques) aux valeurs réelles souhaitées :

  tunnels:
    	six:
    		proto: http
    		addr: 6000
    		hostname: youmustsetanamehere6.ngrok.io
    	eight:
    		proto: http
    		addr: 8000
    		hostname: youmustsetanamehere8.ngrok.io

  Copie

Remarque : l'application Voice API sera exécutée sur le port local 8000, et l'application de chatbot simple sera exécutée sur le port local 6000.

• Démarrer les deux tunnels ngrok

• • Exécuter ngrok start six eight

  • Vous verrez des lignes comme... Interface Web http://127.0.0.1:4040 Transfert https://xxxxxxx.ngrok.io -> http://localhost:6000 Renvoi https://yyyyyyy.ngrok.io -> http://localhost:8000

  • Notez xxxxxxx.ngrok.io (sans le https://), celui qui est associé au port local 6000, car il sera défini en tant que BOT_SERVER dans les étapes suivantes,

  • Prenez note de https://yyyyyyy.ngrok.io (avec le https://), celui qui est associé au port local 8000, car il sera nécessaire dans les étapes suivantes.

Compte API Vonage

Connectez-vous à votre ou inscrivez-vous à un compte Vonage API Account.

Aller à Vos Applications, accéder à une application existante ou + Créer une nouvelle application.

Dans la section Capacités (cliquez sur [Modifier] si vous ne voyez pas cette section) :

Activer Voice

• Sous Answer URL, laissez HTTP GET, et entrez https://<host>:<port>/answer (remplacez <host> et <port> par le nom d'hôte public et, si nécessaire, le port public du serveur sur lequel l'exemple d'application Voice API est exécuté), par exemple https://yyyyyyyy.ngrok.io/answer ou https://myappname.herokuapp.com/answer (voir les sections suivantes) ou https://myserver2.mycompany.com:40000/answer (déploiement sur vos propres serveurs)

• Sous URL de l'événement, sélectionnez HTTP POST (au lieu de HTTP GET), et entrez https://<host>:<port>/event (remplacez <host> et <port> par le nom d'hôte public et, si nécessaire, le port public du serveur sur lequel l'exemple d'application Voice API est exécuté), par exemple https://yyyyyyyy.ngrok.io/eventou https://myappname.herokuapp.com/event voir les sections suivantes(voir les sections suivantes) ou https://myserver2.mycompany.com:40000/event (déploiement sur vos propres serveurs)

• Cliquez sur [Generate public and private key] si vous n'avez pas encore créé de clés publiques et privées ou si vous souhaitez en créer de nouvelles, puis enregistrez le fichier sous .private.key (notez le point qui précède le nom du fichier) dans le dossier qui contiendra l'application Voice API. IMPORTANT : N'oubliez pas de cliquer sur [Enregistrer les modifications] en bas de l'écran si vous avez créé un nouveau jeu de clés.

• Associez un numéro de téléphone à cette application si aucun n'a encore été associé à l'application.

Veuillez prendre note de votre numéro d'identification de l'application et du numéro de téléphone associé (car ils sont nécessaires dans la section suivante).

Pour les étapes suivantes, vous aurez besoin de

• Votre clé Clé API Vonage (comme API_KEY)

• Le secret de l'API de Vonage Secret de l'API de Vonageet non un secret de signature (comme API_SECRET)

• Votre numéro d'identification de l'application (comme APP_ID),

• Le numéro de téléphone lié à votre Applications (comme SERVICE_NUMBER), votre téléphone appellera ce numéro,

• Le nom d'hôte public et le port du serveur du chatbot simple en mode texte (en tant que BOT_SERVER), l'argument n'a pas de préfixe http:// ou https://, pas de / à la fin, et pas de sous-chemin, par exemple xxxxxxx.ngrok.io ou mysimplebotname.herokuapp.com ou myserver1.mycompany.com:32000

Configuration de Heroku

Après avoir testé localement, vous pouvez, si vous le souhaitez, déployer votre application dans des environnements hébergés par Heroku.

Pour configurer Heroku,

Installer git.

S'inscrire à un compte Heroku Account.

Installer la ligne de commande ligne de commande Heroku et connectez-vous à votre Account Heroku.

Pour déployer les applications, suivez les instructions de la section Déployer sur Heroku.

Développement

Voyons comment fonctionnent les Applications.

Première phase

Dans la première phase, nous allons utiliser et déployer l'application de référence voice-on-text-bot-app-with-simple-bot.js à partir du référentiel Voice Enabling Text Bot Application repository (Référentiel d'applications de robots textuels à commande vocale)en conjonction avec l'application de chatbot simple very-simple-bot.js du dépôt Voice-Enabling Text Bot Simple Chatbot (en anglais).

Déploiement local sur votre ordinateur pour les deux Applications

Voice enabling text-only chatbot. Local deployment for tests

Téléchargez le code de l'application de référence à partir du référentiel dans un dossier local, puis allez dans ce dossier.

Copiez le fichier env.example dans un nouveau fichier appelé .env (avec un point en tête) : cp env.example .env

Modifiez le fichier .env et définissez les valeurs des cinq paramètres (voir les sections précédentes) :

API_KEY=

API_SECRET=

APP_ID=

BOT_SERVER=

SERVICE_NUMBER=

Installer les dépendances une seule fois :

npm install

Assurez-vous que ngrok a été démarré avec les deux tunnels comme expliqué dans les sections précédentes.

Lancer l'application :

node voice-on-text-bot-app-with-simple-bot.js

Téléchargez le code de l'application de chatbot simple depuis le référentiel dans un dossier local, puis allez dans ce dossier.

Lancer l'application :

node very-simple-bot.js

Pour interagir via des appels vocaux avec le bot très simple, appelez le numéro de téléphone lié à votre application, celui qui est listé comme SERVICE_NUMBER.

Déployer sur Heroku

En option, vous pouvez déployer les deux applications dans des environnements hébergés par Heroku.

Assurez-vous d'abord que vos Applications fonctionnent comme prévu avec un déploiement local sur votre ordinateur et que vous avez configuré Heroku dans les prérequis.

Allez dans le dossier où se trouve l'application Voice API,

Si vous n'avez pas encore de dépôt git local, créez-en un :

git init

git add .

git commit -am "initial"

Commencez par créer cette application sur Heroku à partir de la ligne de commande en utilisant la CLI Heroku : Note : Dans la commande suivante, remplacez "myappname" par un nom unique sur l'ensemble de la plateforme Heroku.

heroku create myappname

ou heroku create myappname --team <xxxxx> (si votre Account Heroku utilise des équipes)

Sur votre tableau de bord Heroku où la page de votre application est affichée, cliquez sur le bouton Applications, ajoutez les Config Vars suivantes et définissez-les avec leurs valeurs respectives :

API_KEY

API_SECRET

APP_ID

BOT_SERVER (see further below)

SERVICE_NUMBER

PRIVATE_KEY_FILE with the value ./.private.key

Maintenant, déployez l'application :

git push heroku master

Sur votre tableau de bord Heroku, où s'affiche la page de votre application, cliquez sur le bouton Ouvrir l'application. Ce nom d'hôte est celui qui doit être utilisé pour votre application API vocale correspondante. Capacités de l'application Vonage Voice API (cliquez sur l'application correspondante, puis sur [Modifier]).

Par exemple, les liens respectifs seraient (remplacer mon nom d'application par la valeur réelle) :

https://myappname.herokuapp.com/answer

https://myappname.herokuapp.com/event

Voir plus de détails dans la section ci-dessus Vonage API Account.

Allez dans le dossier où vous avez l'application chatbot très simple,

Si vous n'avez pas encore de dépôt git local, créez-en un :

aller dans le dossier de cette simple application bot

git init

git add .

git commit -am "initial"

Créez cette application sur Heroku à partir de la ligne de commande en utilisant le CLI Heroku :

Note : Dans la commande suivante, remplacez "mysimplebotname" par un nom unique sur l'ensemble de la plateforme Heroku.

heroku create mysimplebotname

ou heroku create mysimplebotname --team <xxxxx> (si votre Account Heroku utilise des équipes)

Déployer l'application

git push heroku master

Dans ce cas, lors de la configuration de l'application Voice API, le paramètre BOT_SERVER pour l'autre déploiement Heroku sera mysimplebotname.herokuapp.com (remplacez mysimplebotname par sa valeur réelle, il n'y a pas de https:// ni de / à la fin).

Pour interagir via des appels vocaux avec le bot très simple, appelez le numéro de téléphone lié à votre application, celui qui est répertorié comme SERVICE_NUMBER.

Fonctionnement des Applications

L'application voice-on-text-bot-app-with-simple-bot.js :

• Utilise l'API Voice de Vonage avec le SDK de serveur Node.js '@vonage/server-sdk',

• Valeurs prédéfinies pour le :

  • le code de langue ASR (reconnaissance automatique de la parole) et TTS (synthèse vocale), en tant que "languageCode",

  • Message d'accueil initial, sous la forme "greetingText",

  • et d'autres paramètres tels que commentés.

• Gère les itinéraires des webhooks :

  • '/makecall'

    • Si vous souhaitez initier des appels sortants

    • Mettre à jour le numéro dans l'objet callInfo. Il doit s'agir du numéro international complet (format E.164), avec l'indicatif du pays, sans "+" initial, sans préfixe de numérotation international tel que "011" ou "00", sans tiret "-" ni espace.

    • Il appellera la route "/placecall".

      • Pour initier l'appel sortant, dans un navigateur web, entrez l'adresse web : <this-application-host-name>/placecall, par exemple xxxxxxx.ngrok.io/makecall

• '/placecall'

  • C'est ici que la demande d'API pour un appel vocal sortant est effectuée.

• '/réponse'

  • Cette route webhook est appelée par la plateforme Voice API de Vonage lors d'un appel vocal entrant, ou lorsqu'un appel vocal sortant est pris,

  • Le segment d'appel (Voice API) est identifié par sa valeur UUID,

  • L'application renvoie un NCCO où :

    • Un message d'accueil est diffusé à l'interlocuteur distant avec "action" : "talk",

    • Il démarre un cycle ASR (Automatic Speech Recognition) avec "action" : "input",

La plateforme Voice API appellera l'URL du webhook comme spécifié dans le paramètre eventUrl (route /asr), que la parole ait été détectée ou non.

• '/événement

  • Cette route webhook est appelée par la plateforme Voice API de Vonage sur différents états du segment d'appel vocal avec une valeur UUID donnée,

  • Dans cette application, il n'y a aucune action en réponse à cette route de webhook à part le renvoi du code HTTP 200 (ok).

• '/asr'

  • Cette route webhook est appelée par la plateforme Vonage Voice API sur les résultats ASR (Automatic Speech Recognition) pour savoir si une transcription a été renvoyée avec succès ou non, par exemple s'il y a eu des bruits au lieu de mots prononcés ou si le délai a été dépassé si aucun son n'a été détecté (la durée du délai correspond à la valeur du paramètre startTimeout valeur du paramètre)

  • Il démarre un nouveau cycle ASR en renvoyant un NCCO avec "action" : "input"

• '/botreply'

  • Cette route webhook est appelée par le chatbot simple pour renvoyer une réponse textuelle à partir d'une requête textuelle,

  • Il lance ensuite un TTS (Text-to-Speech) pour lire la réponse du chatbot.

• Dans cette application, définissez la langue ASR (Reconnaissance Automatique de la Parole) et TTS (Text-To-Speech) (paramètre languageCode). (paramètre languageCode) qui correspondent à la langue de votre chatbot textuel. Plus de 40 langues locales sont disponibles avec Voice API de Vonage pour ASR et TTS.

• Les deux dernières lignes de code permettent à cette application Node.js d'écouter sur le port local 8000 pour un déploiement local ou sur un port local différent pour un déploiement hébergé (automatiquement défini avec un déploiement Heroku).

L'application very-simple-bot.js :

• Simule un chatbot textuel. Son seul but est de montrer comment un véritable chatbot en texte seul pourrait être activé vocalement avec l'application qui utilise l'API Voice de Vonage,

• Cet exemple de chatbot très simple prend en charge les langues anglaise et française.

• Les seules demandes prises en charge sont énumérées dans les dictionnaires botKbEn et botKbFr,

• Ce chatbot très simple ne fait pas de traitement du langage naturel pour les tests. Vous devez formuler exactement l'une des demandes supportées attendues. Sinon, la réponse sera celle par défaut pour les demandes inconnues,

• Il gère le webhook "/bot" pour recevoir les demandes ; il rappellera l'URL du webhook indiquée dans la demande entrante pour fournir le texte de réponse correspondant,

• Les deux dernières lignes de code permettent à cette application Node.js d'écouter sur le port local 6000 pour un déploiement local ou sur un port local différent pour un déploiement hébergé (automatiquement défini avec un déploiement Heroku).

Deuxième phase

Voice Enabling text-only chatbot. Hosted/ Production deployment.

Dans la deuxième phase, vous allez mettre à jour (là où c'est indiqué à l'intérieur) le code source voice-on-text-bot-app-generic.js pour interagir avec votre chatbot réel pour les demandes/réponses de texte et utiliser voice-on-text-bot-app-with-simple-bot.js comme référence, tous les deux à partir du dépôt d'application référentiel d'applications.

Vous n'aurez besoin d'aucun code provenant du dépôt simulateur de robot simple.

Vous interagirez par la voix avec votre chatbot en appelant le numéro de téléphone lié à votre application, celui répertorié sous la forme... SERVICE_NUMBER.

Conclusion

Dans ce tutoriel, vous avez appris qu'en utilisant l'API Voice de Vonage, vous pouvez activer vocalement n'importe quel chatbot en mode texte, et que de nombreuses langues sont prises en charge.

Vous commencez d'abord par un déploiement local sur votre ordinateur avec l'application Voice API et le chatbot textuel simple pour illustrer comment vous pouvez activer vocalement un chatbot textuel.

Vous pouvez éventuellement déployer dans des environnements hébergés par Heroku.

Ensuite, vous mettrez à jour l'autre application Voice API pour ajouter uniquement le code spécifique à intégrer à votre chatbot textuel pour les demandes/réponses textuelles, car toutes les interactions nécessaires avec Vonage Voice API, y compris la gestion des appels vocaux entrants/sortants, la reconnaissance vocale automatique et la synthèse vocale, ont déjà été mises en œuvre dans ce fichier de code source.

Qu'avez-vous pensé de ce tutoriel ? Vous avez des questions ou des commentaires sur l'activation par Voice d'un chatbot en mode texte ? Rejoignez-nous sur le Slack des développeurs de Vonage. Et suivez-nous sur Twitter pour rester au courant des dernières mises à jour de Vonage Developer