🚫Web V1 [Encerramento]

Este canal foi aposentado em: 16/09/2025.

A partir de 31 de outubro de 2024, todos os clientes Chatlayer que utilizam o canal Web precisarão migrar para o novo widget web, Web V2. Isso significa que o Web V1 será removido da nossa base de código. Saiba tudo sobre migrar do V1 para o V2.

Atenção:

Este artigo se refere ao nosso widget web legado, que será descontinuado em 01/10/2024. Em 01/04/2024, interromperemos o suporte ao widget de chat web V1. Todos os widgets web criados recentemente devem seguir a documentação do Web V2.

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 no processo de integração do bot no seu site.

Criando seu widget de chat web

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

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

Você pode criar múltiplos widgets de chat para um bot, removê-los, visualizá-los e copiá-los usando os botões na tabela de widgets de chat.

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

• Aba Config

  • Título do bot

  • Modelo

  • Fazer upload de CSS customizado (mais informações sobre CSS customizado aqui)

  • Fonte e tamanho da fonte do título

  • Fonte e tamanho da fonte do parágrafo

  • Lista branca (whitelist) dos domínios nos quais você quer 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 do SDK - que é a imagem mostrada quando o bot está fechado)

• Aba Cores

  • Cores de todos os componentes principais do chatbot

• Aba Traduções

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

Whitelist

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

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

Regexes de whitelist também podem ser usados para configurações mais complexas e com múltiplos domínios. Considere o seguinte conjunto de domínios como exemplo:^https:\/\/www\.(subdomain1|subdomain2)\.(rootdomain1|rootdomain2)\.com(\/|$) irá colocar na whitelist 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/

Whitelist com um iframe

Alguns navegadores têm uma 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 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 um regex de whitelist 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 whitelist do seu widget, você pode sobrescrever a referrerpolicy do iframe que contém o link para o seu widget para no-referrer-when-downgrade

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

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

Incorporando o widget web no seu site

Para incorporar o bot no 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 mostrado antes da janela de chat abrir, com a opção de fechar o chatbot.

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

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

SDK

Você pode carregar o widget de chat usando a tag script abaixo. Chamar a chatlayer função exibirá 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 do URL se você quiser integrar um bot LIVE. Você pode adicionar parâmetros à chatlayer função para incluir funcionalidades adicionais.

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

Nesse 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

Nome da propriedade	Tipo	Observação
withCloseButton	booleano	O botão de fechar permite que os clientes fechem o bot clicando em um ícone "X" no canto superior direito do widget de chat
autoOpen	booleano
noButton	booleano
session	objeto	Adicione dados à sessão que podem ser usados para direcionar o fluxo.
sessionId	string	Um ID de sessão pode ser usado para continuar a conversa depois que o usuário sair da página. Certifique-se de que tenha 20 caracteres ou mais.
lang	string	Idioma do bot
button	HTMLElement
wrapper	HTMLElement

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 à chatlayer função. Todos os dados serão colocados na session variável na sessão do Chatlayer.ai. Esses dados podem então ser usados para customizar 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 determinam como o usuário aparecerá 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 de usuário com o SDK do widget de chat

Em muitos casos é necessário saber quem está falando com o bot. Uma maneira de descobrir é enviando um login ID, 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 login ID pode posteriormente 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

Certifique-se de que o script do SDK esteja carregado antes de executar essas funções.

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 do 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 retornante do bot, pode enviar um sender ID único para cada pessoa que abrir o bot, o qual pode então 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 a carga útil usando JWT, garantindo que não tenha sido alterada, 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 no seu próprio back-end. O código para gerar o token fica assim (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 pelo 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 Chatlayer</button>
    <button onclick="closeChatlayer()">Fechar Widget Chatlayer</button>

    <script>
      /**
       * Este exemplo demonstra a destruição de um webwidget do Chatlayer
       * ao acionar o plugin JSON builder no fluxo.
       *
       * O diálogo de ação do JSON builder foi configurado 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('ABERTO');
        });

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

        chatlayerInstance.on("event", event => {
          // Observe o conteúdo do event aqui: a chave "action" com valor "destroy"
          // origina-se diretamente da ação configurada do JSON Builder.
          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 prop: -->
    <!-- onload="initChatlayer()" -->
    <script
      src="https://chatbox.staging.chatlayer.ai/sdk/5ecbcf1514c3dc4942f05f96"
      async
    ></script>
  </body>
</html>

Configuração do plugin JSON builder:

Visualizar uma versão ao vivo deste código aqui.

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.