Inicio rápido de voz programable para Java

¿Listo para empezar a enviar y recibir llamadas telefónicas con voz programable de Twilio en Java?

Este inicio rápido de voz programable para Java te enseñará a hacerlo con la biblioteca auxiliar de Twilio para Java para nuestra API REST.

En este inicio rápido, aprenderás lo siguiente:

1. Registrarte en Twilio y obtener tu primer número de teléfono de Twilio con voz habilitada
2. Configurar tu entorno de desarrollo para realizar y recibir llamadas telefónicas
3. Hacer tu primera llamada telefónica con Twilio
4. Recibir y responder una llamada telefónica entrante que lee un mensaje para el agente de llamada mediante la conversión de texto a voz

¿Prefieres ver un video para comenzar? Mira nuestro video de inicio rápido de Voice para Java en YouTube.

Regístrate en Twilio y obtén un número de teléfono de Twilio

Antes de poder hacer una llamada telefónica desde Java, deberás registrarte para obtener una cuenta de Twilio o ingresar a tu cuenta existente y comprar un número de teléfono con capacidad de voz.

Si actualmente no posees un número de teléfono de Twilio con la funcionalidad de voz, deberás comprar uno. Después de ir a la página Buy a Number (Comprar un número), marca la casilla "Voice" (Voz) y haz clic en "Search" (Buscar).

A continuación, verás una lista de los números de teléfono disponibles y sus capacidades. Busca el número que más te guste y haz clic en "Buy" (Comprar) para añadirlo a tu cuenta.

Ahora que tienes una cuenta de Twilio y un número de teléfono programable, puedes empezar a escribir código. Para facilitar aún más las cosas, configuraremos nuestro entorno de Java y, luego, descargaremos la biblioteca auxiliar oficial de Twilio para aplicaciones de Java.

Configura tu entorno de Java

Para realizar tu primera llamada telefónica, deberás tener instalado Java Development Kit (JDK)Edición estándar (SE). Si no sabes si tienes instalado el JDK, ejecuta el siguiente comando para ver qué versión posees:

javac -version

Deberías ver algo similar a este resultado:

javac 1.8.0_92

El SDK de Twilio requiere Java SE 8 o una versión superior, que aparecerá como número de versión "1.8" o superior cuando ejecutes el comando anterior.

Si tienes una versión anterior de Java o no tienes el JDK, deberás instalar el JDK antes de continuar. Sigue las instrucciones de instalación de Java SE Development Kit para tu plataforma (Windows, Mac, Linux) desde la página de descarga de Java SE.

Descarga la biblioteca auxiliar de Twilio para Java independiente

¿Tienes Java configurado y listo para su uso? ¡Fantástico!

A continuación, descarga la biblioteca auxiliar de Twilio para Java independiente. Con esta biblioteca, tendrás clases en Java que te permitirán llamar a la API de Twilio mediante Java, junto con todas las otras dependencias que necesitarás para comenzar. Cuando descargues el archivo JAR, también descarga el que tenga un nombre similar a twilio-8.x-jar-with-dependencies.jar.

¿Prefieres usar Maven, Gradle u otra herramienta de compilación?

Con Maven, coloca esto dentro de la etiqueta de <dependencias> en el archivo pom.xml:

<dependency>
  <groupId>com.twilio.sdk</groupId>
  <artifactId>twilio</artifactId>
  <version>8.0.0</version>
</dependency>

Con Gradle, pega la siguiente línea dentro del bloque de dependencias del archivo build.gradle:

compile group: "com.twilio.sdk", name: "twilio", version: "8.0.+"

Si utilizas un IDE Java para desarrollar la aplicación, puedes especificar el ID de grupo, el ID de artefacto y el número de versión de las dependencias.

Independientemente del administrador de paquetes que utilices, recuerda especificar la última versión de la biblioteca auxiliar. Busca el número de la última versión en la página de la biblioteca auxiliar de Twilio para Java.

Realiza una llamada telefónica con Java

Ahora que terminamos de configurar el JDK y descargamos la biblioteca auxiliar de Twilio para Java, podemos hacer una llamada telefónica desde el número de teléfono de Twilio que acabamos de comprar mediante una sola solicitud de API. Crea y abre un nuevo archivo llamado MakePhoneCall.java y escribe o pega este ejemplo de código.

Tendrás que editar este archivo un poco más antes de que funcione la llamada telefónica:

Reemplaza los valores de los marcadores de posición de credenciales

Cambia los valores de los marcadores de posición ACCOUNT_SID y AUTH_TOKEN por tus credenciales personales de Twilio. Ve a https://www.twilio.com/console e inicia sesión. En esta página, encontrarás tu Account SID (SID de cuenta) y Auth Token (Token de autenticación) únicos, que necesitarás cada vez que hagas llamadas telefónicas con la biblioteca auxiliar de Twilio para Java. Para revelar tu token de autenticación, puedes hacer clic en el ícono de globo ocular:

Abre MakePhoneCall.java y reemplaza los valores de ACCOUNT_SID y AUTH_TOKEN con tus valores únicos.

