Documentación
🇺🇸🇧🇷Discord
Start typing to search…

Integración de Chatbot privado

En este tutorial aprenderás cómo usar las funciones de tu Salesbot para enviar mensajes desde servicios externos a tus canales de chat de Kommo.

El caso más común es conectar algún servicio LLM a Kommo para analizar los mensajes que llegan a tu cuenta a través de ciertos canales de chat, y luego responder con mensajes generados por el LLM.

❗️

Los métodos de la API de Chats no te permitirán hacer lo mismo, ya que cada integración tiene su propio canal de chat y no puedes acceder a ellos mediante tu propio canal personalizado. Puedes enviar mensajes de forma manual o a través del Salesbot a esos canales.

Salesbot para enviar mensajes

Salesbot es un bot que puede programarse para realizar ciertas acciones dentro de Kommo. Ayuda a recibir datos de los usuarios a través de mensajeros (Telegram, Facebook Messenger, Instagram) y envía mensajes a cualquier canal de chat conectado a tu cuenta de Kommo.

El Salesbot también cuenta con varios manejadores que pueden ser útiles para ampliar su funcionalidad. Por ejemplo, el manejador widget_request te permite enviar webhooks a URLs externas con los datos especificados desde Kommo hacia tu widget, y recibir una respuesta de vuelta en Kommo.

📘

widget_request es el manejador que utilizaremos en este tutorial para enviar mensajes desde servicios externos hacia Kommo.

¿Por dónde empezar?

Primero, necesitas entender que trabajar con widget_request requiere tener un widget cargado para tu integración e inicializado dentro de la ubicación de Salesbot.

❗️

¡Necesitas tener al menos el planAvanzado para utilizar WebSDK y cargar widgets personalizados a tu cuenta de Kommo!


1. Crea una integración

Comienza creando una integración en tu cuenta de Kommo siguiendo estos pasos:

  • Inicia sesión como administrador de la cuenta

  • Ve a Ajustes → Integración

  • Haz clic en el butón Crear integración

  • Envía el formulario simple. Consulta más información sobre cómo crear una integración privada aquí.

2. Crea tu widget

Un widget es un componente de interfaz de usuario que se utiliza para mostrar datos en áreas específicas, interactuar con los usuarios o ajustar configuraciones por parte de los administradores.

Crea tu widget de acuerdo con la documentación.

3. Widget en el Salesbot

Para que tu widget funcione dentro del Salesbot, no olvides agregar todas las ubicaciones y objetos necesarios en los archivos de tu widget. Lee más sobre el SDK del Salesbot aquí.

manifest.json

  1. Especifica la ubicación del salesbot_designer
{
  ...

  "locations": [
    "salesbot_designer"
  ],

  ...
}
  1. Añade el objeto salesbot_designer
"salesbot_designer": {
  "logo": "/widgets/my_widget/images/image.jpg",
  "handler_name": {
    "name": "settings.handler_name",
    "settings": {
      "text": {
        "name": "settings.text",
        "default_value": "¡Hola, soy el Salesbot!",
        "type": "text",
        "manual": true, // true - el usuario debe ingresar un valor,
 // false - el usuario selecciona un valor de campo.
      },
      "link_to": {
        "name": "settings.link",
        "default_value": "www.kommo.com",
        "type": "url",
      }
    }
  }
}

Este objeto describe los campos que se mostrarán en la interfaz de configuración del widget dentro del diseñador de Salesbot.:

Los campos dentro de la propiedad settings pueden tener los siguientes tipos:

  • texto
  • numérico
  • url (enlace)

Si estas configuraciones están especificadas correctamente, el widget aparecerá en la ventana modal del diseñador de widgets de Salesbot, por ejemplo:

Ejemplo de un widget en Salesbot paso personalizado

Ejemplo de un widget en Salesbot paso personalizado

script.js

Las configuraciones para cada manejador se especifican en el archivo manifest.json y luego se utilizan en el código del Salesbot. Se pueden añadir los siguientes callbacks al archivo script.js:

onSalesbotDesignerSave

Después de que el usuario haya configurado su secuencia en el diseñador de Salesbot y haya hecho clic en el botón Guardar, el callback onSalesbotDesignerSave se ejecuta dentro del widget.

Este método debe retornar una cadena en formato JSON que represente el flujo del Salesbot, tomando en cuenta los códigos de salida del bot.

