Partager:
){kind=small}
Ancien rédacteur technique chez Vonage. Aime jouer avec les API et les documenter.
Jouer un fichier audio dans un appel Voice avec Java et Spark
Temps de lecture : 17 minutes
Ce tutoriel vous montre comment diffuser de l'audio dans un appel à l'aide de l'API Voice de Nexmo.
Le cas d'utilisation le plus évident est la diffusion d'une musique d'attente ou de messages. Personne n'apprécie particulièrement d'être mis en attente. Mais vous pouvez rendre cette expérience aussi agréable que possible en donnant à vos interlocuteurs quelque chose à écouter plutôt que le silence. Des études ont montré que le temps semble passer plus vite lorsque les appelants ont quelque chose à écouter et que cela peut également réduire considérablement leur niveau d'anxiété - ce qui est idéal lorsqu'ils appellent votre service clientèle pour se plaindre.
Toutefois, les mêmes études ont également montré que les appelants peuvent réagir négativement s'ils n'aiment pas ce qu'ils sont obligés d'écouter. Choisissez donc votre musique ou votre message avec soin et, quoi que vous fassiez, ne le faites pas. Rick Roll ne les faites pas rouler !
Pour répondre à un appel entrant, vous devez créer un webhook accessible au public et configurer votre Account Nexmo pour l'utiliser. Nous utiliserons Java et le framework web Spark web framework pour créer le webhook. Une fois l'appel en cours, nous utiliserons la bibliothèque client de l'API REST de Bibliothèque client Nexmo REST API pour Java pour diffuser de l'audio en continu. Vous pouvez trouver une version du code de ce tutoriel sur GitHub.
Le JDK ou son équivalent open source OpenJDK. Ce tutoriel a été écrit avec OpenJDK 11, mais la version 8 ou supérieure de l'un ou l'autre devrait convenir.
Gradle (version 3.4 ou ultérieure) pour construire votre projet et gérer ses dépendances.
ngrok pour rendre votre webhook disponible sur l'internet public.
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.
Vous avez besoin d'un numéro virtuel Numbers que vous pouvez utiliser pour recevoir des appels entrants. Vous pouvez en acheter un directement dans le tableau de bord du développeur, mais dans ce tutoriel, vous utiliserez l'outil outil CLI de Nexmo de Nexmo.
Installez le CLI Nexmo :
Ensuite, configurez-le avec vos NEXMO_API_KEY et NEXMO_API_SECRET depuis le tableau de bord du développeur :
Utilisez l'interface de commande Nexmo pour afficher les numéros dotés de la fonction voice qui sont disponibles à l'achat dans votre pays, en remplaçant dans la commande suivante la mention GB dans la commande suivante par votre propre code pays à deux caractères:
Sélectionnez un numéro et achetez-le :
Vous devez rendre votre webhook accessible aux API de Nexmo. Une bonne façon de le faire pendant le développement est d'utiliser ngrok. Pour en savoir plus, lisez notre article de blog sur ngrok.
Téléchargez et installez ngrokpuis exécutez la commande suivante pour exposer votre application sur le port 3000 à l'Internet public :
Notez les URLs publiques que ngrok et laissez-le tourner pendant toute la durée de ce tutoriel (parce que vous devez configurer votre application avec ces URLs et que ngrok vous en donne de nouvelles, aléatoires, à chaque fois que vous l'exécutez, à moins que vous ne souscriviez à un plan payant) :
Terminal showing the ngrok URLs
Créez un répertoire pour votre projet appelé play-audio-into-call, passez dans ce répertoire et utilisez ensuite gradle pour initialiser le projet :
Acceptez tous les paramètres par défaut, puis ouvrez le projet généré dans votre IDE.
Localisez le fichier build.gradle et modifiez le référentiel de dépendances de jcenter() à mavenCentral():
repositories {
mavenCentral()
}Remplacer la section dependencies par le texte suivant :
dependencies {
// Spark framework
implementation 'com.sparkjava:spark-core:2.8.0'
// Nexmo client library
implementation 'com.nexmo:client:4.4.0'
// Use JUnit test framework
testImplementation 'junit:junit:4.12'
}Nous n'utiliserons pas JUnit dans cet exemple, mais vous pouvez le laisser là pour l'instant.
Gradle a créé la classe App dans le répertoire src/main/java/play/audio/into/call dans le répertoire
Ouvrez App.java dans votre IDE. Supprimez la méthode getGreeting() qui a été créée pour vous gradle a créée pour vous et ajoutez la déclaration import nécessaire pour le paquetage spark nécessaire.
Ensuite, appelez la méthode port pour indiquer que votre application écoute les requêtes sur le port 3000.
Votre App.java devrait ressembler à ceci :
package play.audio.into.call;
import static spark.Spark.*;
public class App {
public static void main(String[] args) throws Exception {
port(3000);
System.out.println("I'm listening!");
}
}Lancez votre application en exécutant gradle run dans le répertoire play-audio-into-call dans le répertoire Vérifiez qu'elle fonctionne en visitant http://localhost:3000 dans votre navigateur et en voyant le message "I'm listening" affiché sur la page.
Une Application API Voice est une construction Nexmo et ne doit pas être confondue avec l'application que vous allez écrire. Il s'agit plutôt d'un "conteneur" pour les paramètres d'authentification et de configuration dont vous avez besoin pour travailler avec l'API.
Vous pouvez créer une Application Voice API à l'aide de la CLI Nexmo. Vous devez fournir un nom pour l'application et les URL de deux points de terminaison webhook : le premier est celui auquel les API de Nexmo adresseront une demande lorsque vous recevrez un appel entrant sur votre numéro virtuel et le second est l'endroit où l'API peut poster des données d'événement.
Dans ce tutoriel, nous ne nous intéressons qu'au webhook "answer", vous pouvez donc fournir n'importe quelle URL pour le webhook "event". Remplacez le nom de domaine dans la commande CLI Nexmo suivante par votre nom de domaine ngrok et exécutez-la dans le répertoire racine de votre projet :
Cette commande télécharge un fichier appelé private.key qui contient des informations d'authentification et renvoie un identifiant d'application unique. Notez cet identifiant car vous en aurez besoin dans les étapes suivantes.
Vous devez maintenant relier votre numéro virtuel Nexmo à votre Application Voice API. Exécutez la commande CLI Nexmo suivante, en remplaçant NEXMO_NUMBER par votre numéro virtuel Nexmo (y compris l'indicatif international, mais en omettant les zéros initiaux) et APPLICATION_ID par l'ID de l'application que vous avez généré à l'étape précédente :
La configuration est terminée. Reprenons le codage de votre application.
Lorsque Nexmo reçoit un appel entrant sur votre numéro virtuel, il soumet une GET demande à votre /webhooks/answer point de terminaison. Ce point de terminaison n'existe pas encore, mais vous le créerez bientôt.
Nexmo s'attend à ce que votre webhook fournisse une réponse contenant un Objet de contrôle d'appel Nexmo (NCCO). Il s'agit d'un tableau d'objets au format JSON, chacun d'entre eux décrivant un objet de contrôle d'appel Nexmo (NCCO). action qui indique à Nexmo comment traiter l'appel.
Dans cet exemple, vous lirez un message de bienvenue à l'appelant à l'aide de la synthèse vocale, puis vous le placerez en conférence. Les deux actions NCCO qui permettent d'atteindre cet objectif sont talk et conversationrespectivement. Le NCCO que vous devez inclure dans votre réponse se présente donc comme suit :
[
{
"action": "talk",
"voiceName": "Russell",
"text": "Please wait while we connect you to the conference"
},
{
"action": "conversation",
"name": "Test Conference"
}
]L'action talk action devrait être assez explicite. Tout ce que vous faites, c'est lire la text à l'utilisateur dans la voix Russell Voice. (Vous trouverez une liste complète des voix disponibles ici).
L'action conversation action exige que vous fournissiez un name pour la conférence afin que vous puissiez joindre plusieurs appelants à la même conférence. Dans ce tutoriel, vous serez probablement le seul appelant, mais vous devez tout de même le nommer. Nous utilisons l'action conversation pour maintenir l'appel ouvert afin de pouvoir y diffuser de l'audio ultérieurement.
La bibliothèque client de l'API REST de Nexmo pour Java Nexmo REST API Client Library for Java fournit quelques classes d'aide pour créer ce NCCO, alors configurons-les d'abord.
Incluez l'importation suivante dans votre fichier App.java l'importation suivante :
import com.nexmo.client.NexmoClient;Ensuite, dans votre méthode main juste en dessous de l'appel à port(3000)instanciez la bibliothèque du client, en remplaçant /path/to/your/private.key par le chemin d'accès à votre fichier private.key et APPLICATION_ID par l'identifiant de votre application Voice API :
public class App {
public static void main(String[] args) throws Exception {
port(3000);
NexmoClient client = NexmoClient.builder()
.applicationId("APPLICATION_ID")
.privateKeyPath("/path/to/your/private.key")
.build();
}
}
Il faut donc d'abord créer ce point d'arrivée. La route que vous utiliserez pour cela est /webhooks/answer.
Inclure les déclarations suivantes import les déclarations :
import com.nexmo.client.voice.VoiceName;
import com.nexmo.client.voice.ncco.Ncco;
import com.nexmo.client.voice.ncco.TalkAction;
import com.nexmo.client.voice.ncco.ConversationAction;Et ajoutez ce code à votre main méthode :
get("/webhooks/answer", (req, res) -> {
String callId = req.queryParams("uuid");
System.out.println("Call answered. The UUID for this call is: " + callId);
TalkAction intro = TalkAction.builder("Please wait while we connect you to the conference.")
.voiceName(VoiceName.RUSSELL)
.build();
ConversationAction conversation = ConversationAction.builder("Test conference")
.build();
res.type("application/json");
return new Ncco(intro, conversation).toJson();
});
Ce code utilise les éléments TalkAction et ConversationAction de la bibliothèque du client Nexmo pour construire le NCCO qu'il renvoie ensuite dans la réponse à Nexmo.
Testez-le en vous assurant d'abord que ngrok est en cours d'exécution, puis en exécutant gradle run. Appelez ensuite votre numéro virtuel Nexmo. Votre application affiche l'UUID de l'appel et vous devez entendre le message de bienvenue. La ligne reste ouverte jusqu'à ce que vous la déconnectiez.
Vous devez maintenant trouver un moyen de diffuser de l'audio dans la conférence téléphonique. Pour ce faire, vous allez créer une route appelée /play/:idoù le :id est l'UUID de l'appel dans lequel vous souhaitez diffuser de l'audio. Vous appellerez cette route manuellement une fois la conférence téléphonique en cours.
Ajouter la déclaration suivante import déclaration :
import com.nexmo.client.voice.StreamResponse;La création de l'itinéraire /play/:id dans votre méthode main méthode :
get("/play/:id", (req, res) -> {
String id = req.params(":id");
final String URL = "http://example.com/your/audio/file.mp3";
System.out.println("Playing audio into " + id.toString());
StreamResponse startStreamResponse = client.getVoiceClient().startStream(id, URL, 0);
System.out.println(startStreamResponse.getMessage());
Thread.sleep(5000);
client.getVoiceClient().stopStream(id);
return "";
});
Remplacer URL par l'URL d'un fichier audio de votre choix. Vous pouvez utiliser https://nexmo-community.github.io/ncco-examples/assets/voice_api_audio_streaming.mp3 pour les tests.
Cette route supprime l'UUID de l'appel de l'URL de la requête GET et l'utilise dans la méthode startStream pour identifier l'appel correct vers lequel diffuser l'audio. Elle joue l'audio pendant cinq secondes, puis l'arrête en appelant stopStream. Si vous ne l'arrêtez pas de cette manière, la lecture se poursuivra indéfiniment, comme le précise le troisième paramètre de la méthode startStream qui indique à Nexmo combien de fois jouer l'audio, zéro signifiant infini.
Tout est prêt ! Vous pouvez maintenant le tester.
Exécutez votre application Java à partir du répertoire de votre application :
Appelez votre numéro virtuel, écoutez le message de bienvenue et notez l'UUID de l'appel affiché dans la console.
Dans un navigateur, ou en utilisant Postman ou un outil similaire, créez une GET vers le point de terminaison /play en indiquant l'UUID de l'appel, par exemple :
http://localhost:3000/play/d2af966a2fa415b7080b2762940a828c
Vous devriez entendre un son qui se termine au bout de cinq secondes.
Dans ce tutoriel, vous avez appris à créer une application Java avec le cadre Spark pour répondre à un appel sur votre numéro virtuel Nexmo à l'aide de l'API Voice, créer une conférence et y diffuser de l'audio. Invitez un ami à appeler le numéro en même temps que vous afin que vous puissiez tous deux être placés dans la conférence. Envisagez d'expérimenter avec différents fichiers audio et de créer un point de terminaison distinct afin de pouvoir contrôler le flux audio. /stop/:id afin de pouvoir contrôler manuellement la durée de l'audio.