Sustituye el número de teléfono "from"

¿Recuerdas el número de teléfono con voz habilitada que compraste hace solo unos minutos? Sustituye el número from (de) existente por ese número, y asegúrate de utilizar el formato E.164:

[+][código de país][número de teléfono con el código de área]

Sustituye el número de teléfono "to"

Reemplaza el número de teléfono to (a) por tu número de teléfono. Podría ser cualquier número de teléfono, pero es buena idea probar con el tuyo para que veas cómo funciona el proceso. Como se indicó anteriormente, debes utilizar el formato E.164 en este valor.

Guarda los cambios y compila esta clase en Java desde el terminal:

Recibe y responde llamadas telefónicas entrantes

Cuando tu número de Twilio reciba una llamada telefónica entrante, Twilio enviará una solicitud de HTTP a un servidor que controles. Este mecanismo de devolución de llamada se conoce como webhook. Cuando Twilio envía una solicitud a tu aplicación, espera una respuesta en el formato XML en TwiML que le indica cómo responder al mensaje.

Veamos cómo desarrollaríamos esto en Java con el uso del marco de aplicaciones web Spark. Spark es un marco ligero de aplicaciones web completamente diferente del software de macrodatos llamado Apache Spark.

Spark requiere su propia biblioteca, independiente de la biblioteca auxiliar de Twilio para Java, la cual puedes instalar siguiendo las instrucciones de la página de descarga de Java de Spark. Encontrarás instrucciones para usar Spark con Maven o Gradle, o como descarga independiente. Spark no viene con una implementación de registro, pero funciona con el Simple Logging Facade 4 Java (SLF4J), que también puedes incluir en la ruta de clases en Java.

Por supuesto, puedes configurar todas tus dependencias en la línea de comandos como lo hicimos en la sección anterior cuando realizamos una llamada telefónica a través de Twilio, pero es un poco más fácil configurar todo con el uso de un entorno de desarrollo integrado (IDE) de Java. Vamos a utilizar la edición Community gratuita de IntelliJ IDEA, que puedes descargar de JetBrains. Puedes descargar archivos JAR y utilizarlos directamente con IntelliJ IDEA, o puedes emplear un gestor de dependencias como Maven o Gradle. Usaremos Gradle con IntelliJ IDEA para desarrollar nuestra aplicación.

Creación de una aplicación web con IntelliJ IDEA y Gradle

Si no has descargado e instalado IntelliJ IDEA Community Edition, continúa y hazlo ahora. Después de ejecutar IDEA por primera vez, verás una pantalla similar a esta:

Selecciona "Create New Project" (Crear nuevo proyecto) y se iniciará el nuevo asistente New Project (Nuevo proyecto):

En el lado izquierdo de este cuadro de diálogo, elige Gradle (en lugar de Java), de manera que IntelliJ IDEA configure el proyecto para que utilice Gradle en la gestión de dependencias. En su lugar, también podrías optar por usar Maven aquí; el proceso es casi el mismo.

Después de elegir Gradle, verifica que IntelliJ IDEA tenga un SDK de proyecto (necesitarás Java 8 o superior, así que la versión 1.8 o una posterior) y, a continuación, haz clic en Next (Siguiente).

En la siguiente pantalla del asistente, se te pedirá un group id (ID de grupo), un artifact id (ID de artefacto) y un version number (número de versión). En el ID de grupo, puedes utilizar un nombre de dominio al revés, como com.yourcompany.voice, y en el ID de artefacto, debes utilizar el nombre de tu proyecto, como voice-quickstart-app. Puedes dejar la versión como 1.0-SNAPSHOT. Después de rellenar estos campos, haz clic en Next (Siguiente).

En esta pantalla de configuración de Gradle, puedes dejar los valores predeterminados y, luego, hacer clic en Next (Siguiente).

Por último, puedes confirmar el nombre del proyecto y el directorio del proyecto que se utilizarán para la aplicación web de inicio rápido. Los valores por defecto probablemente también estén bien aquí. Si haces clic en Finish (Finalizar), accederás a tu nuevo proyecto de IntelliJ. Si acabas de instalar IntelliJ IDEA, el IDE descargará Gradle y llevará a cabo la configuración e instalación.

Ahora que ya tenemos todo nuestro proyecto configurado, solo quedan unos pasos más. Necesitaremos la biblioteca auxiliar de Twilio para Java y el marco de la aplicación web de Java Spark como dependencias, junto con la implementación de registro, para que podamos ver los mensajes de estado de Spark. Con Gradle, podemos agregarlos al archivo build.gradle que IntelliJ creó para nosotros. Busca el archivo build.gradle en la barra lateral, y haz clic en él para abrirlo.

Agrega dependencias al archivo build.gradle

Deberás agregar tres líneas al archivo build.gradle, en el grupo de dependencias:

compile group: "com.twilio.sdk", name: "twilio", version: "8.0.+"
compile group: "com.sparkjava", name: "spark-core", version: "2.7.1"
compile group: "org.slf4j", name: "slf4j-simple", version: "1.7.21"

