Mensajes

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.

Recuerde que todas las peticiones hechas a nuestra API deben ser autentificadas

 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). Postcenter no se encarga de realizar este procedimiento.

Este servicio es para enviar HSM previamente cargados en Postcenter. 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 Postcenter, 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 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:

{
  "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:

{
  "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 Postcenter 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

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

Probar servicio

Permite iniciar una conversación con un cliente de manera proactiva.

Mejores prácticas para WhatsApp: La persona que recibirá el mensaje debe saber que la van a contactar. De lo contrario es posible que reporte o bloquee la cuenta. Si muchos clientes lo hacen, WhatsApp puede bloquear el número de teléfono permanentemente.

Definir cuentas proactivas

No todos los números de WhatsApp conectados en Postcenter 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 string
user_name Nombre del cliente, utilizado para crear su perfil en Postcenter string
account_id Identificador del la cuenta de WhatsApp a utilizar string
message  El texto a enviar string
no_manual_reopen Fuerza a que el ticket una vez cerrado, no se pueda reabrir boolean
no_manual_merge Fuerza a que el ticket no se pueda fusionar con otro boolean

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 Postcenter 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 Postcenter 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. 200 si la petición fue exitosa integer
ticket_id  Identificador de ticket string

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

Probar servicio

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 Postcenter 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 Postcenter 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.

Solo mensajes de Postcenter: Usted sólo puede responder mensajes que han pasado por Postcenter y estén vinculados a las cuentas de su empresa en nuestra plataforma.

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. 200 si la petición fue exitosa integer
message  Texto indicando a quien fue enviado el mensaje string

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 string
client_id Id del cliente al cual se desea responder string no
message  Mensaje a enviar al cliente string
private_only Si el mensaje puede o no ser enviado como respuesta pública boolean 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.

Mensajes automáticos: Para el envío de mensajes automáticos, se recomienda siempre explicitar 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.