¿Cómo acceder a Botmaker API para WhatsApp?
En este artículo obtendrás información acerca de cómo acceder a Botmaker API para WhatsApp.
Lectura estimada: 10 minutos
Es posible enviar mensajes a los usuarios utilizando la consola del agente, donde puedes responder manualmente o mediante bots. Desde la API de Botmaker, también se pueden generar notificaciones masivas y programar su entrega desde un sistema.
Nota_: estas acciones son válidas para las conversaciones generadas en un período de 24 horas. De no ser así, se podrán enviar templates. Consulta nuestro artículo relacionado:_ ¿Cómo enviar templates?
¿Cómo obtener credenciales para acceder a la API?
Para acceder a la API, debes obtener un token de acceso siguiendo estos pasos:
- Ingresa a Canales e Integraciones > Botmaker API.
- Selecciona Botmaker API > Generar Credenciales.
- Genera un token o utiliza uno ya generado. Es imprescindible que no pierdas este token. Guárdalo.
- Ingresar dicho token en el header access-token de la request HTTP.
¿Es posible probar la API?
Sí, para probar la API, debes ir a https://go.botmaker.com/apidocs/. Haz click en “Authorize”. Al ingresar el access token, aparecerán todas las opciones que permite la API.
Haz click en “message” y luego en post> message/V3.
A continuación, completa los parámetros:
- Copia el ejemplo Example Value ,
- Agrega tus datos de canal y teléfono, texto de mensaje, etc…
Con acceso al token, será posible hacer la publicación HTTP llamada API rest dentro de un JSON:
curl -X POST --header ‘Content-Type: application/json’ --header ‘Accept: application/json’ --header ‘access-token: your_access_token’ -d ‘{“chatPlatform”: “whatsapp”, “chatChannelNumber”: “your_phone”, “platformContactId”: “user_phone”,“messageText”: “message_to_send”}’ ‘https://go.botmaker.com/api/v1.0/message/v3’
#your_access_token: ey…
#your_phone: +55135433…
#user_phone: +5512324314…
#message_to_send: Hi!
La respuesta será un código http 200 con un JSON que indica la ID del mensaje generado:
{
“id”: “id_del_mensaje”
}`
Cada vez que se envíe un mensaje al usuario, se realizará una verificación de saldo en tu cuenta de Botmaker. Si la cuenta está a punto de quedarse sin saldo, el servicio devolverá un código http 403 - Prohibido , que indica que no hay saldo para enviar mensajes en la respuesta JSON:
{
“error”: {
“code”: 101,
“message”: “Insufficient credit”
}
}`
Consulta la sección Plantillas de Mensajes para obtener más información:
Plantillas de Mensajes de WhatsApp
WhatsApp permite a los usuarios enviar mensajes dentro de las 24 horas posteriores al último mensaje enviado por ellos. Fuera de ese período, debes utilizar plantillas. Para enviar nuevas plantillas para su aprobación, puedes acceder desde Menú>Envío de Notificaciones>Plantillas. Aquí puedes crearlas haciendo clic en el “+” ubicado en la parte superior de la pantalla.
Para obtener información detallada acerca de cómo crear y enviar plantillas de WhatsApp, consulta nuestro artículo relacionado ¿Cómo crear y enviar un template de WhatsApp y optimizar los tiempos de respuesta?.
Una vez que la plantilla ha sido aprobada (puedes chequearlo en Menú>Plantillas), puedes crear una intención para disparar esa plantilla según sea necesario. Sigue los siguientes pasos:
Paso 1 : Ingresa a Menú>Chatbots
Paso 2 : Crea una nueva intención
Paso 3 : Al configurar la respuesta a tu intención, selecciona Acción>Notificación de WhatsApp.
Paso 4 : Selecciona la plantilla que deseas utilizar y haz click en " guardar".
Nota : Al crear la plantilla, se pueden agregar variables o textos que autocompleten información en los parámetros de WhatsApp.
Envío de plantillas
Puedes enviar plantillas de tres maneras diferentes (siempre considerando el envío a través de la plataforma Botmaker)
- Individualmente desde la sección de chat manual (Conversaciones>Chats>Enviar plantilla)
- Masivamente desde la sección de audiencias (Envío de notificaciones>Audiencias)
imagen13
Consulta los detalles acerca de cómo enviar plantillas en nuestro artículo ¿Cómo enviar templates?
- Utilizando la API de Botmaker. Consulta el artículo: ¿Cómo crear y enviar un template de WhatsApp y optimizar los tiempos de respuesta?
Webhooks: cómo recibir mensajes de conversaciones
Para obtener información detallada sobre cómo integrar webhooks, consulta el artículo ¿Cómo integrar webhooks?
Formato de las notificaciones webhook
Hay 2 tipos de notificaciones:
- De mensaje
- De estado del mensaje
Notificaciones de mensaje
Son notificaciones que se reciben cuando llega un mensaje del usuario o cuando el bot o un agente envía un mensaje al usuario. La estructura del cuerpo de la solicitud (request) es:
{
// versión del formato
"v": "1.1",
// marca de que es una notificación de mensaje
"type": "message",
// campos de plataforma chat y del canal:
// el nombre de la plataforma chat
"chatPlatform": "webchat" | "whatsapp" | "messenger" | "telegram" | "twitter" | …,
// whatsapp: número de teléfono del usuario
// messenger, telegram o twitter: id de usuario en plataforma
"contactId": string,
// si el canal es whatsapp, numero de la cuenta del bot
"whatsappNumber": "551149331774",
// si el canal no es whatsapp, id del chat en la plataforma de chat
"chatIdInChatPlatform":"AR4Q1S3P1U",
// id del canal de chat en Botmaker
"chatChannelId": string,
// fin de campos de plataforma chat y del canal
// campos del usuario:
// id del usuario en Botmaker
"customerId":"NDRP2LQVX2C4G8DNEQCH",
// nombre y apellido del usuario
"firstName": "Pedro",
"lastName": "Patineta",
// fecha y tiempo de creación de usuario (formato YYYY-MM-DDThh:mm:ss.sssZ)
"customerCreationTime": "2021-02-28T23:59:00.147Z",
// fecha y tiempo de comienzo de la sesión a la que pertenecen los mensajes (formato YYYY-MM-DDThh:mm:ss.sssZ)
"sessionCreationTime":"2021-03-08T19:28:45.147Z",
// fin campos del usuario
// mensajes: array. Pueden generarse varios mensajes en respuesta a un mensaje de usuario;
// esto suele ocurrir cuando responde el bot
"messages": [
{
// id del mensaje en Botmaker (la notificación de status hace referencia a este id)
"_id_":"PHW3S2KV4VRWL17BBM1U",
// fecha y tiempo del mensaje
"date":"2021-03-08T19:44:14.388Z",
// texto del mensaje
"message": "Hola, cómo estás?",
// nombre de quién generó el mensaje. El nombre de usuario u operador, o "Bot" si fue el bot
"fromName":"Ignacio F",
// categoría de quién envió el mensaje
"from": "bot" | "user" | "operator",
// flag que marca si es del usuario
"fromCustomer": true | undefined,
// flag que marca si fue un botón (el texto de "message" va a ser el label del botón)
"isButton": true | undefined,
// flag que indica si tiene imagen, video, audio o documento
"hasAttachment": true | undefined,
// urls del attachment
"image": "https://…",
"audio": "https://…",
"video": "https://…",
"file": "https://…",
// si el mensaje fue emitido por un operador (from == "operator"), los siguientes campos serán enviados: operatorId, operatorName, operatorEmail, operatorRole
// id del operador en Botmaker
"operatorId": "bxj99dyfxEsdopib9ZuboIG5Tqr3",
"operatorName": "Pepe",
"operatorEmail": "pepe@domain.com",
"operatorRole": "ADMIN" | "CONFIGURATOR" | "SUPERVISOR" | "OPERATOR" | nombreRolCustom
// cola en la que está el usuario al momento del mensaje
"queue":"idColaAtencion" | undefined
// si el mensaje fue generado por una intención (from == "bot"), se envía el nombre de la intención
"intentName": "Nombre de una Intención"
// específicos para Whatsapp
// cuando el usuario envía su geolocalización
"location": "lat & long",
// texto que acompaña imagen
"caption": string,
// para hsm/templates con botones:
"payload": string, // payload configurado por usuario
"button": string, // label del botón hsm
"templateName": string, // nombre del template con botón
},
// otros mensajes
{ … },
{ … }
],
// cambios de variables que ocurrieron al generarse estos mensajes
// mapa nombreVariable -> nuevoValor
"variables": {
"varName1": "new val 1",
"varName2": "new val 2"
}
}
Notificaciones de estado del mensaje (sólo WhatsApp) Son notificaciones de los estados por los que va pasando el mensaje:
- Enviado (sent): Botmaker envió el mensaje a WhatsApp
- Entregado (delivered): el mensaje llegó a destinatario
- Leído (read): mensaje leído
- Fallado (failed): falló el envío
- Eliminado (deleted): mensaje eliminado
La estructura de la notificación es:
{
// version del formato
"v": "1.1",
"type": "status",
// id del bot en Botmaker (por si varios bots apuntan a mismo webhook)
"businessId": string,
// whatsapp: número de teléfono del usuario
// messenger, telegram o twitter: id de usuario en plataforma,
"contactId": string,
// id del canal de chat en Botmaker
"chatChannelId": string,
// el nombre de la plataforma de chats
"chatPlatform": "webchat" | "whatsapp" | "messenger" | "telegram" | "twitter", …,
// si el canal es Whatsapp, el número de teléfono que usa el bot
"whatsappNumber": "551149331774",
// id del usuario en Botmaker
"customerId": string,
// message status
"status": "delivered" | "read",
// fecha y tiempo del cambio de estado (formato YYYY-MM-DDThh:mm:ss.sssZ)
"statusChangeTime": "2021-03-01T00:00:00.000Z",
// id del mensaje en Botmaker que cambió de estado (este id hace referencia a algún id de mensaje de salida, del bot u operador)
"messageId": string,
// para cuando el mensaje se envía por api de Botmaker
"clientPayload": string
}
Aplicar formatos a los mensajes a través de la API
Es posible aplicar formatos simples al texto de los mensajes que se enviarán a los usuarios, por ejemplo, “Hola, John”. Para más información, consulta la Documentación de Formatos de WhatsApp.
Recuerda visitar nuestro Centro de Ayuda para mayor información
Escrito por Equipo Botmaker
Actualizado: 02/03/2022