Con estas tres dependencias, Gradle descargará las bibliotecas correspondientes para ti y las agregará a la ruta de clases a fin de desarrollar y ejecutar tu aplicación de Java.

Ahora que ya estamos listos con todo esto, es hora de escribir código.

Responde una llamada telefónica entrante

Tendremos que empezar por crear una clase en Java en nuestro proyecto. En IntelliJ IDEA, selecciona la carpeta java en src y main. A continuación, abre el menú File (Archivo) en la parte superior de la pantalla. Elige el submenú New (Nuevo) y, a continuación, Java Class (Clase en Java).

Aparecerá una pequeña ventana emergente y podrás crear una nueva clase. Asigna el nombre VoiceApp a la clase; el uso de mayúsculas es importante porque tiene que coincidir con el ejemplo de código.

Ahora deberías tener un archivo de código fuente VoiceApp.java. Copia y pega el código del ejemplo de código en este archivo de código fuente.

Este código de Java escuchará las solicitudes HTTP GET entrantes a "/hello" (hola) y responderá con "Hello Web" (Hola Web), y escuchará las solicitudes HTTP POST entrantes de "/" y responderá con marcado de TwiML.

Permite que Twilio hable con tu aplicación de Java mediante ngrok

Acabamos de crear una pequeña aplicación web de Java para recibir llamadas telefónicas entrantes. Antes de que funcione, necesitamos asegurarnos de que Twilio pueda llegar a nuestra aplicación.

La mayoría de los servicios de Twilio utilizan webhooks para comunicarse con tu aplicación. Cuando Twilio recibe una llamada telefónica entrante, por ejemplo, llega a una URL en tu aplicación para obtener instrucciones sobre cómo gestionar el mensaje.

Cuando trabajas en tu aplicación web de Java en el entorno de desarrollo, la app solo es accesible a través de otros programas de tu computadora, por lo que Twilio no podrá hablar con ella. Para resolver este problema, debemos hacer que la aplicación sea accesible a través de Internet.

Aunque hay muchas maneras de hacerlo, como implementar la aplicación en Heroku o AWS, probablemente querrás una forma menos laboriosa de probar tu app de Twilio. Para hacer que la app esté disponible en Internet de manera ligera, te recomendamos una herramienta llamada ngrok. ngrok escucha en el mismo puerto en el que se ejecuta tu servidor web local y proporciona una URL única en el dominio ngrok.io, lo que reenvía las solicitudes entrantes al entorno de desarrollo local. Funciona así:

Si aún no lo has hecho, instala ngrok. Asegúrate de que la versión de ngrok sea la adecuada según tu sistema operativo y de que el comando "ngrok" se encuentre en la ruta del sistema. Si trabajas con Mac o Linux, ya tienes todo listo. Si usas Windows, sigue nuestra guía sobre cómo instalar y configurar ngrok en Windows. Para obtener más información sobre ngrok, incluidos algunos consejos y trucos excelentes, revisa esta publicación detallada del blog.

Ahora tenemos una nueva URL externa.

Configura la URL de tu webhook

Ahora, debes tomar esa URL pública y configurarla como webhook para uno de tus números de teléfono en la consola. Vuelve a la consola, selecciona tu número de teléfono, cambia "A CALL COMES IN" (Entra una llamada) a Webhook y, a continuación, introduce la URL externa a tu servicio, como "https://069a61b7.ngrok.io/", tal como se muestra anteriormente.

Guarda los cambios. ¡Ya tienes todo listo!

Prueba tu aplicación

Asegúrate de ejecutar tanto el comando "ngrok" en la línea de comandos como la aplicación web desde IntelliJ IDEA. Si reiniciaste ngrok, tendrás que actualizar el webhook en la consola para utilizar la URL correcta.

Con ambos servidores en ejecución, estamos listos para la parte divertida: probar nuestra nueva aplicación web de Java.

Llama al número de teléfono de Twilio que configuraste con este webhook. Deberías ver una solicitud de HTTP POST con un 200 OK en la consola de ngrok. La aplicación web de Java responderá a Twilio con tu respuesta en TwiML, y escucharás que se lee tu mensaje.

¿Dónde ir a continuación?

Ahora ya conoces los conceptos básicos de realizar y responder llamadas telefónicas con Java.

Esta app solo utilizó el verbo <Say> (Decir) en TwiML para leer un mensaje al agente de llamada mediante la conversión de texto a voz. Con diferentes términos en TwiML, puedes crear otras construcciones y flujos de llamada eficaces. Prueba algunos, como <Record> (Grabar), <Gather> (Recopilar) y <Conference> (Conferencia).

Consulta estas páginas para obtener más información:

• Consulta la documentación de referencia de la API de voz programable
• Documentos de referencia de TwiML
• Tutoriales con aplicaciones de muestra completas en Java
• Cómo marcar y contestar llamadas telefónicas con Spark y Java 8 en IntelliJ

¡Disfrute este truco!