¿Cómo integrar webhooks?
En este artículo aprenderás qué es un webhook y cómo integrarlo en la plataforma.
Lectura estimada: 05 minutos
¿Qué es un webhook?
Los webhooks son un método por el cual los servidores de Botmaker se comunican con los servidores del cliente cuando se dan ciertos eventos. Por ejemplo, cuando un bot envía un mensaje, se dispara un mensaje de webhook. De esta forma, los clientes podrían integrar estos eventos con un sistema para, por ejemplo, recopilar todos los mensajes enviados por un bot.
Nota: Recuerda que para poder usar esta funcionalidad debes tener un rol de súper administrador o un rol con permiso a la pantalla de webhooks.
Integrar webhooks en Botmaker
Para acceder a la pantalla de webhooks, ve a Menú>Integraciones> Webhooks.
Dentro de la pantalla webhooks en Botmaker puedes:
- Crear, editar y eliminar webhooks.
- Conectar webhooks a tus canales de preferencia.
- Configurar qué tipos de mensajes quieres que se notifiquen.
- Obtener notificaciones sobre cambios de variables.
- Testear webhooks: con herramientas para que puedas probar que detectan y procesan correctamente las diferentes notificaciones.
¿Cómo crear un webhook?
Para crear un nuevo webhook, sólo debes hacer click en Nuevo webhook. Se abrirá una ventana emergente donde tendrás que completar todos los campos.
¡Listo! Ya creaste tu webhook.
Nota: Puedes contar con múltiples webhooks. Sin embargo, no puedes tener más de un webhook para el mismo canal.
¿Qué encontrarás en cada webhook?
Botones de la barra azul superior:
- Apagar o encender este webhook
- Editarlo
- Eliminarlo
Test webhook: Desde aquí puedes probar el mensaje que enviará el webhook según tu configuración. Recuerda tener el webhook en on , ya que en caso contrario no funcionará esta opción.
Error logs: aquí tienes más detalles de los últimos errores.
En el histograma puedes ver la cantidad de:
- Respuestas exitosas
- Respuestas lentas
- Respuestas con error
- Respuestas rechazadas, envío de mensajes bloqueado debido a repetidas fallas en webhook
En los últimos 30 minutos encontrarás:
- Tiempo más rápido
- Tiempo promedio
- Tiempo más lento
De esta manera podrás chequear el estado de salud de tu servidor. Si el webhook falla más de 100 veces durante 10 minutos, los nuevos mensajes dejarán de ser enviados por los próximos 10 minutos para evitar saturar el servidor (estos mensajes se perderán). Es por ello que es importante mantener la operatividad del clúster de servidores que recibirá los mensajes del webhook.
Nota: Esta funcionalidad no está activa por defecto, dado que tiene un costo adicional. Para activarla ve a la sección "Cuenta". Allí encontrarás un apartado especifico con el título "webhook" desde donde podrás dar de alta la funcionalidad con solo un click.
Mensajes enviados en webhooks
Los siguientes ejemplos aplican a mensajes en webhooks enviados tanto desde la plataforma como desde la API de Botmaker.
A continuación, verás dos ejemplos:
- Formato de mensaje enviado por webhook
{
// 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": "Apellido",
// 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"
}
}
- Formato de estado de mensaje enviado por webhook
{
// 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
}
¡Listo! Ya has integrado tus webhooks para monitorear tus comunicaciones en tiempo real.
Recuerda visitar nuestro Centro de Ayuda para mayor información.
Escrito por: Equipo Botmaker
Actualizado: 15/03/2022