Recibe los siguientes parámetros:

  • handler_code (el código del manejador definido en el objeto salesbot_designer)
  • params (la configuración del widget en el formato especificado)
onSalesbotDesignerSave: function (handler_code, params) {
  const salesbot_source = {
      question: [],
      require: [],
    },
    values = [];
  salesbot_source.question.push({ type: 'texto' });

  $.each(params, (param) => {
    values.push(param);
  });

  salesbot_source.question.push({
    values: values,
  });

  salesbot_source.question.push({ accept_unsorted: 'false' });
  return JSON.stringify([salesbot_source]);
};
onSalesbotDesignerSave: function (handler_code, params) {
  const request_data = {
    message: params.message,
  };

  if (APP.getBaseEntity() === 'lead') {
    request_data.lead = '{{lead.id}}';
  };

  return JSON.stringify([
    {
      question: [
        {
          handler: 'widget_request',
          params: {
            url: 'https://example.com/webhook',
            data: request_data,
          },
        },
        {
          handler: 'goto',
          params: {
            type: 'question',
            step: 1,
          },
        },
      ],
    },
    {
      question: [
        {
          handler: 'conditions',
          params: {
            logic: 'and',
            conditions: [
              {
                term1: '{{json.status}}',
                term2: 'success',
                operation: '=',
              },
            ],
            result: [
              {
                handler: 'exits',
                params: {
                  value: 'success',
                },
              },
            ],
          },
        },
        {
          handler: 'exits',
          params: {
            value: 'fail',
          },
        },
      ],
    },
  ]);
},

salesbotDesignerSettings

Cuando el usuario hace clic en el botón Agregar debajo del widget, se activa el callback salesbotDesignerSettings. Al utilizar este callback, puedes modificar la apariencia del bloque de tu widget dentro del diseñador.

🚧

No abordaremos el callback salesbotDesignerSettingsen este tutorial, pero puedes encontrar más información sobre este callback en la sección del SDK del Salesbot.

4. widget_request webhook

La estructura del manejador widget_requestse muestra a continuación. Puedes especificar qué datos enviar desde Kommo a tu servidor; los, placeholders del manejador show se pueden usar para pasar datos dinámicos. Supongamos que quieres enviar el mensaje del cliente a tu widget. Esto puede lograrse proporcionando el placeholder {{message_text}} como valor de la clave data.message.

📘

Puedes añadir más de una clave al objeto params.data

{
  "handler": "widget_request",
  "params": {
    "url": "https://example.com/endpoint",
    "data": {
      "message": "{{message_text}}",
      "from": "widget"
    }
  }
}
onSalesbotDesignerSave: (_handler_code, params) => {
        const hookUrl = params?.text || '';
        const requestData = { from: 'widget', message: '{{message_text}}' };

        const firstStep = createStep([
          {
            handler: 'widget_request',
            params: {
              url: hookUrl,
              data: requestData,
            }
          }
        ]);

        const flow = [firstStep];

        return JSON.stringify(flow);
      }
ParámetroTipo de datoDescripción
urlstringLa URL del endpoint del servidor externo.
dataarrayUn arreglo con cualquier dato que contenga cadenas y/o placeholders desde la sección del manejador "show", por ejemplo, "{{message_text}}".

Cuando el paso del widget se activa en el flujo del Salesbot, los datos del paso anterior se enviarán a la URL especificada. El endpoint definido en url recibirá una solicitud POST. Para confirmar que el webhook fue recibido correctamente, debes responder dentro de los 2 segundos con un código de estado HTTP 200.

{
      "token": "JWT_TOKEN",
      "data": {
        "message": "¡Hola! ¿Cómo estás?",
        "from": "widget"
      },
      "return_url": "https://subdomain.kommo.com/api/v4/salesbot/321/continue/123"
    }

El token JWT es necesario para validar los datos enviados en la solicitud. Está firmado con la clave secreta.

5. Respuesta del widget y reanudación del flujo del bot

Una vez que el webhook ha sido recibido y procesado correctamente por tu servidor, puedes enviar datos de regreso a Kommo y continuar el flujo del Salesbot. Para reanudar la operación del bot, necesitas hacer una solicitud con los datos. El bot actual no continuará su operación hasta que reciba dicha solicitud. Además, no podrás continuar la ejecución si otro bot ya se encuentra activo para la misma entidad.

