Neste tutorial, você aprenderá a usar os recursos do seu Salesbot para enviar mensagens de serviços externos para os seus canais de chat da Kommo.

O caso mais comum é conectar algum serviço de LLM à Kommo para analisar as mensagens que chegam à sua conta por meio de alguns canais de chat e, em seguida, fornecer respostas a elas, elaboradas pelo LLM.

❗️

Os métodos da API de Chats não permitirão que você faça o mesmo, pois cada integração tem seu próprio canal de chat e você não pode acessá-los pelo seu canal personalizado. Você pode enviar mensagens manualmente ou pelo Salesbot para esses canais.

Salesbot para envio de mensagens

Salesbot é um bot que pode ser programado para executar determinadas ações na Kommo. Ele ajuda a receber dados de usuários por meio de aplicativos de mensagens (Telegram, Facebook Messenger, Instagram) e envia mensagens para qualquer canal de chat conectado à sua conta Kommo.

O Salesbot também possui vários handlers que podem ser úteis para aprimorar sua funcionalidade. Por exemplo, o manipulador widget_request permite enviar webhooks para URLs externas com os dados especificados da Kommo para o seu widget e obter uma resposta do seu widget de volta para a Kommo.

📘

widget_request é um manipulador que usaremos neste tutorial para enviar mensagens de serviços externos para a Kommo.

Por onde começar?

Primeiro, você precisa entender que trabalhar com widget_request requer que você tenha um widget carregado para sua integração e inicializado dentro do Salesbot.

❗️

Você precisa ter pelo menos o plano Avançado para usar o WebSDK e carregar widgets personalizados para sua conta Kommo!

1. Crie uma integração

Comece criando uma integração na sua conta Kommo seguindo os passos:

• Faça login como administrador da conta
• Acesse Configurações → Integrações
• Clique no botão Criar integração
• Envie o formulário simples. Veja mais informações sobre como criar uma integração privada aqui.

2. Crie seu widget

Um widget é um componente de interface do usuário usado para exibir dados em áreas específicas, interagir com usuários ou ajustar configurações por administradores.

Crie seu widget de acordo com a documentação.

3. Widget no Salesbot

Para que seu widget funcione no Salesbot, não se esqueça de adicionar todos os locais e objetos necessários aos seus arquivos de widget. Leia mais sobre o SDK do Salesbot aqui.

1. 1. Especifique o salesbot_designer Localizações.
   JSON

   {
     ...
   
     "locations": [
       "salesbot_designer"
     ],
   
     ...
   }

   2. Adicione o salesbot_designer objecto.
   JSON

   "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 descreve os campos para exibir a interface de configurações do widget no Designer do Salesbot:

Os campos na propriedade settings podem ter as seguintes opções de tipo:

• texto
• numérico
• url (link)

Se essas configurações forem especificadas corretamente, o widget aparecerá na janela modal dos widgets do Designer do Salesbot, por exemplo:

script.js

As configurações de cada manipulador são especificadas no arquivo manifest.json e, em seguida, usadas no código do Salesbot. Os seguintes retornos de chamada podem ser adicionados ao script.js:

onSalesbotDesignerSave

Após o usuário configurar sua sequência no designer do Salesbot e clicar no botão Salvar, o retorno de chamada onSalesbotDesignerSave é executado no widget.

O método deve retornar uma string no formato de código JSON para o Salesbot, levando em consideração os códigos de saída do bot.

Ele aceita as seguintes entradas:

• handler_code (o código do manipulador do objeto no salesbot_designer) objeto)
• params (as configurações do widget no formato especificado)

javascript Example 1
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]);
};
```
```javascript Example 2
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

Quando o usuário clicar no botão Adicionar abaixo do widget, o retorno de chamada salesbotDesignerSettings será acionado. Usando esse retorno de chamada, você pode alterar a aparência do bloco do seu widget no designer.

🚧

Não abordaremos o retorno de chamada salesbotDesignerSettings neste tutorial, mas você pode encontrar mais informações sobre ele na seção Salesbot SDK.

