¿Cómo acceder a Botmaker API?

Aquí aprenderás cómo acedder a Botmaker API.

Acceso

Para acceder a los métodos API y sus especificaciones de swagger, debes seguir los siguientes pasos que te permitirán obtener un token de acceso. Para hacer esto:

1 - Accede a la página de configuración del canal

2 - Selecciona API de Botmaker - Credenciales

3 - Genera un token o usa el que ya se generó. En particular, es importante guardar el token de acceso

Una vez con el Token, accede al swagger: API

Haz clic en el botón “autorizar” (arriba a la derecha) e ingresa el token de acceso en el segundo campo de texto, como se muestra a continuación. Haz clic en autorizar.

Modelo de datos

Cliente

En un modelo de datos, un cliente simboliza un usuario o cliente que ha interactuado con el bot. Todas las interacciones que tienen lugar en el mismo canal (WhatsApp, Webchat, Messenger, Twitter, Google Assistant, etc.) continuarán refiriéndose al mismo cliente.

El cliente se compone de los siguientes datos:

  • BUSINESS_ID: identificación del bot al que pertenece el usuario. Para el mismo bot, todos los clientes tendrán el mismo número de identificación.

  • CREATION_TIME: fecha de creación del cliente, es decir, de su primera interacción.

  • CHAT_PLATFORM_ID: la plataforma en la que interactuó el usuario. Puede ser WhatsApp, Webchat, Messenger, Twitter, Google Assistant, Microsoft Teams, etc.

  • CHAT_CHANNEL_ID: el canal a través del cual el usuario interactúa en la plataforma. Es una identificación formada por la plataforma + la identificación del canal. Diferentes páginas de Facebook por ejemplo.

  • PLATFORM_CONTACT_ID: ID específico generado por la plataforma de canal utilizada. Junto con la identificación del canal, permite identificar al usuario individualmente.

  • BOT_MUTED: indica si el bot está en muted para este usuario. Cuando el bot está apagado, no enviará respuestas automáticas al usuario. El bot se degrada nuevamente después de 60 minutos de inactividad del usuario.

  • PENDING_MSGS: cantidad de mensajes que el bot no entendió y están pendientes de ser leídos por un agente humano.

  • FIRST_NAME y LAST_NAME: nombre y apellido del usuario respectivamente.

  • LAST_SEEN: fecha en la que el usuario habló por última vez.

  • PICTURE_URL: imagen de usuario en el canal al que pertenece.

  • Variables: el usuario también está compuesto de variables, que son datos que se obtienen en interacciones con el bot.

Estos valores son parte del cliente y aparecerán en la API con el último valor que se obtuvo de una determinada variable.

Las variables se configuran (como en los lenguajes de programación) para guardar sus posibles valores y se pueden ver o modificar en la plataforma, en la sección de variables.

  • Tags: etiquetas que se aplican a un usuario para su posterior identificación. La etiqueta se puede considerar como una variable booleana (activada o desactivada).

Un usuario tiene una etiqueta por los siguientes motivos:

El usuario habla sobre un tema específico con el bot, que lo etiqueta automáticamente para ese tema.

El bot etiqueta al usuario específicamente para ver más adelante las métricas o la generación de audiencias para enviar mensajes push.

Mensajes

message/download‌ El propósito de este punto final es obtener el historial de mensajes de una conversación. Cada llamada devuelve 500 registros de mensajes, junto con el estado del usuario y un operador humano al momento de enviar el mensaje.

Modo de uso‌ Este servicio debe llamarse periódicamente, manteniendo los datos devueltos en su propia base de datos y luego analizándolos de acuerdo con sus necesidades. Cada solicitud actualiza en la API la fecha del último mensaje descargado. Cada nueva llamada continúa donde terminó la llamada anterior. La estructura JSON devuelta es:

{
hasMore: Boolean (si hay mas mensajes para pedir; usarlo como condición de loop)
messages: Lista de mensajes
count: Cantidad de mensajes
}

‌ Estos son algunos de los campos del objeto de mensajes: ‌

  • id

  • datas: creation_time, message_date, message_year, message_month, message_week, message_day, message_quarter, message_dayofweek, message_time, message_hour, message_minute, message_second, message_day_name, message_semester, message_bimester

  • msg_from, msg_to (de un usuario; bot de la plataforma)

  • message

  • chat_channel_id: el canal del mensaje (webchat, WhatsApp, Messenger, etc).

  • datos del usuario: customer_id, customer_last_seen, customer_platform_contact_id, customer_first_name, customer_last_name, customer_email, customer_has_talked

  • datos del usuario en el bot: campos uservar_*.​

Ejemplo: ‌

El siguiente es un ejemplo en node.js sobre cómo se debe consumir el servicio:

‌const rp = require('request-promise');​
(async () => {
let results = await rp.post('https://go.botmaker.com/api/v1.0/message/download', { headers: { 'access-token': 'your-bot-access-token' }, json: true
});​
while (results.hasMore) {
results = await rp.post('https://go.botmaker.com/api/v1.0/message/download', { headers: { 'access-token': 'your-bot-access-token' }, json: true });
results.messages.forEach(message => saveInDB(message));
}​
console.log('done!') })();

Parámetro fromDate‌

El parámetro fromDate te permite rebobinar el puntero interno para solicitar datos nuevamente en caso de error al guardarlo. fromDate puede ser al menos una semana antes de la hora actual.

Intenciones

/intent/trigger

[https://go.botmaker.com/api/v1.0/intent/trigger]

Se usa para activar una plantilla para un usuario específico, utilizando su número de contacto como parámetro para la identificación del mismo. Cuenta con la posibilidad de agregar parámetros adicionales que sirven para alimentar las variables del usuario en cuestión.