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:
- Registrarte en Twilio y obtener tu primer número de teléfono de Twilio con voz habilitada
- Configurar tu entorno de desarrollo para realizar y recibir llamadas telefónicas
- Hacer tu primera llamada telefónica con Twilio
- 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
Si ya tienes una cuenta de Twilio y un número de teléfono de Twilio con voz habilitada, ¡ya tienes todo listo! No dudes en avanzar al paso siguiente.
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
¿Ya tienes tu entorno de desarrollo de Java y una biblioteca auxiliar de Twilio para Java configurados en la ruta de clases? Puedes omitir las siguientes dos secciones y pasar directo a hacer tu primera llamada telefónica con Twilio.
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.
Esta biblioteca auxiliar de Twilio para Java no está pensada para su uso en aplicaciones Android. Utiliza esta biblioteca para servidores, aplicaciones de línea de comandos y proyectos similares. Enviar el Account SID (SID de cuenta) y el Auth Token (Token de autenticación) de Twilio a los usuarios finales conlleva un riesgo de seguridad para tu cuenta de Twilio.
Si deseas realizar o recibir llamadas telefónicas desde una aplicación móvil (Android o iOS), debes utilizar el SDK de voz programable de Twilio. Revisa esta página para obtener instrucciones sobre cómo empezar.
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.
Ten en cuenta lo siguiente: está bien codificar de forma fija tus credenciales cuando comiences, pero debes utilizar variables de entorno para mantenerlas en secreto antes de implementarlas en producción. Para obtener más información, revisa cómo establecer variables de entorno.
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:
javac -cp twilio-8.0.0-jar-with-dependencies.jar MakePhoneCall.java
Necesitamos incluir este archivo JAR de Twilio con las dependencias para compilar nuestra clase desde la línea de comandos. Si utilizas un entorno de desarrollo integrado (IDE), como IntelliJ IDEA, NetBeans o Eclipse, puedes simplemente añadir ese archivo JAR de Twilio a tu ruta de clases o a las bibliotecas de tus proyectos como cualquier otra dependencia. También puedes usar una herramienta de compilación como Maven o Gradle para desarrollar y ejecutar tu aplicación de Java; simplemente especifica la biblioteca auxiliar de Twilio como dependencia.
Una vez que hayas creado la clase en Java, necesitarás ejecutarla. Si la ejecutas desde la línea de comandos en MacOS o Linux, el comando tendrá el siguiente aspecto:
java -cp .:twilio-8.0.0-jar-with-dependencies.jar MakePhoneCall
En Windows, el comando equivalente se ve así:
java -cp .;twilio-8.0.0-jar-with-dependencies.jar MakePhoneCall
La diferencia es que, en Windows, el separador de ruta de clases en Java en la línea de comandos es un punto y coma, y en MacOS o Linux son dos puntos.
¡Eso es todo! En unos momentos, deberías recibir una llamada de tu número de Twilio en tu teléfono.
Si utilizas una cuenta de prueba de Twilio, las llamadas telefónicas salientes se limitarán a los números de teléfono que hayas verificado con Twilio. Los números de teléfono se pueden comprobar a través de los ID de agente de llamada verificados de la consola de Twilio.
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.
Una vez que hayas agregado el código, puedes hacer clic con el botón derecho del mouse en la clase VoiceApp del esquema del proyecto de la parte izquierda y, a continuación, elegir el elemento de menú Run 'VoiceApp.main()' (Ejecutar VoiceApp.main).
El servidor de aplicaciones web Spark de Java comenzará a escuchar en el puerto 4567.
Intenta ir a "http://localhost:4567/hello" para verificar que el servidor esté funcionando; deberías ver "Hello Web" (Hola Web) en el navegador web.
Una cosa importante que debes tener en cuenta: si realizas un cambio en el código y deseas volver a ejecutar el servidor, tendrás que detener la aplicación que se está ejecutando con el botón rojo de detención. Solo una aplicación puede utilizar el puerto 4567 a la vez, por lo que si ejecutas la aplicación de Java mientras aún se está ejecutando una versión anterior, la nueva aplicación se cerrará inmediatamente.
Tendrás que hacer que tu aplicación sea accesible a través de Internet. Aunque puedes hacerlo de muchas formas, te recomendamos una herramienta que proporciona una URL con acceso externo llamada ngrok. Te mostraremos cómo configurarla para que tu app pueda recibir llamadas telefónicas.
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.
El siguiente comando usaría ngrok para exponer el "puerto 4567" a la Internet pública. Escribe el siguiente comando en la línea de comandos:
ngrok http 4567
Y verás un resultado similar a este:
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!
¿Necesitas ayuda?
Todos la necesitamos a veces; la programación es difícil. Obtén ayuda ahora de nuestro equipo de soporte, o recurre a la sabiduría de la multitud visitando Stack Overflow Collective de Twilio o navegando por la etiqueta de Twilio en Stack Overflow.