Envía y recibe mensajes de medios con WhatsApp en Java Servlets

En este tutorial, configuraremos una aplicación Java Servlets que utiliza el canal de WhatsApp para lo siguiente:

• Enviar mensajes de medios
• Responder mensajes entrantes con medios

Las muestras de código en este tutorial utilizan la biblioteca auxiliar Java de Twilio, Java y Servlets.

Envía mensajes de medios salientes mediante WhatsApp

Al igual que cuando se envía un MMS, cuando se envía un mensaje de WhatsApp saliente, se utiliza el recurso de mensajes de Twilio. Esta sección te guiará por la configuración y el envío de medios en un mensaje de WhatsApp. Los medios pueden consistir en imágenes, archivos de audio y PDF.

Regístrate (o inicia sesión) a tu cuenta Twilio y activa el Sandbox

Recopilar la información de tu cuenta Twilio

Antes de poder enviar cualquier mensaje, deberás recopilar tus credenciales de cuenta de Twilio. Puedes encontrarlos en la consola de Twilio.

• SID de cuenta: se utiliza para identificarte en solicitudes de API
• Token de autenticación: se utiliza para autenticar solicitudes de API REST

Para todos nuestros fragmentos de código y ejemplos de Java, deberás autenticarte con el SID de cuenta y el token de autenticación.

Envía un mensaje de medios de WhatsApp mediante la API REST

A fin de enviar un mensaje de medios salientes con WhatsApp desde tu cuenta de Twilio, deberás crear un HTTP POST para el recurso de mensajes de Twilio.

Enviar un mensaje de medios con WhatsApp es similar a enviar un mensaje basado en texto con WhatsApp con una adición importante: el parámetro media_url (medio de URL). El parámetro media_url (medio de URL) de este código indica a Twilio dónde recuperar los medios que queremos incluir en el mensaje de WhatsApp. (Puedes evitar el acceso no autorizado a tus medios activando la autenticación básica HTTP para URL de medios en la consola de Twilio).

La biblioteca auxiliar Node de Twilio te ayuda a crear un nuevo caso del recurso de mensajes. Cuando hagas esto, especificarás el to (para), from (desde) y los parámetros mediaUrl (medio de URL) de tu mensaje.

Si aún no tienes instalada la biblioteca auxiliar Java, puedes agregarla a tus dependencias de POM buscando la versión más reciente aquí:

Ahora, crea un archivo con el nombre app.java e incluye el siguiente código:

Reemplaza los valores del marcador de posición para accountSid y authToken con tus valores únicos. Puedes encontrarlos en tu consola de Twilio.

El número de destino debe ser el número de teléfono para la cuenta WhatsApp de destino en formato E.164. Si estás utilizando el Sandbox de WhatsApp, solo puedes enviar mensajes a números que se unieron al Sandbox.

Le dirás a Twilio qué número de teléfono utilizar para enviar este mensaje reemplazando el número from (desde) con el identificador de canal whatsapp: seguido del número de Sandbox en formato E.164.

Guarda el archivo y ejecútalo:

mvn compile exec:java -Dexec.mainClass=com.twilio.app.App

En unos momentos, deberías recibir un mensaje de WhatsApp con una imagen.

Ten en cuenta que WhatsApp no es compatible con incluir un cuerpo de texto en el mismo mensaje que un video, un archivo de audio, un documento, un contacto (vCard) o una ubicación. Si pasas el parámetro Body (Cuerpo) en un mensaje con uno de estos tipos de medios, el cuerpo se ignorará y no se entregará al dispositivo.

Entender la respuesta de Twilio

Cuando envías un mensaje de medios saliente de WhatsApp, Twilio envía datos sobre el mensaje en respuesta a tu solicitud. La respuesta JSON contiene el SID y URI únicos de tu recurso de medios:

"subresource_uris": {"media": "/2010-04 01/Accounts/ACxxxxxxxx/Messages/SMxxxxxxxxxxxxx/Media.json"}

Cuando la API REST de Twilio crea tu nuevo recurso de mensajes, guarda la imagen que se encuentra en el mediaUrl (medio de URL) especificado como un recurso de medios. Una vez creado, puedes acceder a este recurso en cualquier momento mediante la API.

Puedes imprimir este valor desde tu código C# para ver dónde se almacena la imagen. La siguiente línea al final de tu archivo program.cs imprime tu URI de medios recientemente aprovisionados:

