🚨Web V1 [Obsoleto]

Uma das maneiras mais comuns de disponibilizar um bot para seus clientes é por meio de um widget de chat. Neste guia técnico, iremos orientá-lo através do processo de integração do bot em seu site.

Criando seu widget de chat web

Para criar um widget de chat para seu bot, navegue até a aba Canais e clique no ícone de lápis ao lado de Web.

Clique "+ Create" para começar a construir seu primeiro widget de chat personalizado.

Na página do Chat Widget você pode personalizar diversos componentes-chave do widget de chat:

• Aba Config

  • Título do bot

  • Modelo

  • Carregar CSS personalizado (mais informações sobre CSS personalizado aqui)

  • Fonte do título e tamanho da fonte

  • Fonte do parágrafo e tamanho da fonte

  • Lista branca dos domínios nos quais você deseja que o bot seja ativado (por exemplo, o domínio do seu próprio site e quaisquer outros domínios que você use para testes)

  • Imagens (título, bot, usuário, ícone de envio, botão SDK - que é a imagem exibida quando o bot está fechado)

• Aba Cores

  • Cores de todos os componentes principais do chatbot

• Aba Traduções

  • Traduções para as mensagens padrão do widget de chat, como "Write reply..."

Listagem branca

Para garantir que seu bot só possa ser ativado no seu site, todos os seus widgets de chat devem estar na lista branca antes de você poder usá-los. Para isso, vá até a aba config do construtor de Chat Widget e adicione uma expressão regular que corresponda aos nomes de domínio que você deseja colocar na lista branca.

Um exemplo simples deste formato de regex para https://www.chatlayer.ai: ^https:\/\/www\.chatlayer\.ai(\/|$)

As regexes de lista branca também podem ser usadas para configurações mais complexas e com múltiplos domínios. Tome o seguinte conjunto de domínios como exemplo:^https:\/\/www\.(subdomain1|subdomain2)\.(rootdomain1|rootdomain2)\.com(\/|$) irá colocar na lista branca os domínios:

• https://www.subdomain1.rootdomain1.com

• https://www.subdomain1.rootdomain2.com

• https://www.subdomain2.rootdomain1.com

• https://www.subdomain2.rootdomain2.com

Você pode separar as alternativas usando um | caractere da seguinte forma:

^https:\/\/www\.subdomain1\.rootdomain1\.com(\/|$)|^https:\/\/www\.subdomain2\.rootdomain1\.com(\/|$)|^https:\/\/www\.subdomain1\.rootdomain2\.com(\/|$)|^https:\/\/www\.subdomain2\.rootdomain2\.com(\/|$)

Uma expressão regular mais curta que corresponderá aos mesmos domínios é:

^https:\/\/www\.(subdomain1|subdomain2)\.(rootdomain1|rootdomain2)\.com(\/|$)

Uma maneira fácil de validar sua expressão regular é usando ferramentas online como https://regex101.com/

Listagem branca com um iframe

Alguns navegadores têm um referrerpolicy padrão de strict-origin-when-cross-origin. Isso fará com que o navegador inclua apenas a origem da sua página ao solicitar o conteúdo de um iframe.

Se o seu widget em iframe estiver hospedado em https://example.com/chat_widget.html, as requisições conterão apenas a https://example.com/ porção desse caminho. Isso pode causar problemas se você usar uma regex de lista branca que corresponda ao caminho completo da sua página, por exemplo:

^https:\/\/example\.com\/chat_widget.html

Se você quiser usar o caminho completo da sua página na configuração de lista branca do seu widget, você pode sobrescrever a referrerpolicy do iframe que contém o link para seu widget para no-referrer-when-downgrade

<iframe referrerpolicy="no-referrer-when-downgrade" src="<CHATBOX_URL>"/>

Mais informações sobre políticas de referrer podem ser encontradas aqui.

Incorporando o widget web no seu site

Para incorporar o bot em seu site, comece clicando no botão Embed no canto superior direito da página Custom Chat Widget.

Existem duas maneiras de integrar o Chat Widget no seu site: você pode usar iframe ou SDK.

Você pode alternar entre SDK e iframe usando o seletor Type acima do seu widget:

Devo usar SDK ou iframe?

Nosso SDK do widget de chat é uma camada sobre um iframe, que inclui algumas outras funcionalidades, como um botão exibido antes da janela de chat abrir, com a opção de fechar o chatbot.

Se você deseja inserir o widget de chat no seu site com desenvolvimento personalizado mínimo, é melhor usar um SDK. A única coisa que você precisa fazer é incluir uma tag de script HTML conforme descrito abaixo.

Se você quiser mais controle sobre outros elementos, como o botão de chat, é melhor usar iframe.

SDK

