Mensajes [Desarrolladores]
Actualizado 1 year ago
Por
Valentina
Mensajes
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). Adereso no se encarga de realizar este procedimiento.
Este servicio es para enviar HSM previamente cargados en Adereso. 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 Adereso, indicando nombre, texto, idioma y el namespace (si corresponde).
Supongamos que nuestro HSM contiene el siguiente mensaje:
Estimado {1}, su orden número {2} se espera que llegue el día {3}Ejemplos
Un ejemplo de body para enviar un HSM y crear una conversación, en formato JSON:
{
"account": "56900000000",
"phone": "56911111111",
"name": "template_name",
"parameters": ["Carlos", "12345", "01/01/2020"]
}Al teléfono del cliente, llegará el mensaje:
Estimado Carlos, su orden número 12345 se espera que llegue el día 01/01/2020
Donde los parámetros son:
Campo | Descripción | Tipo |
account | Número de la cuenta WhatsApp Business |
|
phone | Número de WhatsApp del cliente |
|
name | Nombre identificador ( |
|
parameters | Lista de parámetros para completar el template |
|
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:
{
"status": 200,
"message_id": "7a72e330d4cb11e9be4c",
"ticket_id": "583dcb2855d0a46e438d0206"
}Campo | Descripción | Tipo |
status | Código de retorno de la petición. |
|
message_id | Identificador del mensaje |
|
ticket_id | Identificador del ticket |
|
msg | Mensaje informativo en caso de error |
|
En caso de que se intente enviar un mensaje con menos parámetros que los requeridos por el HSM, la respuesta será la siguiente:
{
"status": 400,
"msg": "Missing parameters for selected HSM"
}Otros códigos de error comúnes son:
Código | Descripción | Solución |
| 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 |
| No autenticado | Comprueba que el header del request esté con los datos correctos |
| HSM no registrado | Si el HSM está aprobado, recuerda notificar a Adereso que ha sido aprobado con los detalles de este para que sea agregado |
| Error interno | Contacta al Equipo de Soporte para ayuda adicional, recuerda incluir el body del request que genera problemas |
Usando swagger
Desde nuestro sitio api-cluster.postcenter.io podrás hacerlo de la siguiente manera
Usando Postman
Te mostramos un ejemplo de cómo hacerlo
Conversación proactiva en WhatsApp
/v2/message/create_conversation/ - POST
Permite iniciar una conversación con un cliente de manera proactiva.
Definir cuentas proactivas
No todos los números de WhatsApp conectados en Adereso tendrán permitido el envío proactivo de mensajes. Para un mejor manejo, usted debe definir desde la aplicación qué cuentas se utilizarán para envío de mensajes proactivo y cuáles no. Se recomienda que las cuentas proactivas se consideren desechables. Usted además puede monitorear cuántos envíos proactivos ha realizado cada cuenta por mes y cuándo se acerca a un límite peligroso. En este caso recomendamos habilitar más números proactivos y dividir la carga.
Para ver esta configuración, debe tener permiso de administrador y luego ir a Administración / Canales tab Whatsapp, en la cuenta a configura hacer click en Configuración luego Opciones de Whatsapp y luego Activar mensajes proactivos
Ejemplo de body para crear la conversación, en formato JSON:
{
"phone": "56912349876",
"user_name": "Carlos Soto",
"account_id": "au2geg72gs",
"message": "Hola Carlos, bienvenido a nuestra tienda"
}Donde los parámetros son:
Campo | Descripción | Tipo |
phone | Número de Whatsapp del cliente |
|
user_name | Nombre del cliente, utilizado para crear su perfil en Adereso |
|
account_id | Identificador del la cuenta de WhatsApp a utilizar |
|
message | El texto a enviar |
|
no_manual_reopen | Fuerza a que el ticket una vez cerrado, no se pueda reabrir |
|
no_manual_merge | Fuerza a que el ticket no se pueda fusionar con otro |
|
Limitar las acciones a realizar sobre un ticket generado por su sistema
En ocasiones ciertas acciones de agentes pueden complejizar el flujo de una integración, que requiere que un ticket mantenga su estado o no pueda ser eliminado.
En Adereso un agente puede unir dos tickets. Cuando se realiza esta acción, se unifica en uno de los dos tickets, toda la información de ambos, incluyendo mensajes, comentarios o clasificaciones del ticket. El otro se elimina. Este puede ser un comportamiento no deseable en algunos casos de negocio, por lo que existe el parámetro no_manual_merge, que impide que el ticket creado pueda ser fusionado y en consecuencia potencialmente eliminado.
Así mismo, un agente puede abrir o cerrar un ticket múltiples veces. En ocasiones esto puede provocar que el ticket tenga un estado no deseado de cara a una integración. Para garantizar que un ticket una vez cerrado, siempre se mantendrá así, usted puede utilizar el parámetro no_manual_reopen, que impedirá a los agentes re-abrir el ticket, garantizando su estado.
En el caso de que necesitemos que el ticket creado no pueda ser fusionado o re-abierto, existen los campos no_manual_merge y no_manual_reopen. Lo anterior es relevante si el flujo que queremos implementar con los tickets de Adereso requiere mantener ciertas condiciones.
La respuesta esperada tendrá la siguiente forma en caso de éxito:
{
"status": 200,
"ticket_id": "583dcb2855d0a46e438d0206"
}Campo | Descripción | Tipo |
status | Código de retorno de la petición. |
|
ticket_id | Identificador de ticket |
|
En caso de que se intente enviar un mensaje utilizando una cuenta que no tiene permitido enviar mensajes proactivos, la respuesta será la siguiente:
{
"status": 202,
"msg": "This account doesnot allow proactive messaging. Please configure at least one account to be allowed to send proactive messages in Admin / Channels / Whatsapp select account and then Configurations > Enable Proactive Messaging"
}Publicar mensajes dentro de un ticket
/v2/message/ - POST
El servicio de Publicar Mensajes permite responder un mensaje a un cliente dentro de un determinado ticket de atención. Si no se provee un client_id, el mensaje se enviará al primer cliente que participe en el ticket y se responderá al último mensaje del ticket.
Por defecto, solo se pueden responder mensajes privados, por lo que Adereso buscará el primer mensaje privado que encuentre y responderá a ese.
Si requiere enviar mensajes públicos, lo puede hacer enviando el parámetro private_only en false. De esta forma, si se encuentra un mensaje público primero, se respondera a ese mensaje.
Si Adereso no encuentra mensajes privados del cliente y no se usa el flag private_only o se establece en true usted obtendrá el código de error 403 - FORBDDEN. Si no se encuentra ningún mensaje, recibirá un mensaje de error 404 - NOT FOUND.
Un ejemplo de respuesta después de un envío exitoso será:
{
"status": 200,
"message": "Message sent to carlos@soto.cl"
}La respuesta se conforma de los siguientes campos:
Campo | Descripción | Tipo |
status | Código de retorno de la petición. |
|
message | Texto indicando a quien fue enviado el mensaje |
|
Usted debe enviar los siguientes parámetros en formato JSON en el body de su petición:
Campo | Descripción | Tipo | Requerido |
ticket_id | Id del ticket al cual se desea responder |
| sí |
client_id | Id del cliente al cual se desea responder |
| no |
message | Mensaje a enviar al cliente |
| sí |
private_only | Si el mensaje puede o no ser enviado como respuesta pública |
| no |
Un ejemplo es:
{
"ticket_id": "583dcb2855d0a46e438d0206",
"message": "Este es un mensaje para un cliente"
}Si todo es correcto, la respuesta esperada será:
{
"status": 200,
"message": "Message sent to carlos@soto.cl"
}El mensaje en este ejemplo se habrá enviado al primer cliente en el ticket 583dcb2855d0a46e438d0206 de manera privada.
Otro ejemplo puede ser:
{
"ticket_id": "583dcb2855d0a46e438d0206",
"client_id": "546b9b2720a9f1301050fec3",
"message": "Este es un mensaje para un cliente",
"private_only": false
}Donde se explicita que el cliente 546b9b2720a9f1301050fec3 recibirá el mensaje en el ticket 583dcb2855d0a46e438d0206 pudiendo ser que su respuesta aparezca pública o privada, dependiendo de cuál sea más reciente.
private_only en true, dado que es posible que usted desee enviar datos como comprobantes de venta/pago, ordenes de compra u otro tipo de información confidencial al cliente y esto permitirá prevenir errores.