¿Cómo utilizar Botmaker API?

En este artículo aprenderás cómo utilizar Botmaker API.

Lectura estimada: 10 minutos

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á silenciado 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

Es posible enviar mensajes a los usuarios utilizando la consola del agente, generando notificaciones masivas y programando envíos por diferentes estímulos. También puedes utilizar el API de Botmaker para disparar mensajes programáticamente desde un sistema.

Es importante tener en cuenta que para usar este tipo de servicio, se recomienda tener un webhook integrado con nuestra cuenta para recibir todos los mensajes que nos envíen los usuarios.

Para obtener mayor información sobre este tema, puedes consultar el siguiente artículo: ¿Cómo integrar webhooks?

**message/v3**

[https://go.botmaker.com/api/v1.0/message/v3]

El propósito de este punto final es enviar un mensaje a un usuario dentro de una conversación.

‌

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

chatPlatform - Plataforma a través de la cual se está llevando la comunicación con el usuario.
chatChannelNumber - Número de teléfono de la cuenta o ID del canal dentro de la plataforma.
platformContactId - Número de teléfono del usuario o ID identificatorio en la plataforma.
messageText - Mensaje de texto a enviar.
audioURL - URL al archivo de audio a enviar.
fileURL - URL al documento a enviar.
videoURL - URL al archivo de video a enviar.
imageURL - URL al archivo de imagen a enviar.
clientPayload - Campo de texto libre. Por lo general se utiliza para colocar un ID personalizado y hacer seguimiento de la respuesta del mensaje. Debido a que una vez que le asignemos un valor, recibiremos este campo en nuestro webhook con el valor asignado en cada mensaje del usuario hasta que sea reemplazado por un nuevo valor. Es importante que si se usa este parámetro, en cada mensaje enviado se vaya cambiando el valor de este campo.

Ejemplo: ‌

El siguiente es un ejemplo de cómo se debe consumir el servicio con un llamado vía HTTP Post al API rest con un JSON:


curl -X POST

--header &#39;Content-Type: application/json&#39;

--header &#39;Accept: application/json&#39;

--header &#39;access-token: your\_access\_token&#39;

-d &#39;{

&quot;chatPlatform&quot;: &quot;whatsapp&quot;,

&quot;chatChannelNumber&quot;: &quot;your\_phone&quot;,

&quot;platformContactId&quot;: &quot;user\_phone&quot;,

&quot;messageText&quot;: &quot;message\_to\_send&quot;

}&#39;

&#39;[https://go.botmaker.com/api/v1.0/message/v3](https://go.botmaker.com/api/v1.0/message/v3)&#39;

# your\_access\_token: ey...

# your\_phone: +55135433...

# user\_phone: +5512324314..

# message\_to\_send: Hi!

**Nota:** El parámetro de ´messageText´ no es combinable con los parámetros de multimedia. Es decir, puedo enviar un mensaje de texto, o puedo enviar un archivo multimedia donde no habrá parámetro de ´messageText´.

Intenciones

Botmaker permite enviar todos los tipos de mensajes multimedia soportados por WhatsApp y otros canales. Para ello, deberás crear una plantilla o mensaje personalizado.

Para mayor información, puedes leer los siguientes artículos:

¿Cómo crear una intención?

¿Cómo enviar templates?

¿Cómo crear templates via API?

https://go.botmaker.com/api/v1.0/intent/v2

Se usa para activar una plantilla o intención 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.

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

chatPlatform - Plataforma a través de la cual se está llevando la comunicación con el usuario.
chatChannelNumber - Número de teléfono de la cuenta o ID del canal dentro de la plataforma.
platformContactId - Número de teléfono del usuario o ID identificatorio en la plataforma.
ruleNameOrId - ID o nombre de la intención que desea enviar al usuario.
params - Lista de variables y los valores que se desean asignar para el usuario. Puede estar vacía.

Ejemplo : ‌

El siguiente es un ejemplo de cómo se debe consumir el servicio con un llamado vía HTTP Post al API rest con un JSON:


curl -X POST

--header &#39;Content-Type: application/json&#39;

--header &#39;Accept: application/json&#39;

--header &#39;access-token: your\_token&#39;

-d &#39;{

&quot;chatPlatform&quot;: &quot;whatsapp&quot;,

&quot;chatChannelNumber&quot;: &quot;your\_phone\_number&quot;,

&quot;platformContactId&quot;: &quot;user\_phone\_number&quot;,

&quot;ruleNameOrId&quot;: &quot;rule\_name&quot;,

&quot;params&quot;: {

&quot;varName&quot;: &quot;varValue&quot;

}

}&#39;

[https://go.botmaker.com/api/v1.0/intent/v2](https://go.botmaker.com/api/v1.0/intent/v2)

# your\_token: your access token

# your\_phone\_number: whatsapp number of yours

# user\_phone\_number: whatsapp number of user

# rule\_name: botmaker rule name

Métricas

El API de Botmaker permite obtener una variedad de información del usuario a través de los métodos de Metrics. Con toda esta información, y haciendo un procesamiento de la misma, es posible generar diferentes tipos de métricas.

Para obtener mayor información sobre este tema, puedes consultar los siguientes artículos: