Api External Hibot (Api Externo)

Aquí está la guía del API External de Hibot. Aprenderás cómo configurarla paso a paso.

¿Para que sirve el Api External de Hibot? 

Cuando un cliente tiene la necesidad de enviar mensajes no tan recurrentes como una notificacion, un mensaje de alerta, una confirmacion etc. Les damos la oportunidad de utilizar un simple API con la cual es posible este envio. 

Configuración previa 

Para que funcione el envio de un mensaje a X contacto, es necesario que el canal (linea) por el cual quiere que salgan los mensajes, esté vinculado en nuestra plataforma, y tenga el permiso: 'Permitir enviar notificaciones (Api externo)' activo. 

Despues de que ya este el canal y el permiso, solo nos queda invocar los endpoints. 

Datos necesarios para realizar un envio de mensaje 

En la plataforma existe un menu llamado: Integración, en donde podemos encontrar el item: Api externo. Si el cliente no cuenta con este menú, es posible que no se encuentre dentro de los features habilitados para su licencia. 

Dentro de este modulo vamos a encontrar una pantalla con datos indispensables que vamos a necesitar: 

• AppId: Hace referencia a el tenant.
• AppSecret: Identificador único por cada tenant o ambiente, 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*, Esta url base cambia con cada Marca Blanca. 
• Canales: Listado de canales disponibles para realizar un envio y que estan vinculados en nuestro tenant. Importante: Solo canales de Whatsapp pueden ser utilizados. 

¿Que debe hacer el cliente para que funcione? 

Hibot solo expone ciertos endpoints para el envio de los mensajes, por lo cual, es responsabilidad del cliente realizar una integracion, aplicacion etc, que realice llamados a nuestra API. Utilizando la Url Base y demas datos de configuracion mostrados en el paso anterior. 

Pasos básicos para el envio de un mensaje 

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 enviara 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 extension. 

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', aqui 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 especificaran en un array de string, cada uno de los parámetros, es importante que esten 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, porfavor especificar el lenguage correspondiente. 

Nota: No es necesario utilizar todos los parametros, los unicos 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. 

Pasos básicos para el envio de un mensaje de plantilla 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 enviara 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 extension. 

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', aqui 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 especificaran en un array de string, cada uno de los parámetros, es importante que esten 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, porfavor especificar el lenguage correspondiente. 

Nota: No es necesario utilizar todos los parametros, los unicos 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. Tambien obviamente, la validez de la misma plantilla, que sea legitima y aprobada por Facebook. 

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 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 enviara 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 extension. 

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', aqui 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 especificaran en un array de string, cada uno de los parámetros, es importante que esten 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, porfavor especificar 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 pagina. 

Nota: No es necesario utilizar todos los parametros, los unicos 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. Tambien obviamente, la validez de la misma plantilla, que sea legitima y aprobada por Facebook. 

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 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 enviara 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 extension. 

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', aqui 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 especificaran en un array de string, cada uno de los parámetros, es importante que esten 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, porfavor especificar 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 esta en la plantilla oficial. 

footer: Campo para mensaje de pie de pagina. 

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 unicos 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. Tambien obviamente, la validez de la misma plantilla, que sea legitima y aprobada por Facebook. 

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 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 enviara 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 extension. 

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', aqui 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 especificaran en un array de string, cada uno de los parámetros, es importante que esten 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, porfavor especificar el lenguage 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 adjunto en el mensaje. Es obligatorio si la plantilla oficial tiene multimedia y debe ser del tipo de multimedia

que esta en la plantilla oficial. 

footer: Campo para mensaje de pie de pagina. 

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 unicos 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. Tambien obviamente, 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 enviara 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 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 conversacion, si por ejemplo actualmente el cliente esta teniendo una conversacion con un agente, el mensaje que se envio por el api externo, no será visible en esta conversacion actual. Los mensajes enviados, se verán 

reflejados solo en la SIGUIENTE conversacion que tenga el contacto con un agente. Cada vez que se inicie una nueva conversacion con un contacto, se realiza una busqueda de mensajes enviados previamente por el api externo. Si un mensaje del api ya fue asignado a una conversacion, ya no será asignado a ninguna otra en el futuro. 

Para que se genere una conversacion 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. 

Documentacion tecnica actual: 

Hibot_External_API. v.2.1.0 

(abirir con un navegador)