Saltar a contenido

Conversación proactiva usando WhatsApp Business API

/v2/message/hsm/ - POST

Probar servicio

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