Conversación proactiva usando WhatsApp Business API¶
/v2/message/hsm/
- POST
Permite iniciar una conversación con un cliente de manera proactiva utilizando un HSM.
Acerca de los HSM
Un HSM (Highly Structured Message) es una plantilla de mensajes de WhatsApp para enviar mensajes o notificaciones a los clientes.
Para poder enviar un HSM, este debe estar previamente aprobado por Facebook.
La persona que recibirá el mensaje debe haber aceptado que la contacten por Whatsapp (Opt-in). Desk no se encarga de realizar este procedimiento.
HSM disponibles
Este servicio es para enviar HSM previamente cargados en Desk.
Debido a ciertas restricciones en la verificación de HSM aprobados la carga de estos se realiza de forma manual. Para cargar una nueva plantilla debe notificar al Equipo de Soporte o a su Ejecutivo Comercial de Desk, indicando nombre, texto, idioma y el namespace (si corresponde).
Ejemplo de body para crear la conversación, en formato JSON
:
1 2 3 4 5 6 | { "account": "56900000000", "phone": "56911111111", "name": "template_name", "parameters": ["Carlos Soto", "orden 12345", "01/01/2020"] } |
Donde los parámetros son:
Campo | Descripción | Tipo |
---|---|---|
account | Número de la cuenta WhatsApp Business | string |
phone | Número de WhatsApp del cliente | string |
name | Nombre identificador (element_name ) del HSM a enviar |
string |
parameters | Lista de parámetros para completar el template | string[] |
Parámetros
El campo parameters
debe incluir la cantidad exacta de argumentos necesarios para completar la plantilla especificada, además cada uno de ellos debe ser no vacío.
No cumplir con esto puede causar que el mensaje no se envíe al cliente aun cuando el servicio responda con un código 200
, debido a validaciones internas en WhatsApp rechazando el mensaje a pesar que haya dejado enviarlo.
La respuesta esperada tendrá la siguiente forma en caso de éxito:
1 2 3 4 5 | { "status": 200, "message_id": "7a72e330d4cb11e9be4c", "ticket_id": "583dcb2855d0a46e438d0206" } |
Campo | Descripción | Tipo |
---|---|---|
status | Código de retorno de la petición. 200 si la petición fue exitosa |
integer |
message_id | Identificador del mensaje | string |
ticket_id | Identificador del ticket | string |
msg | Mensaje informativo en caso de error | string |
En caso de que se intente enviar un mensaje con menos parámetros que los requeridos por el HSM, la respuesta será la siguiente:
1 2 3 4 | { "status": 400, "msg": "Missing parameters for selected HSM" } |
Otros códigos de error comúnes son:
Código | Descripción | Solución |
---|---|---|
400 |
Campo incompleto o faltante | Comprueba que el body del request tenga todos los campos requeridos y el número de la cuenta esté correctamente ingresado |
401 |
No autenticado | Comprueba que el header del request esté con los datos correctos |
404 |
HSM no registrado | Si el HSM está aprobado, recuerda notificar a Desk que ha sido aprobado con los detalles de este para que sea agregado |
500 |
Error interno | Contacta al Equipo de Soporte para ayuda adicional, recuerda incluir el body del request que genera problemas |