4. widget_request webhook

A estrutura do manipulador widget_request é apresentada abaixo. Você pode especificar quais dados enviar da Kommo para o seu servidor. Os do manipulador show podem ser usados para passar dados dinâmicos. Digamos que você queira passar uma mensagem do cliente para o seu widget. Isso pode ser feito fornecendo o espaço reservado {{message_text}} para nossa chave 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);
      }

Quando a etapa Widget for acionada no fluxo do Salesbot, os dados da etapa anterior serão passados para a URL especificada. O ponto final url receberá uma solicitação POST. Para confirmar que o webhook foi recebido, você precisa responder em até 2 segundos com um código de status HTTP 200.

{
      "token": "JWT_TOKEN",
      "data": {
        "message"": "Olá! Como vai?",
        "from": "widget"
      },
      "return_url": "https://subdomain.kommo.com/api/v4/salesbot/321/continue/123"
}

O token JWT é necessário para validar os dados enviados na solicitação. Ele é assinado com a chave secreta do cliente.

5. Resposta do Widget e Retomada das Operações do Bot

Assim que o webhook for recebido e processado com sucesso no seu servidor, você poderá enviar os dados de volta para a Kommo e continuar o fluxo do Salesbot. Para retomar a operação do bot, você precisa fazer uma requisição com os dados. O bot atual não continuará sua operação até receber a solicitação. Além disso, você não poderá continuar a execução do bot se outro bot para a mesma entidade já estiver em execução.

Se o widget precisar enviar algum dado, ele deverá ser inserido no campo data como um objeto dentro de solicitação. Se o widget precisar executar uma ação antes que o bot continue trabalhando, você pode passar uma lista de manipuladores para o parâmetro execute_handlers, por exemplo:

{
  "data": {
      "message": "Olá! Como vai?"
  },
  "execute_handlers": [
      {
          "handler": "show",
          "params": {
              "type": "text",
              "value": "Seu texto"
          }
      },
      {
          "handler": "show",
          "params": {
              "type": "buttons",
              "value": "Pressione o botão",
              "buttons": [
                  "Botão 1",
                  "Botão  2",
                  "Botão 3",
                  "Botão 4",
                  ...
                  "Botão 25"
              ]
          }
      },
      {
          "handler": "show",
          "params": {
              "type": "buttons_url",
              "value": "Botoões com links",
              "buttons": [
                  "https://kommo.com"
              ]
          }
      },
      {
          "handler": "goto",
          "params": {
              "type": "question|answer|finish",
              "step": 5
          }
      }
  ]
}

No exemplo acima, passamos um Campo message para o widget. O widget poderá obter o valor do campo (message) em qualquer bloco após a etapa Widget, através da chave {{json.message}}. Também instruímos o bot do widget a exibir texto, botões, botões com links e prosseguir para a etapa 5 do bot do widget.

Exemplo

Preparamos exemplos para os arquivos script.js, manifest.json e i18n/en para mostrar um fluxo simples do Salesbot enviando mensagens de serviços externos.

🚧

Lembre-se de que este widget é apenas um exemplo, e não uma integração pronta para o negócio. Você também precisa criar um fluxo do Salesbot!

{
  "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": "Widget exemplo",
    "short_description": "É uma descrição curta!",
    "description": "Essa é uma descrição completa!",
    "tour_description": "Descrições de tour do widget"
  },

  "settings": {
    "login": "Login do usuário",
    "password": "Senha"
  },

  "salesbot": {
    "handler_name": "Nome do Handler",
    "text": "Texto",
    "message": "Mensagem"
  }
}

Após o upload do widget para sua conta, acesse o Salesbot e escolha seu widget na etapa "Widget". Aqui, você verá uma etapa com a possibilidade de especificar a URL do seu webhook no editor de interface do usuário.

Para acionar seu Salesbot, você também pode usar um webhook geral em cada mensagem recebida da sua conta e, em seguida, enviar uma solicitação para lançar um Salesbot via API para a entidade.