System.out.println(message.subresourceUris.get("media");

Responde con los medios en WhatsApp

Para responder mediante los medios a los mensajes entrantes de WhatsApp, deberás proporcionar a Twilio una URL de webhook que apunte a un servidor que ejecute el código para inspeccionar y guardar los archivos de medios.

¿Qué son los webhooks?

Los webhooks son devoluciones de llamadas HTTP definidas por el usuario. Por lo general, son activados por algún evento, como recibir un mensaje SMS o una llamada telefónica entrante. Cuando se produce ese evento, Twilio realiza una solicitud HTTP (en general una POST o una GET) a la URL configurada para el webhook.

Para manejar un webhook, solo necesitas crear una pequeña aplicación web que pueda aceptar las solicitudes HTTP. Casi todos los lenguajes de programación en el lado del servidor ofrecen un marco para que lo hagas. En este tutorial, configuraremos nuestra aplicación web con Servlets.

La funcionalidad del webhook es la misma para cada aplicación de Twilio. En primer lugar, un webhook realiza una solicitud HTTP a una URI que tú le proporcionas a Twilio. Cuando recibes esta solicitud, tu aplicación realiza una lógica predefinida. Esto podría ser algo como leer o escribir en la base de datos o llamar a otra API. Por último, tu aplicación envía una respuesta de TwiML a Twilio en la que especifica las instrucciones que Twilio debe seguir.

¿Qué es TwiML?

TwiML es Twilio Markup Language (lenguaje marcado de Twilio), que se podría decir que es un documento XML con etiquetas especiales definidas por Twilio para ayudarte a crear tus aplicaciones de mensajería y voz.

TwiML es más fácil de mostrar que explicar:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
   <Message>¡Gracias por el mensaje!</Message>
</Response>

Cada documento de TwiML tiene el elemento <Response> (Respuesta), que puede contener uno o más verbos. Los verbos son acciones que te gustaría que Twilio realice, como <Say> (Decir) un saludo a la persona que llama, o enviar un <Message> (Mensaje) de SMS en respuesta a un mensaje entrante. Para obtener una referencia completa sobre todo lo que puedes hacer con TwiML, consulta nuestra referencia de API de TwiML.

Para devolver un medio en la respuesta de WhatsApp, debes incluir el elemento TwiML de medios con la dirección URL del archivo de medios. Se admite un archivo adjunto de medios por mensaje, con un límite de tamaño de 5 MB.

Genera un TwiML en tu aplicación

Para responder a un mensaje entrante de WhatsApp, puedes escribir un TwiML bruto o utilizar una biblioteca auxiliar. Cuando utilizas la biblioteca auxiliar, no tienes que preocuparte por generar el XML bruto tú mismo.

Tienes el código: ahora necesitas una URL que le puedas dar a Twilio.

Twilio solo puede acceder a servidores públicos en Internet. Esto significa que debes llevar tu aplicación web y publicarla a un proveedor de alojamiento web o en la nube (de los cuales hay muchos), puedes alojarla en tu propio servidor o puedes utilizar un servicio como ngrok para exponer tu máquina de desarrollo local a Internet. (Solo recomendamos esta última para fines de desarrollo y pruebas, y no en implementaciones de producción).

Para enviar medios en respuesta a un mensaje entrante de WhatsApp, simplemente agrega una URL de imagen. Si es necesario, reinicia el servidor y, luego vuelve a enviar un mensaje al número de WhatsApp. Deberías recibir un mensaje de WhatsApp que incluya una imagen. Consulta la referencia de la API para obtener más detalles.

Configura la URL de tu webhook

Ahora que tienes una dirección URL para la rutina de generación de respuestas TwiML de tu aplicación web, puedes configurar tu número de teléfono Twilio para llamar a tu URL de webhook cada vez que aparezca un nuevo mensaje de WhatsApp.

Puedes establecer la URL del webhook para los mensajes entrantes en el servidor en el Sandbox.

Asegúrate de elegir el HTTP POST o HTTP GET correspondiente con lo que esperas tu aplicación web. Por lo general, el valor predeterminado de POST está bien.

Examina los medios en los mensajes entrantes de WhatsApp

Ver, guardar o manipular los archivos de medios en los mensajes entrantes de WhatsApp también implica configurar una URL de webhook. La URL apunta a un servidor que genera instrucciones de TwiML, incluidos los medios que deseas enviar.

Obtén detalles del mensaje entrante

Cuando Twilio llama a tu webhook, envía una serie de parámetros sobre el mensaje que acabas de recibir. La mayoría de estos, como el número de teléfono To (Para), el número de teléfono From (Desde) y el Body (Cuerpo) del mensaje, están disponibles como propiedades del parámetro de solicitud para nuestro método de acción.

Envía direcciones URL a los medios

Twilio envía variables de formulario llamadas MediaUrlX, en el que X es un índice basado en cero. Los mensajes de WhatsApp solo contienen un archivo de medios por mensaje entrante, de modo que puedes acceder al archivo en MediaUrl0 en la solicitud entrante desde Twilio a la URL de tu webhook.

Determina el tipo de contenido de los medios

Los archivos adjuntos a los mensajes de WhatsApp pueden ser de muchos tipos de archivos diferentes, como JPG, MP3 y PDF. (Para obtener más información sobre los tipos de archivos compatibles, consulta las preguntas frecuentes). Twilio administra la determinación del tipo de archivo para ti y puedes obtener el tipo MIME estándar desde el parámetro MediaContentTypeX. Si esperas fotos e imágenes, es probable que veas muchos archivos adjuntos con la imagen o JPEG tipo MIME.

Y eso es todo lo que hay que hacer; recibir y responder es exactamente igual a lo que harías en cualquier aplicación de SMS con nuestra API de mensajería. Genial, ¿verdad?

¿Qué sigue?

Todo el código, en un proyecto de trabajo completo, está disponible en GitHub. Para profundizar, dirígete a la referencia de la API de mensajería y obtén más información sobre la solicitud de webhook Twilio y el recurso de medios de API REST. Además, debes tener en cuenta los precios para el almacenamiento de todos los archivos de medios que mantienes en los servidores de Twilio.

¡Nos encantaría escuchar lo que crearás con esto!