Trabajar con mensajes interactivos de WhatsApp
Mensajes interactivos es una función de WhatsApp para empresas. La página Mensajes API de Vonage le permite aprovechar esta función mediante el uso de sus puntos finales de API y webhooks.
Flujo básico de Applications
El flujo básico para trabajar con los mensajes interactivos de WhatsApp es el siguiente:
Enviar un
POSTsolicitud a la/v1/messagesendpoint. El cuerpo de la solicitud debe contener los datos JSON requeridos, con el carácterchannelajustado awhatsappy elmessage_typeajustado acustom. Encustomdebe rellenarse con un formato adecuado objeto personalizado. La estructura real del objeto personalizado variará en función del tipo de mensaje interactivo que se envíe (por ejemplo, botón de respuesta o lista).El tipo de mensaje apropiado se mostrará en el chat de WhatsApp especificado. El cliente puede interactuar con el mensaje, como hacer clic en un botón de respuesta o seleccionar una opción de una lista (según el tipo de mensaje). La API de Messages de Vonage te informará de esta interacción a través de una devolución de llamada con la carga útil del mensaje usando una función preconfigurada de webhook de mensajes entrantes
En función del contenido de la carga útil recibida a través de la devolución de llamada, puede realizar las acciones que considere oportunas, como enviar otra solicitud.
NOTA: El webhook de mensajes entrantes para recibir las retrollamadas debe forme parte de un Aplicación de Vonage
Configuración de su aplicación
Puedes configurar tu aplicación de Vonage de varias maneras, por ejemplo, a través de la función Cuadro de mandosa través de una llamada a la API de Applications o a través de la CLI de Vonage. A continuación describimos la configuración de una aplicación a través del panel.
- Cree una nueva aplicación en Sus aplicaciones (dándole un nombre apropiado, etc.)
- En Capacidades, active Mensajes
- La activación de Mensajes debería exponer campos para webhooks de entrada y de estado. Establezca el webhook de entrada en la URL en la que desea recibir las devoluciones de llamada de los mensajes interactivos de WhatsApp.
- Establezca la versión de Messages API en v1 mediante el menú desplegable
- Haga clic en Generar nueva solicitud
- Una vez generada la solicitud, se abrirá la pestaña "Vincular canales sociales". En esta pestaña podrás vincular tu número de WhatsApp Business
NOTA: Las Applications de Vonage exigen el uso de JWT (JSON Web Tokens) para autenticar las solicitudes a la API, es decir, la autenticación HTTP Basic no es una opción cuando se usa Messages API v1 con webhooks. Más información sobre los JWT.
Mensajes interactivos: Ejemplos
La estructura del objeto JSON variará en función del tipo de mensaje interactivo, y también de un mensaje a otro. No obstante, como norma general, deberá incluir el objeto from y to Numbers, a channel en whatsappy un message_type de custom. A continuación, tendrá que establecer un custom cuyo valor es una objeto personalizado. El objeto personalizado debe tener un type clave de interactivey un interactive cuyo valor es a su vez un objeto.
En interactive define el mensaje interactivo. Debe tener un type en button o listy, por lo general, constará también de cuatro partes principales: header, body, footery action. En action determina los elementos interactivos dentro del mensaje, como botones u opciones de lista.
Botones de respuesta: Ejemplo
A continuación se muestra un ejemplo del cuerpo de una solicitud de envío de un mensaje interactivo de WhatsApp con tres botones de respuesta:
{
"from": "YOUR_WABA_NUMBER",
"to": "USERS_NUMBER",
"channel": "whatsapp",
"message_type": "custom",
"custom": {
"type": "interactive",
"interactive": {
"type": "button",
"header": {
"type": "text",
"text": "Delivery time"
},
"body": {
"text": "Which time would you like us to deliver your order at?"
},
"footer": {
"text": "Please allow 15 mins either side of your chosen time"
},
"action": {
"buttons": [
{
"type": "reply",
"reply": {
"id": "slot-1",
"title": "15:00"
}
},
{
"type": "reply",
"reply": {
"id": "slot-2",
"title": "16:30"
}
},
{
"type": "reply",
"reply": {
"id": "slot-3",
"title": "17:15"
}
}
]
}
}
}
}
El mensaje resultante aparecerá así:
En la interfaz de usuario de WhatsApp, el mensaje cambia de aspecto como si el usuario hubiera respondido a ese mensaje con el texto de uno de los botones. Además, ese botón deja de ser seleccionable, mientras que los demás siguen siendo seleccionables.
Si el usuario selecciona la primera opción, usted recibiría posteriormente algo como esto a través del webhook de entrada:
{
"to": "YOUR_WABA_NUMBER",
"from": "USERS_NUMBER",
"channel": "whatsapp",
"message_uuid": "00000000-0000-0000-0000-000000000000",
"timestamp": "2021-08-10T00:00:00Z",
"message_type": "reply",
"reply": {
"id": "slot-1",
"title": "15:00"
}
}
Listar mensajes: Ejemplo
A continuación se muestra un ejemplo del cuerpo de una solicitud para enviar un mensaje de lista interactiva de WhatsApp con cuatro opciones clasificadas en dos secciones:
{
"from": "YOUR_WABA_NUMBER",
"to": "USERS_NUMBER",
"channel": "whatsapp",
"message_type": "custom",
"custom": {
"type": "interactive",
"interactive": {
"type": "list",
"header": {
"type": "text",
"text": "Select which pill you would like "
},
"body": {
"text": "You will be presented with a list of options"
},
"footer": {
"text": "There are no wrong choices"
},
"action": {
"button": "Select",
"sections": [
{
"title": "Section A - pills",
"rows": [
{
"id": "row1",
"title": "Red",
"description": "Take the red pill"
},
{
"id": "row2",
"title": "Blue",
"description": "Take the blue pill"
},
{
"id": "row3",
"title": "Green",
"description": "Take the green pill"
}
]
},
{
"title": "Section B - no pills",
"rows": [
{
"id": "row4",
"title": "Nothing",
"description": "Do not take a pill"
}
]
}
]
}
}
}
}
El mensaje resultante aparecerá así:
Cuando el usuario pulsa el botón "Seleccionar", se muestran las opciones disponibles. A continuación, el usuario puede seleccionar una opción (como máximo) y pulsar el botón "Enviar".
El aspecto del mensaje cambia como si el usuario hubiera respondido al mensaje con el texto de los campos de título y descripción de la solicitud API.
Si el cliente seleccionó la primera opción de la Sección A, usted recibiría posteriormente algo como esto a través del webhook de entrada:
{
"to": "YOUR_WABA_NUMBER",
"from": "USERS_NUMBER",
"channel": "whatsapp",
"message_uuid": "00000000-0000-0000-0000-000000000000",
"timestamp": "2021-08-10T00:00:00Z",
"message_type": "reply",
"reply": {
"id": "row1",
"title": "Red",
"description": "Take the red pill"
}
}