Si el widget necesita enviar datos, estos deben colocarse en el campo data como un objeto dentro de la solicitud. Si el widget debe realizar alguna acción antes de que el bot continúe funcionando, puedes pasar una lista de manejadores al parámetro execute_handlers, por ejemplo:

{
  "data": {
      "message": "¡Hola! ¿Cómo estas?"
  },
  "execute_handlers": [
      {
          "handler": "show",
          "params": {
              "type": "text",
              "value": "Tu texto"
          }
      },
      {
          "handler": "show",
          "params": {
              "type": "buttons",
              "value": "Presiona el botón",
              "buttons": [
                  "Botón 1",
                  "Botón 2",
                  "Botón 3",
                  "Botón 4",
                  ...
                  "Botón 25"
              ]
          }
      },
      {
          "handler": "show",
          "params": {
              "type": "buttons_url",
              "value": "Botones con enlaces",
              "buttons": [
                  "https://kommo.com"
              ]
          }
      },
      {
          "handler": "goto",
          "params": {
              "type": "question|answer|finish",
              "step": 5
          }
      }
  ]
}

En el ejemplo anterior, hemos enviado un campo message field to the widget. al widget. El widget podrá acceder al valor de ese campo (message) en cualquier bloque posterior al paso del Widget usando la clave {{json.message}}. Además, le hemos indicado al bot del widget que muestre texto, botones, botones con enlaces y que avance al paso 5 del bot del widget.

Ejemplo

Hemos preparado ejemplos de los archivos script.js, manifest.json y i18n/en para mostrar un flujo simple en el que el Salesbot envía mensajes desde servicios externos.

🚧

Recuerda que este widget es solo un ejemplo y no una integración lista para producción. ¡Debes crear el flujo del Salesbot por tu cuenta también!

{
  "widget": {
    "name": "widget.name",
    "description": "widget.description",
    "short_description": "widget.short_description",
    "version": "1.0.1",
    "interface_version": 2,
    "init_once": true,
    "locale": ["en"],
    "installation": true,
    "support": {
      "link": "https://www.example.com",
      "email": "[email protected]"
    }
  },

  "locations": ["salesbot_designer"],
  
  "tour": {
    "is_tour": true,
    "tour_images": {
      "en": ["/images/tour_1_en.png"]
    },
    "tour_description": "widget.tour_description"
  },

  "settings": {
    "login": {
      "name": "settings.login",
      "type": "text",
      "required": false
    },
    "password": {
      "name": "settings.password",
      "type": "text",
      "required": false
    }
  },

  "salesbot_designer": {
    "logo": "/widgets/my_widget/images/image.jpg", 
    "handler_name": {
      "name": "salesbot.handler_name",
      "settings": {
        "text": {
          "name": "salesbot.text",
          "default_value": "https://webhook.site/",
          "type": "text",
          "manual": true
        }
      }
    }
  }
}

define(['jquery'], function ($) {
  return function CustomWidget() {
    const self = this;

    const createStep = (questions) => ({ question: questions, require: [] });

    this.callbacks = {
      settings: () => {},
      init: () => true,
      bind_actions: () => true,
      render: () => true,

      onSalesbotDesignerSave: (_handler_code, params) => {
        const hookUrl = params?.text || '';
        const requestData = { from: 'widget', message: '{{message_text}}' };

        const firstStep = createStep([
          {
            handler: 'widget_request',
            params: {
              url: hookUrl,
              data: requestData,
            },
          }
        ]);

        const flow = [firstStep, createConditionStep()];

        return JSON.stringify(flow);
      },

      destroy: () => {},
      onSave: () => true,
    };

    return this;
  };
});

{
  "widget": {
    "name": "Ejemplo de widget",
    "short_description": "Es una descripción corta",
    "description": "Esta es una descripción completa",
    "tour_description": "Descripción del recorrido del widget"
  },

  "settings": {
    "login": "Usuario",
    "password": "Contraseña"
  },

  "salesbot": {
    "handler_name": "Nombre del manejador",
    "text": "Texto",
    "message": "Mensaje"
  }
}

Una vez que el widget esté cargado en tu cuenta, ve a Salesbot y selecciona tu widget en el paso widget. Allí tendrás la opción de especificar la URL del webhook en el editor visual.

Para activar tu Salesbot, también puedes utilizar el webhook general para cada mensaje entrante en tu cuenta y luego enviar una solicitud para lanzar un Salesbot vía API para la entidad correspondiente.

Updated 3 days ago