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 específico con el título "webhook" desde donde podrás dar de alta la funcionalidad con solo un click.

Ejemplos:

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 ejemplos:

Formato de notificación de mensajes Entrantes y Salientes: JSON

{

    // version 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 línea 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": string,

    // nombre y apellido del usuario

   "firstName": string,

    "lastName": string,

    // 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",

    // user fields end

    "whatsappNickName": string,

    // cuando se envían templates por la API Botmaker, el valor de este campo coincide con `webhookNotificationId` devuelto por el API

    "txId": string,

    // 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 Ferrari",

            // 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

            // En la API Botmaker de mensajes y disparo de intenciones es posible enviar `webhookPayload` (v2.0) o `clientPayload` (v1).

            // `webhookPayload` (o `clientPayload`) sirve para que el usuario del API haga seguimiento del envío del mensaje.

            // Si el mensaje fue enviado a través de la API Botmaker, es en este campo donde se vuelve a enviar `webhookPayload` o `clientPayload`.

            "clientPayload": string,

            // cuando el usuario entra a la conversación siguiendo un link referral

            "whatsappReferral": {

                "sourceId": string,

                "sourceURL": string,

                "headline": string,

                "body": string

     },

            // cuando el mensaje es de checkout de cart

            "cart": {

                "products": [

                    { "sku": string, "quantity": number }

                ]

            }

        },

        // 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 notificación de status (Whatsapp)

```json

{

    // version del formato

    "v": "1.0",

    // id del bot en Botmaker (por si varios bots apuntan a mismo webhook)

    "businessId": string,

    // id del usuario en Botmaker

    "customerId": 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",

    // message status

    // sent: whatsapp envío el mensaje

    // delivered: el mensaje llegó al teléfono destino

    // read: el mensaje fue leído

    "status": "sent" | "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,

    // En la API Botmaker de mensajes y disparo de intenciones es posible enviar `webhookPayload` (v2.0) o `clientPayload` (v1).

    // `webhookPayload` (o `clientPayload`) sirve para que el usuario del API haga seguimiento del envío del mensaje.

    // Si el mensaje fue enviado a través de la API Botmaker, es en este campo donde se vuelve a enviar `webhookPayload` o `clientPayload`.

    "clientPayload": string,

    // cuando se envían templates por la API Botmaker, el valor de este campo coincide con `webhookNotificationId` devuelto por el API

    "intentTxId": string,

    "error": [ { "message": string, "code": string } ]

}

Es posible seguir el resultado de un envío vía API Botmaker escuchando los webhooks de estado.

Para ello,

- enviar a la API un `webhookPayload` (o `clientPayload` en la v1) y al recibir una notificación de estado, revisar `clientPayload` y marcar que esa clientPayload se envío o tuvo error.

- guardar el `webhookNotificationId` devuelto por el API y revisar `intentTxId` en la notificación de estado.

Escrito por: Equipo Botmaker

Actualizado: 22/03/2024