# Web V1 \[Encerrado]

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

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

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

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.

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

![](https://181262846-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LLTwFwbOqJj4dDhg8Ju%2F-M1aKdXlt4LGre1IJV3g%2F-M1aOY7KmJRASiWYS5rN%2Fimage.png?alt=media\&token=0f3472c2-1d5e-4645-846b-1900b5bce730)
{% endhint %}

![](https://181262846-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LLTwFwbOqJj4dDhg8Ju%2F-M1aKdXlt4LGre1IJV3g%2F-M1aL_eQj_YH_zQTpm1o%2Fimage.png?alt=media\&token=97aec660-7853-4a14-8839-b350f9797438)

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

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

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

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

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

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

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

![](https://181262846-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LLTwFwbOqJj4dDhg8Ju%2F-M1aKdXlt4LGre1IJV3g%2F-M1aQ4xkosErE4XbCQcC%2FMar-04-2020%2017-40-50.gif?alt=media\&token=465fa742-4ffa-43f7-967e-9cf1567a00e1)

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:

![](https://181262846-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LLTwFwbOqJj4dDhg8Ju%2F-M1aKdXlt4LGre1IJV3g%2F-M1aQsOxymIDqxVpRE-J%2Fimage.png?alt=media\&token=87581b76-3b6b-4e26-b6c8-8c06ed8a62f6)

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

```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` do URL se você quiser integrar um bot LIVE. Você pode adicionar parâmetros à `chatlayer` função para incluir funcionalidades adicionais.

```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 do SDK, ele será aberto com a animação Grow.

![](https://181262846-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LLTwFwbOqJj4dDhg8Ju%2F-M1aKdXlt4LGre1IJV3g%2F-M1aW6q80onrHohkELNB%2FMar-04-2020%2018-07-31.gif?alt=media\&token=40e324a3-c399-4681-ae40-bc24cdbcd28e)

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

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

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

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

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

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

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

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

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

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

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

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

![](https://181262846-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LLTwFwbOqJj4dDhg8Ju%2F-MESA3MDM5ncHoFf8MDU%2F-MESASr-xhpXHQHYaIfQ%2Fimage.png?alt=media\&token=9de80732-e9a2-441d-b8a1-6a64e2dee270)

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

```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'
});
```

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.

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

![](https://181262846-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LLTwFwbOqJj4dDhg8Ju%2F-M8BYZ0rFc274QsygIov%2F-M8BZt06OqDoM5_E2u71%2Fimage.png?alt=media\&token=179a1c12-f52c-470d-8fec-de0b4a666fa0)

{% hint style="info" %}
Visualizar 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 acionar um evento de destruição para o widget de chat.