Compartir:
){kind=small}
Antiguo redactor técnico en Vonage. Le encanta jugar con las API y documentarlas.
Reproducir un archivo de audio en una llamada de voz con Java y Spark
Tiempo de lectura: 16 minutos
Este tutorial le muestra cómo transmitir audio en una llamada utilizando el Nexmo Voice API.
El caso más obvio es reproducir música de espera o mensajes. A nadie le gusta especialmente que le pongan en espera. Pero puede hacer que la experiencia sea lo más agradable posible ofreciendo a sus interlocutores algo que escuchar en lugar de silencio. Los estudios han demostrado que el tiempo parece pasar más rápido cuando las personas que llaman tienen algo que escuchar y también puede reducir sus niveles de ansiedad de manera significativa - ideal cuando están llamando a su departamento de servicio al cliente para quejarse.
Sin embargo, los mismos estudios también han informado de que las personas que llaman pueden reaccionar negativamente si no les gusta lo que se les obliga a escuchar. Así que elige bien la música o el mensaje y, hagas lo que hagas, no Rick Roll de Rick.
Para responder a una llamada entrante, debe crear un webhook de acceso público webhook y configurar su cuenta Nexmo para utilizarlo. Vamos a utilizar Java y el Spark web framework para crear el webhook. Una vez que la llamada está en marcha, vamos a utilizar el Nexmo REST API Client Library para Java para transmitir audio en él. Puedes encontrar una versión del código para este tutorial en GitHub.
El sitio JDK o su equivalente de código abierto OpenJDK. Este tutorial fue escrito usando OpenJDK 11, pero la versión 8 o superior de cualquiera de los dos debería estar bien.
Gradle (versión 3.4 o posterior) para construir tu proyecto y gestionar sus dependencias.
ngrok para que su webhook esté disponible en la Internet pública.
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.
Necesitas un número virtual Nexmo que puedas utilizar para recibir llamadas entrantes. Usted puede comprar uno directamente en el salpicadero desarrollador, pero en este tutorial, se utilizará la Nexmo CLI herramienta en su lugar.
Instale el Nexmo CLI:
A continuación, configúrelo con sus NEXMO_API_KEY y NEXMO_API_SECRET desde el panel del desarrollador:
Utilice la CLI de Nexmo para mostrar los números con voice capacidad que están disponibles para la compra en su país, mediante la sustitución de GB en el siguiente comando por su propio código de país de dos caracteres:
Seleccione un número y cómprelo:
Debes hacer que tu webhook sea accesible a las APIs de Nexmo. Una gran manera de hacer esto durante el desarrollo es utilizar ngrok. Para obtener más información, lea nuestro entrada de blog sobre ngrok.
Descargue e instale ngroky ejecute el siguiente comando para exponer su aplicación en el puerto 3000 a la Internet pública:
Tome nota de las URL públicas que ngrok y déjela ejecutándose mientras dure este tutorial (porque necesita configurar su aplicación con estas URLs y ngrok te da unas nuevas y aleatorias cada vez que la ejecutas a menos que te suscribas a un plan de pago):
Terminal showing the ngrok URLs
Cree un directorio para su proyecto llamado play-audio-into-callcambie a ese directorio y utilice gradle para inicializar el proyecto:
Acepte todos los valores predeterminados y, a continuación, abra el proyecto generado en su IDE.
Localice el archivo build.gradle y cambie el repositorio de dependencias de jcenter() a mavenCentral():
repositories {
mavenCentral()
}Sustituya la dependencies sección por lo siguiente:
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'
}No utilizaremos JUnit en este ejemplo, pero puedes dejarlo ahí por ahora.
Gradle creó la clase App clase en el directorio src/main/java/play/audio/into/call directorio.
Abra App.java en su IDE. Elimine el método getGreeting() método que gradle ha creado para usted y añada la import necesaria para el spark paquete.
Luego, llama al método port para indicar que tu aplicación está a la escucha de peticiones en el puerto 3000.
Su App.java debería tener este aspecto:
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!");
}
}Ejecute su aplicación ejecutando gradle run en el directorio play-audio-into-call directorio. Compruebe que funciona visitando http://localhost:3000 en tu navegador y viendo el mensaje "Estoy escuchando" que aparece en la página.
Una Aplicación Voice API es una construcción de Nexmo y no debe confundirse con la aplicación que vas a escribir. En su lugar, es un "contenedor" para los ajustes de autenticación y configuración que necesitas para trabajar con la API.
Puedes crear una Voice API Application con la CLI de Nexmo. Debe proporcionar un nombre para la aplicación y las URL de dos puntos finales de webhook: el primero es al que las API de Nexmo harán una solicitud cuando reciba una llamada entrante en su número virtual y el segundo es donde la API puede publicar datos de eventos.
En este tutorial sólo estamos interesados en el webhook "answer", así que puedes proporcionar cualquier URL para el webhook "event". Reemplace el nombre de dominio en el siguiente comando Nexmo CLI con su ngrok y ejecútalo en el directorio raíz de tu proyecto:
Este comando descarga un archivo llamado private.key que contiene información de autenticación y devuelve un ID de aplicación único. Anote este ID porque lo necesitará en los pasos siguientes.
Ahora tiene que vincular su número virtual Nexmo a su Voice API Application. Ejecute el siguiente comando CLI Nexmo, sustituyendo NEXMO_NUMBER por tu número virtual Nexmo (incluyendo el código de marcación internacional, pero omitiendo los ceros a la izquierda) y APPLICATION_ID con el ID de aplicación que generaste en el paso anterior:
Esa es toda la configuración hecha. Volvamos a la codificación de su aplicación.
Cuando Nexmo reciba una llamada entrante en su número virtual, enviará una GET solicitud a su /webhooks/answer punto final. Ese endpoint aún no existe, pero lo creará en breve.
Nexmo espera que su webhook proporcione una respuesta que contenga un Objeto de Control de Llamada Nexmo (NCCO). Este es un array de objetos en formato JSON, cada uno de los cuales describe un action que indica a Nexmo cómo gestionar la llamada.
En este ejemplo, leerá un mensaje de bienvenida a la persona que llama utilizando la función de texto a voz y, a continuación, la pondrá en conferencia. Las dos acciones NCCO que lo consiguen son talk y conversationrespectivamente. Así que la NCCO que necesitas incluir en tu respuesta tendrá este aspecto:
[
{
"action": "talk",
"voiceName": "Russell",
"text": "Please wait while we connect you to the conference"
},
{
"action": "conversation",
"name": "Test Conference"
}
]El sitio talk acción debería explicarse por sí misma. Todo lo que estás haciendo es leer la cadena text al usuario en la voz Russell Voice. (Puede encontrar una lista completa de las voces disponibles aquí).
El sitio conversation acción requiere que proporcione un name para la conferencia, de modo que pueda unir a varios participantes en la misma conferencia. En este tutorial es probable que usted sea la única persona que llame, pero aún así es necesario que le ponga un nombre. Estamos utilizando la acción conversation para mantener la llamada abierta y poder transmitir audio más tarde.
La Nexmo REST API Client Library para Java proporciona algunas clases de ayuda para crear esta OCN, así que vamos a configurar eso primero.
Incluya la siguiente importación en su App.java archivo:
import com.nexmo.client.NexmoClient;A continuación, en su método main justo debajo de la llamada a port(3000)instancie la biblioteca cliente, sustituyendo /path/to/your/private.key por la ruta a su archivo private.key y APPLICATION_ID por el ID de tu aplicación 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();
}
}
Así que primero necesitas crear ese endpoint. La ruta que usarás para esto es /webhooks/answer.
Incluya las siguientes import declaraciones:
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;Y añada este código a su main método:
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();
});
Este código utiliza las etiquetas TalkAction y ConversationAction para construir la OCNC que luego devuelve en la respuesta a Nexmo.
Pruébelo asegurándose primero de que ngrok se esté ejecutando y, a continuación, ejecute gradle run. A continuación, llame a su número virtual Nexmo. Su aplicación mostrará el UUID de la llamada y debería escuchar el mensaje de bienvenida. La línea permanecerá abierta hasta que se desconecte.
Ahora necesitas una forma de reproducir audio en la multiconferencia. Para ello, creará una ruta llamada /play/:iddonde :id es el UUID de la llamada a la que desea transmitir audio. Llamarás a esta ruta manualmente una vez que la multiconferencia esté en marcha.
Añada la siguiente import declaración:
import com.nexmo.client.voice.StreamResponse;El crear la /play/:id ruta en su main método:
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 "";
});
Sustituya URL por la URL de un archivo de audio de su elección. Puede utilizar https://nexmo-community.github.io/ncco-examples/assets/voice_api_audio_streaming.mp3 para las pruebas.
Esta ruta elimina el UUID de llamada de la GET y lo utiliza en el método startStream para identificar la llamada correcta a la que transmitir el audio. Reproduce el audio durante cinco segundos y luego deja de reproducirlo llamando a stopStream. Si no lo detuvieras de esta manera, continuaría reproduciéndose indefinidamente como se especifica en el tercer parámetro de startStream que indica a Nexmo cuántas veces debe reproducir el audio, siendo cero infinito.
Ya está todo listo. Ahora puedes probarlo.
Ejecute su aplicación Java desde el directorio de aplicaciones:
Llame a su número virtual, escuche el mensaje de bienvenida y tome nota del UUID de llamada que aparece en la consola.
En un navegador, o utilizando Postman o una herramienta similar, cree una GET solicitud al /play pasando el UUID de la llamada, por ejemplo:
http://localhost:3000/play/d2af966a2fa415b7080b2762940a828c
Deberías escuchar algo de audio que termina después de cinco segundos.
En este tutorial, has aprendido a crear una aplicación Java con el framework Spark para responder a una llamada en tu número virtual Nexmo utilizando la Voice API, crear una conferencia y luego transmitir audio en ella. Invite a un amigo a llamar al número al mismo tiempo que usted para que ambos puedan ser colocados en la conferencia. Experimenta con distintos archivos de audio y crea un punto final /stop/:id para poder controlar manualmente la duración del audio.