Con el avance de la tecnología, notificar a la gente se ha convertido en un proceso de un solo paso. Atrás quedaron los días en los que la gente se apuntaba las citas y acontecimientos importantes en un calendario junto al teléfono y hacía falta llamarles el día de antes para confirmar que se acordaban. Ahora disponemos de un método más eficaz, eficiente y fiable de notificar a la gente: la mensajería. Si Raúl tiene una cita programada para las 18:00 del miércoles, podemos enviarle una confirmación un día antes, seguida de un recordatorio una hora antes de la cita real. Raúl tiene una agenda muy apretada, así que avisándole, sabrá que se le espera para esa cita en concreto.
Este tutorial cubrirá:
- Cómo enviar un mensaje utilizando metadatos y programar un mensaje.
- Cómo comprobar el estado de un mensaje.
- Cómo comprobar las respuestas a los mensajes.
- Cómo comprobar los informes de entrega.
- Cómo confirmar la recepción de una respuesta y el informe de entrega una vez que se ha procesado.
- Cómo implementar webhooks.
Si en algún momento te atascas en alguna sección, puedes consultar el código de este repositorio para que te ayude.
Requisitos previos
Para trabajar en este tutorial, necesitas:
Instalación del SDK de mensajes en Ruby
Para esta parte necesitarás un editor de código como Sublime Text o Atom. Utilizaremos Ruby para desarrollar nuestra aplicación, así que tendrás que asegurarte de que también lo has instalado en tu máquina. Ahora crea una carpeta vacía para tu proyecto, llamémosla "testApp". Después, abre tu símbolo del sistema, accede al directorio y ejecuta el siguiente comando para instalar el SDK de mensajes:
gem install messagemedia_messages_sdk
Envar un mensaje
Crea un archivo app.rb dentro de esa carpeta y ábrelo en tu editor. Escribe el código siguiente. Está comentado, para que puedas entender lo que ocurre en cada línea.
require 'message_media_messages.rb' # Esta gema contiene toda la lógica necesaria para interaccionar con la API de mensajes de Sinch Engage
require 'pp' # Esta gema es para que el JSON se muestre "bonito"
def setup
# Estas son las credenciales de API necesarias para acceder a la API de mensajes
auth_user_name = 'CLAVE_DE_API'
auth_password = 'CLAVE_SECRETA_API'
use_hmac = false # Cambia este valor a true si utilizas claves HMAC
# Instanciar el cliente
client = MessageMediaMessages::MessageMediaMessagesClient.new(
auth_user_name: auth_user_name,
auth_password: auth_password,
use_hmac: use_hmac
)
return client
end
def send_message
client = setup();
# Crear la estructura del mensaje
messages = client.messages
body_value = '{
"messages":[
{
"content":"Hola, Raúl. Tienes una cita con la Dra. Gárate hoy a las 18:00. Responde Y para confirmar o N para cancelar.",
"destination_number":"NUMERO_MOVIL",
"metadata": {
"name": "Ibrahim"
},
"scheduled": "2018-04-30T11:49:02.807Z",
"delivery_report": "true"
}
]
}';
# Analizar el cuerpo del mensaje y convertirlo en un objeto de Ruby
body = JSON.parse(body_value);
# Por último, enviar el mensaje
result = messages.create_send_messages(body)
# Y mostrar la respuesta en la consola
pp result
end
# Llamar a la función send_message
send_message
Hemos programado el mensaje para que se envíe un día antes de la cita de Raúl y también hemos incluido algunos metadatos en el cuerpo del mensaje. Los metadatos pueden utilizarse cuando no quieras almacenar datos persistentes en la aplicación. En un mensaje se pueden especificar hasta 10 pares de datos de metadatos clave/valor. Antes de enviar el mensaje, añade tus credenciales de API y el número de Raúl, que es +34 666123456. ¡Y todo listo para empezar!
Este es el aspecto que debe tener un cuerpo de respuesta con éxito.
Cómo comprobar el estado de un mensaje.
El mensaje enviado está en cola (comprueba el estado de la captura de pantalla anterior). No sabes cuándo o si el mensaje se envió realmente a partir de la respuesta inicial de la API. Podemos averiguarlo comprobando el estado del mensaje mediante el ID del mensaje que se encuentra en el objeto respuesta.
Vamos a añadir algo de código para comprobar el estado del último mensaje que hemos enviado.
def check_status
client = setup()
messages = client.messages
message_id = 'TU_ID_DE_MENSAJE'
result = messages.get_message_status(message_id)
print result.inspect
end
# Llamar a la función check_status
check_status
No olvides sustituir el marcador de posición messageID por un ID de mensaje real. En este caso, era fbbe1ae6-8ad7-441d-bc4c-551880911e2b. Y esta es la respuesta que recibí:
La estructura de respuesta es muy similar a la de send_message. Puedes ver en la respuesta que el mensaje está actualmente programado para ser entregado. No queremos que Raúl falte a su cita y, para asegurarnos de que no lo hace, le enviaremos otro recordatorio en la próxima sección, donde veremos cómo comprobar si hay respuestas.
Cómo comprobar las respuestas
Las respuestas enviadas desde un teléfono móvil aparecerán cuando llamemos a la función de respuestas, así que vamos a intentar enviar un mensaje a Raúl desde nuestro teléfono móvil.
Ahora vamos a añadir algo de código para comprobar si hay respuestas.
def check_replies
client = setup()
replies = client.replies
result = replies.get_check_replies()
print result.inspect
end
# Llamar a la función check_replies
check_replies
Cada petición al punto de conexión de check_replies devolverá las respuestas recibidas que aún no hayan sido confirmadas mediante otro punto de conexión similar a replies llamado confirm replies. Una respuesta del punto de conexión de check_replies tendrá la estructura que se muestra a continuación.
Comprobar los informes de entrega
Los informes de entrega son una notificación del cambio de estado de un mensaje a medida que se procesa.
Cada petición al punto de conexión check_delivery_reports devolverá todos los informes de entrega recibidos que aún no se hayan confirmado mediante el punto de conexión confirm_delivery_reports.
Ahora vamos a añadir algo de código para comprobar los informes de entrega.
def check_delivery_reports
client = setup()
deliveryReports = client.delivery_reports
result = deliveryReports.get_check_delivery_reports()
pp result
end
# Llamar a la función check_delivery_reports
check_delivery_reports
Una respuesta del punto de conexión de check_delivery_reports tendrá la siguiente estructura.
Confirmación de respuestas e informes de entrega
El punto de conexión de confirm_replies está pensado para ser utilizado junto con el punto de conexión de check_replies y permitir un procesamiento sólido de los mensajes de respuesta. Una vez que se han procesado uno o más mensajes de respuesta, se pueden confirmar utilizando el punto final de confirm_replies, de modo que ya no se devuelven en posteriores peticiones de check_replies. El punto de conexión de confirm_delivery_reports funciona exactamente igual, pero con el punto de conexión de check_delivery_reports.
El punto de conexión de confirm_replies toma una lista de identificadores de respuesta como sigue:
{
"reply_ids": [
"011dcead-6988-4ad6-a1c7-6b6c68ea628d",
"3487b3fa-6586-4979-a233-2d1b095c7718",
"ba28e94b-c83d-4759-98e7-ff9c7edb87a1"
]
}
Y el punto de conexión de confirm_delivery_reports toma una lista de identificadores de informes de entrega como sigue:
{
"delivery_report_ids": [
"011dcead-6988-4ad6-a1c7-6b6c68ea628d",
"3487b3fa-6586-4979-a233-2d1b095c7718",
"ba28e94b-c83d-4759-98e7-ff9c7edb87a1"
]
}
Es probable que sondees el punto de conexión de check_replies o check_delivery_reports para obtener resultados. Como puedes suponer, esto puede volverse muy tedioso muy rápidamente. ¿Por qué? Tendrás que sondear el punto de conexión por cada solicitud send_message que hagas, así que para 1000 mensajes enviados serán 1000 solicitudes a cada punto de conexión. No es recomendable procesar las respuestas o los informes por separado. En su lugar, puedes utilizar webhooks. Un webhook es básicamente una URL y si una aplicación web implementa ese webhook, entonces se pueden enviar mensajes a esa URL cuando ocurran ciertas cosas.
Utilizando webhooks, puedes recibir automáticamente cambios en el estado del mensaje, respuestas recibidas en respuesta al mensaje o informes de entrega recibidos para el mensaje.
Webhooks
Para activar los webhooks, simplemente especifica un parámetro callback_url en el cuerpo del mensaje de tu función send_message.
"messages":[
{
"content":"Esto es un recordatorio de la cita que tienes hoy.",
"destination_number":"+34666123456",
"metadata": {
"name": "Ibrahim"
},
"delivery_report": "true",
"callback_url": "https://my.callback.url.com"
}
]
Personalmente, me gusta probar las devoluciones de llamada en una página web llamada Webhook Tester. Esta página web te permite probar fácilmente webhooks y otros tipos de peticiones HTTP. Registra instantáneamente cualquier solicitud enviada a esa URL y lo mejor es que ni siquiera tienes que actualizar.
Intentemos enviar un mensaje utilizando una callback_url desde Webhook Tester. Para obtener una URL de devolución de llamada, visita Webhook Tester y luego copia la URL única que debería generarse para ti en la página de destino.
Modifiquemos el cuerpo de nuestro mensaje para añadir soporte para la callback_url. Este es el aspecto que debe tener el cuerpo de tu mensaje. He añadido mi callback_url.
"messages":[
{
"content":"Esto es un recordatorio de la cita que tienes hoy.",
"destination_number":"+34666123456",
"metadata": {
"name": "Ibrahim"
},
"delivery_report": "true",
"callback_url": "https://webhook.site/d49c3883-c1fd-4cf5-8977-52a4ea57ddc2"
}
]
Unos segundos después de llamar a la función send_message, deberías ver algo similar a esto en la pantalla de tu Webhook Tester.
En la parte izquierda de la pantalla, encontrarás varias solicitudes. Estos son tus informes de entrega y cada uno tendrá un estado diferente. Esto ilustra cómo cambia el estado del mensaje a medida que pasa del remitente a nuestra pasarela, al operador y, finalmente, al receptor. Para obtener una vista "más bonita" del objeto respuesta, marca la casilla "Formato JSON" en la parte superior de la pantalla, justo debajo de la barra de navegación.
Aquí tienes un fragmento de uno de mis informes de entrega:
Conclusión
Raúl va camino de su cita. Dice que se habría olvidado si no fuera por ti. No solo te has asegurado de que Raúl acuda a su cita, sino que también has aprendido mucho por el camino. Bien hecho.
Obtén el código
Todo el código de este tutorial está disponible en el repositorio de Github del tutorial de mensajería de Ruby.
Recursos