Você pode carregar o widget de chat usando a tag de script abaixo. Chamar a função chatlayer mostrará o botão e seu widget de chat na página.

<script src="https://chatbox.staging.chatlayer.ai/sdk/INSERT-TOKEN-HERE" 
        onload='chatlayer()' async>
    // O token pode ser encontrado na janela de configuração do Chat Widget
</script>

Remova .staging da URL se você quiser integrar um bot LIVE. Você pode adicionar parâmetros à função chatlayer para incluir funcionalidades adicionais.

<script src="https://chatbox.staging.chatlayer.ai/sdk/INSERT-TOKEN-HERE" 
        onload='chatlayer({"lang":"en","animation":"grow"})' async>
</script>

Neste caso, seu bot será aberto em inglês, e quando um usuário clicar no botão do SDK, ele será aberto com a animação Grow.

Opções do SDK

Transferindo uma variável do seu site, através do SDK, para o chatbot

Se você quiser transferir dados do seu site para o chatbot, você pode adicionar esses dados à função chatlayer Todas as informações serão colocadas na variável sessão na sessão do Chatlayer.ai. Esses dados podem então ser usados para personalizar o fluxo do chatbot, com base em dados reais do site.

<script src="https://chatbox.staging.chatlayer.ai/sdk/INSERT-TOKEN-HERE"
 onload='chatlayer({session: {number: 1234, firstName: "User", lastName: "Name" }})' async>
</script>

Transferindo as variáveis firstName e lastName para o SDK permite que você defina as variáveis internas correspondentes da sessão do Chatlayer. Essas variáveis específicas decidem como o usuário será exibido na tabela de conversas do Chatlayer.

internal: {
  ...
  user: {
      firstName: 'User',
      lastName: 'Name',
        },
        ...
    },
    ...
 session: {
     number: 1234,
     firstName: 'User',
     lastName: 'Name'
    }
    ...
    firstname: 'User',
    lastname: 'Name'
}

Autenticação do usuário com o SDK do widget de chat

Em muitos casos é necessário saber quem está conversando com o bot. Uma maneira de descobrir isso é enviando um ID de login, detectado no site em que seu usuário está logado, e repassando-o ao bot quando o SDK for inicializado:

<script src="YOUR_CHATWIDGET_URL" 
onload='chatlayer({ sessionId: LoginID }})' async>
</script>

Esse ID de login pode mais tarde ser reutilizado para realizar chamadas com o plugin de API.

Comportamento do botão do widget de chat

Se você importar o widget de chat com nosso SDK, você pode decidir quando o widget abre ou fecha. Um exemplo:

var chatlayerChat = chatlayer({ lang: 'en'});
// Isso cria uma instância do Chatlayer.ai e adiciona o ícone à sua página

chatlayerChat.open();
// Abre a janela de chat do Chatlayer.ai
setTimeout(()=>chatlayerChat.open(),10000)
// Abre a janela de chat do Chatlayer.ai com um atraso predefinido
chatlayerChat.toggle();
// Alterna entre a versão aberta e fechada do widget de chat
chatlayerChat.close();
// Minimiza a janela do widget de chat para o botão

Iframe

Incorporar o widget de chat em um iframe é a opção de incorporação mais direta. Você determina como e onde posicionar o elemento e pode estilizar como desejar.

<iframe src="https://chatbox.staging.chatlayer.ai/INSERT-TOKEN-HERE?lang=en"/>

Remova .staging da URL se você quiser integrar um bot de produção. Você pode alterar ?lang=en para qualquer idioma que o bot suporte.

Definindo o sender ID

Se você quiser reconhecer um usuário que retorna ao bot, você pode enviar um sender ID único para cada pessoa que abre o bot, que então pode ser usado para abrir a mesma conversa quando a página for recarregada.

<iframe src="https://chatbox.staging.chatlayer.ai/TOKEN?senderId=5241bbd5-6fd8-4333-85e0-72bsdf04f4c91"/>

Certifique-se de que seu sender ID tenha 20 caracteres ou mais.

Transferindo uma variável do seu site, através do iframe, para o chatbot

A sessão de um usuário pode ser atualizada a qualquer momento através da Enviar mensagens através de um canal Webhook chamada de API.

O mesmo objetivo também pode ser alcançado alterando a URL do iframe:

<iframe src="https://chatbox.staging.chatlayer.ai/TOKEN?senderId=12345TEST&session[data][first_name]=Charlie"/>

O exemplo acima resultaria em uma sessão contendo:

{
   "id":"1234TEST",
   "session":{
      "data":{
         "first_name":"Charlie"
      }
   }
}

Tamanho e posição do iframe

Adicionando as propriedades abaixo ao seu CSS, você pode redimensionar a janela do widget de chat. Você pode usar esses parâmetros para tornar o widget de chat responsivo para dispositivos móveis.

