> For the complete documentation index, see [llms.txt](https://docs.chatlayer.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.chatlayer.ai/chatlayer-documentation-pt-br/channels/all-channels/web/webwidget.md).

# Web V1 \[Fim da vida útil]

{% hint style="danger" %}
Este canal foi descontinuado em: 16/09/2025.
{% endhint %}

{% hint style="danger" %}
**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**](/chatlayer-documentation-pt-br/channels/all-channels/web/web-v2.md)**.** 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](/chatlayer-documentation-pt-br/channels/all-channels/web/web-v2/from-web-v1-to-v2.md).
{% endhint %}

{% hint style="warning" %}
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](https://docs.chatlayer.ai/channels/web-v2).
{% endhint %}

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.

{% hint style="info" %}
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.

<img src="/files/377ada01f6d4a1a5639e2f70fba21bdb1c07f842" alt="" data-size="original">
{% endhint %}

![](/files/81d7bedb128cbe173720f95c2daa4bcdb05be817)

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](/chatlayer-documentation-pt-br/channels/all-channels/web/webwidget/customize-web-widget.md))
  * 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:

```markup
^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 é:

```markup
^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:

```markup
^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`

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

Mais informações sobre políticas de referência podem ser encontradas [aqui](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy).

## 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.

![](/files/a0100ef15d629621833fab681ce3cf7abce6b8a4)

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:

![](/files/b476fec77937bbc6602c2440f5211b3f66853f7a)

### 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.

```markup
<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.

```markup
<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.

![](/files/1185503552cc5d35509a60c1d1e2717fa6d58147)

#### 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.

```markup
<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.

```javascript
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:

```markup
<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](/chatlayer-documentation-pt-br/integrateandcode/custom-back-end-integrations.md).

#### 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:

```javascript
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
```

{% hint style="warning" %}
Certifique-se de que o script do SDK esteja carregado antes de executar essas funções.
{% endhint %}

## 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.

```markup
<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.

```markup
<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](https://api.chatlayer.ai/v1/docs/#operation/sendWebhookMessage) chamada à API.

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

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

O exemplo acima resultaria em uma sessão contendo:

```javascript
{
   "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.

```markup
<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.

![](/files/8959781f6df957567cf792419abc9b7672bc8abf)

\
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):

```javascript
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.

```markup
<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:

![](/files/17249ce665850ea9de766173d2768151883864e0)

{% hint style="info" %}
Ver uma versão ao vivo deste código [aqui](https://codesandbox.io/s/chatlayer-destroy-webwidget-s0lnj?file=/index.html).
{% endhint %}

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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.chatlayer.ai/chatlayer-documentation-pt-br/channels/all-channels/web/webwidget.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.