Envía y recibe mensajes de medios con WhatsApp en PHP
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 PHP Laravel 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 PHP de Twilio y Laravel Lumen.
¿Deseas echar un vistazo a esta aplicación de PHP en su totalidad? Puedes clonar nuestro repositorio de muestras en GitHub en tu máquina y seguir los pasos de README.md para hacerlo funcionar.
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.
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
Para todos nuestros fragmentos de código y ejemplos PHP, 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 en PHP 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 PHP 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 PHP, puedes instalarla mediante Composer:
composer requiere twilio o sdk
Si no estás utilizando composer
, puedes encontrar instrucciones de instalación manual aquí.
Ahora, crea un archivo con el nombre send_whatsapp_media.php
e incluye el siguiente código:
Reemplaza los valores del marcador de posición para $sid
y $token
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 (whatsapp:
) debe ser el número de teléfono de la cuenta WhatsApp de destino en el 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 desde la línea de comandos:
php send_whatsapp_media.php
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.
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. Laravel es un marco de desarrollo web popular en PHP. En este tutorial, configuraremos nuestra aplicación web con Lumen, que es el micromarco de Laravel.
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.
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 Luden mediante la validación de las solicitudes entrantes de Twilio.
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!
¿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.