🚫Web V1 [Encerrado]

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

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

Atenção:

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

Uma das formas mais comuns de disponibilizar um bot para seus clientes é por meio de um chat widget. Neste guia técnico, vamos orientá-lo no processo de integração do bot ao seu site.

Criando seu widget de chat da web

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

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

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

Na página do Chat Widget, você pode personalizar vários componentes-chave do chat widget:

• Aba de configuração

  • Título do bot

  • Modelo

  • Faça upload de CSS personalizado (mais informações sobre CSS personalizado aqui)

  • Fonte e tamanho da fonte do título

  • Fonte e tamanho da fonte do parágrafo

  • Lista de permissões dos domínios nos quais você quer que o bot seja ativado (isto é, o domínio do seu próprio site e quaisquer outros domínios usados para testes)

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

• Aba de cores

  • Cores de todos os principais componentes do chatbot

• Aba de traduções

  • Traduções das mensagens padrão do chat widget, como "Escreva a resposta..."

Lista de permissões

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

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

As regexes de lista de permissões também podem ser usadas para configurações mais complexas, com vários domínios. Considere o seguinte conjunto de domínios como exemplo:^https:\/\/www\.(subdomain1|subdomain2)\.(rootdomain1|rootdomain2)\.com(\/|$) irá colocar na lista de permissões 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/

Lista de permissões com um iframe

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

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

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

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

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

Mais informações sobre políticas de referência podem ser encontradas aqui.

Incorporando o widget da web no seu site

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

Há duas maneiras de integrar o Chat Widget ao 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 de chat widget é uma camada sobre um iframe, que inclui algumas outras funcionalidades, como um botão exibido antes de a janela de chat abrir, com a opção de fechar o chatbot.

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

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

SDK

Você pode carregar o chat widget usando a tag script abaixo. Ao chamar a chatlayer função, o botão e o seu chat widget serão exibidos 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 EM PRODUÇÃO. Você pode adicionar parâmetros à chatlayer função para incluir funcionalidade adicional.

<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 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 chat widget
autoOpen	booleano
noButton	booleano
session	objeto	Adicione dados à sessão que possam ser usados para orientar 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 ele tenha 20 caracteres ou mais.
lang	string	Idioma do bot
botão	Elemento HTML
contêiner	Elemento HTML

Transferindo uma variável do seu site, por meio 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 poderão 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: "Usuário", lastName: "Nome" }})' 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 da Chatlayer.

internal: {
  ...
  user: {
      firstName: 'Usuário',
      lastName: 'Nome',
        },
        ...
    },
    ...
 session: {
     number: 1234,
     firstName: 'Usuário',
     lastName: 'Nome'
    }
    ...
    firstname: 'Usuário',
    lastname: 'Nome'
}

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

Em muitos casos, é necessário saber quem está falando com o bot. Uma forma de descobrir isso é enviar um ID de login, detectado no site em que o usuário está autenticado, e passá-lo ao bot quando o SDK for inicializado:

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

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

Comportamento do botão do chat widget

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

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

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 a fechada do chat widget
chatlayerChat.close();
// Minimiza a janela do chat widget para o botão

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

Iframe

Incorporar o chat widget em um iframe é a opção de incorporação mais direta. Você determina como e onde coloca o elemento e pode estilá-lo como quiser.

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

Remova .staging da URL se você quiser integrar um bot em produção. Você pode alterar ?lang=en para qualquer idioma compatível com o bot.

Definindo o ID do remetente

Se você quiser reconhecer um usuário recorrente do bot, você pode enviar um ID de remetente exclusivo para cada pessoa que abrir o bot, o qual então poderá 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 ID de remetente tenha 20 caracteres ou mais.

Transferindo uma variável do seu site, por meio do iframe, para o chatbot

A sessão de um usuário pode ser atualizada a qualquer momento por meio da Envie mensagens por meio de um canal Webhook chamada à 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

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

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

Criptografia

Há duas opções principais para proteger o chat widget. Você pode verificar o payload usando JWT, garantindo que ele não tenha sido adulterado, ou pode criptografar a sessão criada pelo chat widget 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 sessão de chat. Esse token deve ser gerado no seu próprio back-end. O código para gerar o token se parece com isto (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'
});

A forma 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 da Chatlayer.ai por meio do seu próprio código JavaScript.

<html>
  <head>
    <title>Exemplo de eventos do Chatlayer</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 mostra a destruição de um webwidget da Chatlayer
       * ao acionar 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 da 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 o valor "destroy"
          // vem 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 da 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 a Chatlayer primeiro!");
          return;
        }
        chatlayerInstance.open();
      };

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

    <!-- Observe a ausência da prop onload no seguinte script tag. -->
    <!-- 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:

Ver 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 disparar um evento de destruição do chat widget.