<style>
    iframe.chatlayer-iframe {
        width: 350px
        max-width: 100%;
        max-height: 560px;
    }
</style>

Criptografia

Existem duas opções principais para proteger o widget de chat. Você pode verificar o payload usando JWT, garantindo que ele não tenha sido adulterado, ou pode criptografar a sessão criada pelo widget de chat usando proteção de dados AES-256.

Quando você ativa a proteção de dados AES-256, só é possível passar um token criptografado como a sessão de chat. Esse token deve ser gerado em seu próprio back-end. O código para gerar o token é o seguinte (usando node.js):

const crypto = require('crypto');
const SECRET = 'CHATLAYER_TOKEN'
const createAESToken = (payload, secret = SECRET) => {
    const iv = Buffer.from(crypto.randomBytes(8)).toString('hex');
    const secretBuffer = Buffer.from(secret, 'hex');
    const cipher = crypto.createCipheriv('aes-256-cbc', secretBuffer, iv);
    const update = cipher.update(typeof payload === 'object' ? JSON.stringify(payload) : String(payload));
    const encrypted = Buffer.concat([update, cipher.final()]);
    return iv + encrypted.toString('hex');
};
const token = createAESToken({
    exp: Math.floor(Date.now() / 1000) + 36000,
    session: {
        isAuthorized: true
    },
    sessionId: 'UNIQUE_ID_FOR_THIS_USER'
});

Como você passa esse token para o cliente dependerá de como você está gerando seu HTML, mas esse token gerado no servidor deve ser o que é passado para a função chatlayer:const chat = chatlayer({token: serverGeneratedToken});

Exemplo ao vivo

Criamos um exemplo de como você pode inicializar e destruir o widget de chat do Chatlayer.ai através do seu próprio código Javascript.

<html>
  <head>
    <title>Chatlayer Events Example</title>
    <meta charset="UTF-8" />
  </head>

  <body>
    <button onclick="initChatlayer()">Inicializar Chatlayer</button>
    <button onclick="destroyChatlayer()">Destruir Chatlayer</button>
    <br />
    <br />
    <button onclick="openChatlayer()">Abrir Widget do Chatlayer</button>
    <button onclick="closeChatlayer()">Fechar Widget do Chatlayer</button>

    <script>
      /**
       * Este exemplo demonstra a destruição de um webwidget do Chatlayer
       * acionando o plugin JSON builder no fluxo.
       *
       * A caixa de diálogo da ação JSON builder foi configurada da seguinte forma:
       * https://minio.dev.chatlayer.ai/public/JSONBuilder.png
       *
       */

      let chatlayerInstance = null;

      const initChatlayer = () => {
        if (chatlayerInstance) return;
        console.log("Inicializando o widget Chatlayer ...");
        chatlayerInstance = chatlayer({ lang: "en" });
        // Os tipos de evento são "event", "open" e "close"

        chatlayerInstance.on("open", event => {
          console.log('OPENED');
        });

        chatlayerInstance.on("close", event => {
          console.log('CLOSED')
        });

        chatlayerInstance.on("event", event => {
          // Observe o conteúdo do event aqui: a chave "action" com valor "destroy"
          // se origina diretamente da ação do JSON Builder configurada.
          const isChatlayerDestroyEvent = event.action === "destroy";
          if (isChatlayerDestroyEvent) {
            destroyChatlayer();
          }
        });
      };

      const destroyChatlayer = () => {
        if (!chatlayerInstance) return;
        console.log("Destruindo o widget Chatlayer ...");
        // Para destruir o widget, ele precisa ser aberto primeiro
        chatlayerInstance.open();
        chatlayerInstance.destroy();
        chatlayerInstance = null;
      };

      const openChatlayer = () => {
        if (!chatlayerInstance) {
          console.log("Por favor, inicialize o Chatlayer primeiro!");
          return;
        }
        chatlayerInstance.open();
      };

      const closeChatlayer = () => {
        if (!chatlayerInstance) {
          console.log("Por favor, inicialize o Chatlayer primeiro!");
          return;
        }
        chatlayerInstance.close();
      };
    </script>

    <!-- Observe a ausência da propriedade onload na tag de script a seguir. -->
    <!-- Para inicializar automaticamente o webwidget, você adicionaria a propriedade: -->
    <!-- onload="initChatlayer()" -->
    <script
      src="https://chatbox.staging.chatlayer.ai/sdk/5ecbcf1514c3dc4942f05f96"
      async
    ></script>
  </body>
</html>

Configuração do plugin JSON builder:

Como você pode ver no exemplo acima, você pode inicializar o widget, abri-lo/fechá-lo, bem como destruí-lo a partir do seu próprio código. O exemplo mostra como usar o plugin JSON Builder para acionar um evento de destruição para o widget de chat.