You are viewing the Spanish (Mexico) site, but your language preference is set to English. Switch to English site →

Menu

Expand
Calificar esta página:

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

Twilio está lanzando una nueva consola. Algunas capturas de pantalla de esta página pueden mostrar la consola heredada y, por lo tanto, es posible que ya no sean precisas. Estamos trabajando para actualizar todas las capturas de pantalla a fin de reflejar la nueva experiencia de la consola. Obtén más información acerca de la nueva consola.

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

Antes de enviar un mensaje de WhatsApp desde tu lenguaje web, deberás registrarte para obtener una cuenta de Twilio o iniciar sesión en su cuenta existente y activar el Sandbox de Twilio para WhatsApp. El Sandbox te permite crear prototipos de WhatsApp de forma inmediata, utilizando un número de teléfono compartido, sin necesidad de esperar a que WhatsApp apruebe un número específico.

Para comenzar, selecciona un número de los números disponibles del sandbox para activar el tuyo.

WA_Sandbox.png

Asegúrate de anotar el número de teléfono que elijas en el sandbox. Lo necesitarás más tarde cuando estemos listos para enviar algunos mensajes.

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

Account Credentials

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.

En este tutorial, se utilizan credenciales codificadas de manera rígida en la parte superior del código; debes seguir las prácticas recomendadas con respecto a la protección de credenciales en producció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).

Si te has unido al Sandbox hace más de 24 horas, deberás enviar un nuevo mensaje de entrada a tu número de WhatsApp para poder enviar un mensaje de medios. Actualmente, WhatsApp no es compatible con los medios en mensajes con “plantilla” que no se envían en una “sesión” de 24 horas.

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:

Loading Code Sample...
        
        

        Envía un mensaje de medios con WhatsApp

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

        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. Revisa cómo mantener tus credenciales de Twilio seguras.

        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.

        Actualmente, el contenido de medios de WhatsApp solo se admite en los mensajes de sesión. Si la sesión de WhatsApp con un usuario caduca, debes esperar a que un mensaje entrante cree una sesión nueva antes de que puedas enviar un mensaje multimedia.

        ¿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.

        Loading Code Sample...
              
              

              Responde a los mensajes entrantes de WhatsApp con medios

              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.

              Protege tus webhooks

              Twilio es compatible con autenticación HTTP básica y Digest. La autenticación te permite proteger tus URL TwiML en tu servidor web con contraseña para que solo tú y Twilio puedan acceder a ellos.

              Obtén más información aquí, y consulta nuestra guía para asegurar tu aplicación Servlet validando las solicitudes de Twilio entrantes.

              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!

              Jose Oliveros Alexis Crespo Alberto Mucarsel
              Calificar esta página:

              ¿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.

              Loading Code Sample...
                    
                    
                    

                    Gracias por tus comentarios.

                    Selecciona los motivos de tus comentarios. La información adicional que nos brindas nos ayuda a mejorar nuestra documentación:

                    Enviando tus comentarios…
                    🎉 Gracias por tus comentarios.
                    Se produjo un error. Inténtalo de nuevo.

                    Gracias por tus comentarios.

                    thanks-feedback-gif