Guía de Notificaciones Automáticas (Guía de uso del API External de Hibot)

¿Para que sirve el Api External de Hibot? 

La API External de Hibot es una solución diseñada para empresas que necesitan automatizar el envío de mensajes puntuales y específicos desde sus propios sistemas hacia sus clientes finales.

A diferencia de las campañas masivas, esta API está optimizada para mensajes transaccionales, es decir, notificaciones que se disparan por una acción previa del usuario o un evento del sistema.

💡 Casos de Uso Principales:
Notificaciones: Avisos de entrega o cambios en el estado de un pedido.
Alertas: Recordatorios de citas o avisos de seguridad.
Confirmaciones: Códigos de verificación, confirmación de pagos o registros exitosos.

⚙️ Configuración Previa (Requisitos)

Antes de realizar tu primera integración, asegúrate de cumplir con estos dos pasos en la plataforma Hibot:

1. Vinculación del Canal: La línea (WhatsApp) por la cual deseas enviar los mensajes debe estar activa y correctamente vinculada en Hibot.

2. Activación de Permisos: En la configuración del canal, debes habilitar la opción: "Permitir enviar notificaciones (Api externo)" 

Una vez configurado el canal, el proceso se resume en invocar nuestros endpoints de manera segura.

Datos necesarios para el envío de mensajes:

Al ingresar al módulo de Configuración, en la sección Plataforma, encontrarás el acceso a API Externa.
Si no cuentas con este menú, es posible que no se encuentre dentro de las características que pagas por tu licencia. 

Dentro de este módulo vamos a encontrar una pantalla con datos indispensables que vamos a necesitar: 

