Autorização Kommo

Como nossa integração utiliza OAuth 2.0 para a autorização, após concluir o setup como descrito no nossso guia de passo-a-passo, um código de autorização vai ser gerado. Esse código deve então ser trocado por um par de tokens de accesse refresh. Esses tokens devem ser armazenados em segurança no seu banco de dados, junto de suas datas de expiração.

🚧

Por favor, note que um mesmo usuário pode instalar a integração em múltiplas contas. Integradores devem garantir um forte isolamento de dados entre as contas pra previnir qualquer vazamento de dados ou acesso não autorizado entre contas pertencentes ao mesmo usuário.

Uma vez que a integração esteja instalada, a janela de configurações irá aparecer com campos a serem preenchidos por um administrador da conta. A Kommo só considera como bem sucedida a configuração de uma integração, quando os ajustes são salvos corretamente. Isso é implementado na interface do usuário (UI/UX) chamando uma função de callback onSave quando um adminisrador salva os ajustes da integração. A função deve retornar o valor true se o widget for configurado com sucesso, e false caso não seja.

function CustomWidget() {
  const self = this;

  self.clickSaveButton = function () {
    /*
     * Essa função define as ações executadas
     * quando o botão é clicado. 
     */
    const $save_button = $(document).find(".js-widget-save");

    $save_button.click();
  };

  /**
   * Um objeto contendo callbacks específicos do widget.
   * Obtenha mais informações sobre os callbacks aqui: https://developers.kommo.com/docs/script-js
   */
  this.callbacks = {
    /**
     * Callback que é disparado quando o botão ".js-widget-save" é clicado.
     */
    onSave: (widgetConfiguration) => {
      const { active, fields } = widgetConfiguration;

      /**
       * Aqui você pode especificar uma condição que determina
       * se o widget está pronto pra configuração.
       */
      const isWidgetConfiguredByCRM = active.toLowerCase() === "y";

      /**
       * O manifest.json especifica os nomes dos campos exibidos nos ajustes.
       * Esses nomes são as chaves do objeto "fields".
       * Os valores dessas chaves correspondem aos valores inseridos
       * no momento em que o callback onSave é disparado.
       */
      const { login, password } = fields;

      const areFieldsFilled = login && password;

      const isWidgetReady = isWidgetConfiguredByCRM && areFieldsFilled;

      if (isWidgetReady) {
        alert("Suas configurações de integração foram salvas com sucesso!");

        /**
         * Retorna "true" se o widget estiver pronto.
         */
        return true;
      }

      alert("Kommo não conseguiu registrar seu widget.");

      /**
       * Caso não, retorna "false".
       */
      return false;
    },
  };

  return this;
}

Lembre-se de não usar o subdomínio da conta como chave primária nas suas configurações, pois ele pode ser alterado. Também recomendamos não usar o ID da conta para esse propósito. A melhor decisão é utilizar um campo ID autoincrementável como chave primária, enquanto o ID da conta e o subdomínio serão apenas propriedades int e string, respectivamente. Para mais informações sobre configuração, consulte o artigo de Configuração do widget.

Autorização do serviço VoIP

Após o usuário instalar a integração pelo Marketplace da Kommo, a integração deve exibir uma janela modal de configurações, onde o usuário pode realizar ações como fornecer as credenciais de acesso ao serviço VoIP. Essas credenciais são conhecidas apenas pelo administrador da conta VoIP.

Outra opção é utilizar OAuth 2.0 para autorização.

É necessário salvar as informações de autorização para chamadas futuras à API do serviço. A partir desse momento, o widget pode ser considerado ativo.

Configuração da integração

A configuração de tratamento de chamadas permite definir como o sistema responde a diferentes tipos de chamadas e ações do usuário. As configurações disponíveis podem incluir: habilitar o som de toque, fornecer feedback de chamada, abrir automaticamente o cartão do cliente ao receber uma chamada, permitir que usuários avaliem a qualidade da chamada.

Administradores também podem configurar o comportamento em diferentes cenários, como: chamada de número conhecido ou desconhecido, chamadas atendidas ou perdidas. Essa flexibilidade permite que o sistema se adapte a diversos fluxos de trabalho e processos de negócio.

Quando uma chamada é recebida de um número desconhecido, o sistema pode: criar automaticamente um novo contato e lead, ou registrar a chamada como um lead de entrada (incoming lead). Os gerentes podem escolher entre aceitar esse lead manualmente ou permitir aceitação automática quando a chamada for atendida.

Quando a chamada é recebida de contatos conhecidos, A configuração pode incluir: criar automaticamente um lead se não houver um lead ativo, e adicionar o número da chamada à nota caso o contato tenha múltiplos telefones.

Quando um gerente perde uma chamada, o sistema pode: criar uma tarefa automática, definir o prazo, vincular à lead relevante ou atribuir a um responsável.

Para chamadas realizadas para números novos, ao efetuar uma chamada para um número que ainda não existe na base, o sistema pode: criar automaticamente um novo contato, criar automaticamente um novo lead.

Representação de dados

Exemplo de informações que você pode armazenar no seu banco de dados:

kommo_auth_tokens

voip_users

voip_calls

widget_settings

Entities

Durante o desenvolvimento, precisamos declarar algumas entidades:

Call

FromWebhook