• AppId: Hace referencia al identificador de tu cuenta (Tenant)
• AppSecret: Identificador único por cada cliente. Este identificador puede ser generado nuevamente en cualquier momento por un administrador.
• Url del api: Es la url BASE que contiene todos los llamados, cada uno de los diferentes endpoints que puede utilizar el cliente va despues de esta url base, como por ejemplo: .../pdn.api.hibot.us/api_external/login, .../pdn.api.hibot.us/api_external/*messages*.
• Canales: Listado de canales disponibles para realizar un envio y que están vinculados en el sistema.
  Importante: Solo canales de Whatsapp pueden ser utilizados. 
  
  

¿Qué debe hacer el cliente para que funcione? 

Hibot solo expone ciertos endpoints para el envío de los mensajes, por lo cual, es responsabilidad del cliente realizar una integración, aplicación etc, que realice llamados a nuestra API, utilizando la Url base y demás datos de configuración mostrados en el paso anterior. 

1️⃣Pasos básicos para el envío de un mensaje:

1. Invocar el endpoint Login y enviarle como parámetros el AppId y AppSecret.
Este endpoint siempre debe ser el primero en ser invocado, ya que el resultado es un Token. 

Token: Es el resultado de la autenticación que realizó el cliente con el appId y el appSecret.
Tiene una expiración de 24 horas.

2. Invocar el endpoint Messages, y enviarle los datos necesarios para saber a que contacto se le enviará el mensaje, el texto del mensaje y desde que línea saldrá el mensaje.
Utilizar el token generado en el paso anterior. 

Campos disponibles para el envío: 

• channelId: Id del canal que se utilizará para enviar los mensajes. 

• recipient: Número completo del contacto con la extensión. 

• content: Mensaje de texto. 

• media: En caso de contener multimedia, en este campo irá el enlace de la multimedia.

• mediaType: Especificación de que tipo de multimedia se enviará estos tipos son: IMAGE, VIDEO, AUDIO, DOCUMENT 

• template: En caso de ser un mensaje tipo 'Plantilla', aquí el nombre completo de la plantilla como por ejemplo: 'whatsapp:hsm:technology:nexmo:simplewelcome'

• params: En caso de que la plantilla contenga parámetros, se especificarán en un array de string cada uno de los parámetros. Es importante que estén en el orden que se desean mostrar. 

• language: El lenguaje de la plantilla, por defecto estará en ingles. ejemplo: 'en', 'es', 'fr' etc.
  Si la plantilla es de un lenguaje diferente al ingles, por favor especificar el lenguaje correspondiente. 

Nota: No es necesario utilizar todos los parámetros, los únicos campos persistentes son el canal y el recipiente.
Cada tipo de mensaje irá acompañado con otros obligatoriamente. Pueden ocurrir las siguientes combinaciones: 

• Multimedia: channelId, recipient, content(opcional), media y mediaType.
• Plantillas: channelId, recipient, content, template, params y language(opcional)
• Texto: channelId, recipient, content. 

2️⃣Pasos básicos para el envio de un mensaje de plantilla multimedia 

1. Invocar el endpoint Login y enviarle como parámetros el AppId y AppSecret.
Este endpoint siempre debe ser el primero en ser invocado, ya que el resultado es un Token. 

Token: Es el resultado de la autenticación que realizó el cliente con el appId y el appSecret.
Tiene una expiración de 24 horas. 

2. Invocar el endpoint Messages, y enviarle los datos necesarios para saber a qué persona se le enviará el mensaje, el mensaje como tal y desde que línea saldrá el mensaje.
Utilizar el token generado en el paso anterior.

Campos disponibles para el envío: 

• channelId: Id del canal que se utilizará para enviar los mensajes. 

• recipient: Número completo del contacto con la extensión. 

• content: Mensaje de texto. 

• media: En caso de contener multimedia, en este campo irá el enlace de la multimedia.

• mediaType: Especificacion de que tipo de multimedia se enviará estos tipos son: IMAGE, VIDEO, AUDIO, DOCUMENT 

• template: En caso de ser un mensaje tipo 'Plantilla', aquí el nombre completo de la plantilla como por ejemplo: 'whatsapp:hsm:technology:nexmo:simplewelcome' params: En caso de que la plantilla contenga parámetros, se especificarán en un array de string, cada uno de los parámetros, es importante que estén en el orden que se quieran mostrar. 

• language: El lenguaje de la plantilla, por defecto estará en inglés. ejemplo: 'en', 'es', 'fr' etc. Si la plantilla es de un lenguaje diferente al inglés, por favor especifique el lenguage correspondiente. 

Nota: No es necesario utilizar todos los parámetros, los únicos campos persistentes son channelId, recipient, media, mediaType, template, params (Solo si la plantilla oficial lo exige). 

Es indispensable que la plantilla esté creada en DB, y ligada al canal que vamos a utilizar.
También, la validez de la misma plantilla, que sea legítima y aprobada por Facebook. 

3️⃣Pasos básicos para el envió de un mensaje con plantilla de call to action sin multimedia 

1. Invocar el endpoint Login y enviarle como parámetros el AppId y AppSecret. Este endpoint siempre debe ser el primero en ser invocado, ya que el resultado es un Token. 

Token: Es el resultado de la autenticación que realizó el cliente con el appId y el appSecret.
Tiene una expiración de 24 horas. 

2. Invocar el endpoint Messages, y enviarle los datos necesarios para saber a qué persona se le enviará el mensaje, el mensaje como tal y desde que línea saldrá el mensaje.
Utilizar el token generado en el paso anterior. 

Campos disponibles para el envio: 

• channelId: Id del canal que se utilizará para enviar los mensajes. 

• recipient: Número completo del contacto con la extensión. 

• content: Mensaje de texto. 

• media: En caso de contener multimedia, en este campo irá el enlace de la multimedia.

   

• mediaType: CALLTOACTION 

• template: En caso de ser un mensaje tipo 'Plantilla', aquí el nombre completo de la plantilla como por ejemplo: 'whatsapp:hsm:technology:nexmo:simplewelcome'.

   

• params: En caso de que la plantilla contenga parámetros, se especificarán en un array de string, cada uno de los parámetros, es importante que estén en el orden que se quieran mostrar. 

• language: El lenguaje de la plantilla, por defecto estará en inglés. ejemplo: 'en', 'es', 'fr' etc. Si la plantilla es de un lenguaje diferente al inglés, por favor especifique el lenguage correspondiente. 

• paramsHeaders: En caso de que la plantilla contenga un título con parámetros. Es obligatorio si la plantilla oficial tiene estos parámetros. 

• paramsUrl: En caso de que la plantilla contenga un una url con parámetros. Es obligatorio si la plantilla oficial tiene estos parámetros para el redireccionamiento correcto. 

• footer: Campo para mensaje de pie de página. 

Nota: No es necesario utilizar todos los parámetros, los únicos campos persistentes son channelId, recipient, media, mediaType, template, params, paramsHeaders o paramsUrl (Solo si la plantilla oficial lo exige). 

Es indispensable que la plantilla esté creada en DB, y ligada al canal que vamos a utilizar.
También, la validez de la misma plantilla, que sea legítima y aprobada por Facebook. 

4️⃣Pasos básicos para el envió de un mensaje con plantilla de call to action con multimedia 

1. Invocar el endpoint Login y enviarle como parametros el AppId y AppSecret. Este endpoint siempre debe ser el primero en ser invocado, ya que el resultado es un Token. 

Token: Es el resultado de la autenticación que realizó el cliente con el appId y el appSecret.
Tiene una expiración de 24 horas.

2. Invocar el endpoint Messages, y enviarle los datos necesarios para saber a que persona se le enviará el mensaje, el mensaje como tal y desde que línea saldrá el mensaje.
Utilizar el token generado en el paso anterior. 

Campos disponibles para el envío: 

• channelId: Id del canal que se utilizará para enviar los mensajes. 

• recipient: Número completo del contacto con la extensión. 

• content: Mensaje de texto. 

• media: En caso de contener multimedia, en este campo irá el enlace de la multimedia.

  mediaType: CALLTOACTION 

• template: En caso de ser un mensaje tipo 'Plantilla', aquí el nombre completo de la plantilla como por ejemplo: 'whatsapp:hsm:technology:nexmo:simplewelcome'

  params: En caso de que la plantilla contenga parámetros, se especificarán en un array de string, cada uno de los parámetros, es importante que estén en el orden que se quieran mostrar. 

• language: El lenguaje de la plantilla, por defecto estará en inglés. ejemplo: 'en', 'es', 'fr' etc. Si la plantilla es de un lenguaje diferente al inglés, por favor especifique el lenguage correspondiente. 

• paramsUrl: En caso de que la plantilla contenga un una url con parámetros. Es obligatorio si la plantilla oficial tiene estos parámetros para el redireccionamiento correcto. 

• headerType: Se debe enviar el tipo de multimedia que se adjunto en el mensaje. Es obligatorio si la plantilla oficial tiene multimedia y debe ser del tipo de multimedia que está en la plantilla oficial. 

• footer: Campo para mensaje de pie de página. 

Nota: Si la plantilla tiene algún archivo multimedia no están permitidos los parametros headers ni paramsHeaders. 

No es necesario utilizar todos los parametros, los únicos campos persistentes son channelId, recipient, media, mediaType, headerType,template, params, paramsHeaders o paramsUrl (Solo si la plantilla oficial lo exige). 

Es indispensable que la plantilla esté creada en DB, y ligada al canal que vamos a utilizar.
También, la validez de la misma plantilla, que sea legítima y aprobada por Facebook. 

5️⃣Pasos básicos para el envió de un mensaje con plantilla de botones con multimedia 

1. Invocar el endpoint Login y enviarle como parametros el AppId y AppSecret.
Este endpoint siempre debe ser el primero en ser invocado, ya que el resultado es un Token. 

Token: Es el resultado de la autenticación que realizó el cliente con el appId y el appSecret.
Tiene una expiración de 24 horas. 

2. Invocar el endpoint Messages, y enviarle los datos necesarios para saber a que persona se le enviará el mensaje, el mensaje como tal y desde que línea saldrá el mensaje.
Utilizar el token generado en el paso anterior.

 

Campos disponibles para el envio: 

• channelId: Id del canal que se utilizará para enviar los mensajes. 

• recipient: Numero completo del contacto con la extensión. 

• content: Mensaje de texto. 

• media: En caso de contener multimedia, en este campo irá el enlace de la multimedia.

• mediaType: INTERACTIVE 

• template: En caso de ser un mensaje tipo 'Plantilla', aquí el nombre completo de la plantilla como por ejemplo: 'whatsapp:hsm:technology:nexmo:simplewelcome'

• Params: En caso de que la plantilla contenga parámetros, se especificarán en un array de string cada uno de los parámetros. Es importante que estén en el orden que se quieran mostrar. 

• language: El lenguaje de la plantilla, por defecto estará en ingles. ejemplo: 'en', 'es', 'fr' etc. Si la plantilla es de un lenguaje diferente al ingles, por favor especificar el lenguaje correspondiente. 

• buttons: En caso de que la plantilla contenga botones.
  
  Es obligatorio si la plantilla oficial tiene estos parámetros. 

• headerType: Se debe enviar el tipo de multimedia que se adjuntó en el mensaje.
  Es obligatorio si la plantilla oficial tiene multimedia y debe ser del tipo de multimedia.

• footer: Campo para mensaje de pie de pagina. 

Nota: Si la plantilla tiene algún archivo multimedia no están permitidos los parámetros headers ni paramsHeaders. 

No es necesario utilizar todos los parámetros, los únicos campos persistentes son channelId, recipient, media, mediaType, headerType,template, params, paramsHeaders o paramsUrl (Solo si la plantilla oficial lo exige). 

Es indispensable que la plantilla esté creada en DB, y ligada al canal que vamos a utilizar.
También, la validez de la misma plantilla, que sea legitima y aprobada por Facebook. 

Pasos básicos para el envió de un mensaje quick reply con multimedia 

1. Invocar el endpoint Login y enviarle como parametros el AppId y AppSecret. Este endpoint siempre debe ser el primero en ser invocado, ya que el resultado es un Token. 

Token: Es el resultado de la autenticacion que realizó el cliente con el appId y el appSecret.
Tiene una expiracion de 24 horas. 

2. Invocar el endpoint Messages, y enviarle los datos necesarios para saber a que persona se le enviará el mensaje, el mensaje como tal y desde que línea saldrá el mensaje.
Utilizar el token generado en el paso anterior.

Campos disponibles para el envío: 

• channelId: Id del canal que se utilizará para enviar los mensajes. 

• recipient: Numero completo del contacto con la extension. 

• content: Mensaje de texto. 

• mediaType: INTERACTIVE 

• buttons: En caso de que la plantilla contenga botones.
  
  Es obligatorio si la plantilla oficial tiene estos parámetros. 

• header: Campo para mensaje de encabezado del mensaje. 

• footer: Campo para mensaje de pie de pagina. 

• interactiveHeader: Objeto con información del tipo de media que se va a utilizar, el cual solo esta permitido imagen, el nombre del archivo y el link de esa media. 

¿Que pasa por debajo con un mensaje enviado por el API?

El mensaje sera marcado con que se envió desde el api externo, en DB, el mensaje queda con la marca: 

from: 'EXTERNAL' . 

El mensaje al instante NO será asignado a una conversación, si por ejemplo actualmente el cliente esta teniendo una conversación con un agente, el mensaje que se envió por el api externo, no será visible en esta conversación actual.
Los mensajes enviados, se verán reflejados solo en la SIGUIENTE conversación que tenga el contacto con un agente. Cada vez que se inicie una nueva conversación con un contacto, se realiza una búsqueda de mensajes enviados previamente por el api externo.
Si un mensaje del api ya fue asignado a una conversación, ya no será asignado a ninguna otra en el futuro. 

Para que se genere una conversación con una respuesta de un mensaje del api, es necesario que el canal esté asignado a una campaña, en lo posible tener agentes asignados a esa campaña. 

📄Documentación tecnica actual: 

Hibot_External_API. v.2.1.0 (abrir con un navegador 🛜)