# Agilize Docs para IA - Página atual

Este arquivo contém uma versão focada e legível por IA da página aberta na documentação pública da Agilize.
Use esta versão quando a pergunta do usuário estiver restrita ao documento atual.

Última geração: 2026-07-14T17:03:00.452Z

## Página

- Título: Configuração do LiveChat e widget do site
- URL humana: https://agilize.app/docs/configuracao/canais-whatsapp-integracoes/configuracao-livechat-widget
- Leitura completa para IA: https://agilize.app/docs/llms.txt
- Descrição: Como cadastrar o LiveChat, instalar o widget no site e configurar textos, cores e posicionamento pela tela ou por código.

## Seções

- Antes de começar
- Onde acessar
- Configurar pela tela
- Campos do cadastro
- Instalar no site
- Configurar sem usar a tela
- Parâmetros visuais do widget
- Parâmetros de posição e abertura

## Conteúdo da página

# Configuração do LiveChat e widget do site

O LiveChat permite receber visitantes do site dentro da Agilize, executar um fluxo de bot quando configurado, distribuir atendimento para a equipe e manter o histórico da conversa junto aos demais canais.

Use este guia para cadastrar o canal, instalar o widget no site e ajustar textos, cores e comportamento visual pela tela da Agilize ou diretamente no código da página.

---
title: "Como o LiveChat entra na operação"
caption: "O cadastro gera o token do widget. O script usa esse token para abrir a conversa do visitante no canal correto."
definition: |
  flowchart LR
    A[Cadastrar LiveChat] --> B[Receber token público]
    B --> C[Instalar script no site]
    C --> D[Visitante envia mensagem]
    D --> E[Fluxo do bot ou atendimento]
    E --> F[Histórico na Agilize]
---

## Antes de começar

Confirme estes pontos:

- você tem permissão para configurar canais no módulo de Mensageria;
- o site onde o widget será instalado pode receber scripts antes do fechamento da tag `body`;
- o fluxo de bot já existe, se o LiveChat deve iniciar com triagem automática;
- a equipe já sabe qual rotina seguirá quando a conversa chegar;
- o time de site conhece as cores, textos e posição desejados para o widget.

O cadastro do LiveChat gera um `publicToken`. Esse token identifica o canal que será usado pelo widget e não deve ser inventado manualmente.

## Onde acessar

Acesse [https://my.agilize.app/messenger/chat/livechat](https://my.agilize.app/messenger/chat/livechat).

Acesso pela tela: sidebar lateral > módulo **Mensageria** > **Configurações** > tree interna **Configuração LiveChat**.

## Configurar pela tela

1. Abra **Configuração LiveChat**.
2. Crie um novo cadastro ou edite um LiveChat existente.
3. Preencha **Nome** com uma identificação clara, como site, produto ou landing page.
4. Selecione **Fluxo Atendimento - ChatBot** quando o visitante deve passar por triagem automática.
5. Ative **Gerar Protocolo** quando a operação exige protocolo para atendimentos desse canal.
6. Em **Customizar Widget**, ajuste textos, cores e posicionamento.
7. Use a pré-visualização para conferir o resultado.
8. Salve o cadastro.
9. Abra a visualização do LiveChat e copie os códigos de instalação.

Na visualização, a tela mostra um link para simular visitante, um bloco opcional de estilos personalizados e o script final do widget. Instale primeiro o bloco de estilos, quando existir, e depois o script do widget.

## Campos do cadastro

| Campo | Obrigatório | Como configurar | Impacto |
| --- | --- | --- | --- |
| **Nome** | Sim | Texto livre. Use um nome estável e fácil de reconhecer. | Identifica o canal na lista de LiveChats. |
| **Fluxo Atendimento - ChatBot** | Não | Selecione um fluxo de bot existente. | Define o fluxo executado quando a conversa entra pelo LiveChat. |
| **Gerar Protocolo** | Não | Ative quando a operação exige protocolo de atendimento. | Quando ativo, gera protocolo para conversas desse canal. |
| **Customizar Widget** | Não | Ajuste textos, cores, fundo, ícones, posição e abertura do widget. | Personaliza a experiência do visitante no site. |
| **Código de instalação** | Gerado pelo sistema | Copie na visualização do cadastro depois de salvar. | Instala o widget no site usando o token gerado para esse LiveChat. |

## Instalar no site

Depois de salvar o LiveChat, copie o código de instalação na visualização do cadastro e adicione antes do fechamento da tag `body` do site.

```html
<script src="https://cdn.agilize.app/module/messenger/js/livechat.js?token=PUBLIC_TOKEN" async></script>
```

Substitua `PUBLIC_TOKEN` pelo token gerado no cadastro. Se você copiou o código pela tela, ele já vem preenchido.

Para simular o visitante sem instalar no site, use o link de simulação exibido na visualização do cadastro. Ele abre a rota do visitante com o mesmo token.

## Configurar sem usar a tela

Quando o cadastro já existe, a personalização visual pode ser controlada pelo site com `window.__agilize_config`. Esse objeto deve ser declarado antes do script do widget.

```html
<script>
  window.__agilize_config = {
    action_bar_text: "Converse conosco agora mesmo!",
    top_bar_text: "Estamos disponíveis :)",
    empty_messages_text: "Escreva uma mensagem abaixo para começar",
    widget_position: "right",
    widget_start_open: false,
    ensure_full_mode: true,
    widget_min_spare_width_px: 120,
    action_bar_bg: "linear_gradient_90_3_colors",
    action_bar_bg_color1: "#020024",
    action_bar_bg_color2: "#090979",
    action_bar_bg_color3: "#46136c",
    action_bar_bg_degree: 90,
    action_bar_text_color: "#ffffff",
    top_bar_text_color: "#293357",
    bg_main_color: "#f6f8ff"
  }
</script>
<script src="https://cdn.agilize.app/module/messenger/js/livechat.js?token=PUBLIC_TOKEN" async></script>
```

Esse caminho é útil quando o time de site quer ajustar textos, cores ou comportamento por ambiente, landing page, teste A/B ou identidade visual sem reabrir o cadastro na Agilize.

Se a sua implantação cria ou atualiza o cadastro por integração autorizada, use os campos técnicos equivalentes aos rótulos da tela: `name` para **Nome**, `flow` para **Fluxo Atendimento - ChatBot**, `isToGenCase` para **Gerar Protocolo** e `custom` para **Customizar Widget**. O `publicToken` continua sendo gerado pelo sistema no cadastro do LiveChat.

## Parâmetros visuais do widget

Use estes parâmetros dentro de `custom` no cadastro ou dentro de `window.__agilize_config` no site.

| Parâmetro | Tipo | Padrão | Efeito |
| --- | --- | --- | --- |
| `action_bar_bg` | string | `linear_gradient_90_3_colors` | Define o fundo da barra recolhida. Use `solid` ou `linear_gradient_90_3_colors`. |
| `action_bar_bg_color1` | cor HEX | `#020024` | Primeira cor do fundo. No modo `solid`, é a cor principal. |
| `action_bar_bg_color2` | cor HEX | `#090979` | Segunda cor do gradiente. |
| `action_bar_bg_color3` | cor HEX | `#46136c` | Terceira cor do gradiente. |
| `action_bar_bg_degree` | número | `90` | Ângulo do gradiente em graus. |
| `action_bar_text` | string | `Converse conosco agora mesmo!` | Texto exibido quando o widget está recolhido. |
| `action_bar_text_color` | cor HEX | `#ffffff` | Cor do texto da barra recolhida. |
| `action_bar_icon_color1` | cor HEX | `#ffffff` | Primeira cor do ícone da barra recolhida. |
| `action_bar_icon_color2` | cor HEX | `#7D00FF` | Segunda cor do ícone da barra recolhida. |
| `top_bar_text` | string | `Estamos disponíveis :)` | Texto no topo da janela aberta. |
| `top_bar_text_color` | cor HEX | `#293357` | Cor do texto da barra superior. |
| `top_bar_icon_color1` | cor HEX | `#EAEDFF` | Primeira cor do ícone da barra superior. |
| `top_bar_icon_color2` | cor HEX | `#293357` | Segunda cor do ícone da barra superior. |
| `top_bar_icon_close_color` | cor HEX | `#293357` | Cor do botão de fechar/minimizar. |
| `main_text` | cor HEX | `#293357` | Cor principal de texto do widget. |
| `empty_messages_text` | string | `Escreva uma mensagem abaixo para começar` | Texto exibido quando ainda não há mensagens. |
| `bg_messsage_1_color` | cor HEX | `#eeecf4` | Fundo de um dos lados da conversa. |
| `border_messsage_1_color` | cor HEX | `transparent` | Borda de um dos lados da conversa. |
| `bg_messsage_2_color` | cor HEX | `#d9d4ec` | Fundo do outro lado da conversa. |
| `border_messsage_2_color` | cor HEX | `transparent` | Borda do outro lado da conversa. |
| `border_btn_color` | cor HEX | `#322e4d` | Cor de borda/linha dos botões exibidos na conversa. |
| `bg_main_color` | cor HEX | `#f6f8ff` | Cor de fundo da área principal da janela. |

Os nomes `bg_messsage_1_color`, `border_messsage_1_color`, `bg_messsage_2_color` e `border_messsage_2_color` mantêm a grafia usada pelo widget. Use exatamente esses nomes no JSON.

## Parâmetros de posição e abertura

| Parâmetro | Tipo | Padrão | Efeito |
| --- | --- | --- | --- |
| `widget_position` | string | `right` | Define o lado do widget. Use `right` ou `left`. |
| `widget_start_open` | boolean | `false` | Quando `true`, o chat inicia aberto. Quando `false`, inicia recolhido. |
| `ensure_full_mode` | boolean | `false` | Quando `true`, o script avalia espaço disponível e alterna entre modo desktop e mobile. |
| `widget_min_spare_width_px` | número | `0` | Folga mínima exigida ao lado do chat para manter o modo desktop. |
| `widget_mobile_mode` | boolean | automático | Força modo mobile quando informado. Use apenas quando o site controla essa decisão. |
| `widget_desktop_width_px` | número | `350` | Largura do widget no modo desktop. |
| `widget_desktop_height_px` | número | `450` | Altura máxima do widget aberto no modo desktop. |
| `widget_desktop_offset_px` | número | `60` | Distância lateral no modo desktop. |
| `widget_mobile_offset_px` | número | `20` | Distância lateral no modo mobile. |
| `widget_bottom_gap_px` | número | `8` | Distância inferior em relação à borda da tela. |
| `widget_min_top_gap_px` | número | `0` | Folga superior mínima considerada no cálculo de modo desktop. |
| `widget_min_desktop_width_px` | número | calculado | Largura mínima para manter modo desktop. Se não informado, usa largura, offset e folga mínima. |
| `widget_min_desktop_height_px` | número | calculado | Altura mínima para manter modo desktop. Se não informado, usa altura, folga inferior e folga superior. |

Na tela da Agilize, os controles principais de posição expõem lado do widget, detecção automática, folga mínima e abertura automática. Os demais parâmetros podem ser úteis em instalação por código quando o layout do site exige medidas específicas.

## Exemplo completo de `custom`

Use este exemplo como base para a configuração por integração ou para o bloco `window.__agilize_config`.

```json
{
  "action_bar_bg": "linear_gradient_90_3_colors",
  "action_bar_bg_color1": "#020024",
  "action_bar_bg_color2": "#090979",
  "action_bar_bg_color3": "#46136c",
  "action_bar_bg_degree": 90,
  "action_bar_text": "Converse conosco agora mesmo!",
  "action_bar_text_color": "#ffffff",
  "action_bar_icon_color1": "#ffffff",
  "action_bar_icon_color2": "#7D00FF",
  "main_text": "#293357",
  "empty_messages_text": "Escreva uma mensagem abaixo para começar",
  "bg_messsage_1_color": "#eeecf4",
  "border_messsage_1_color": "transparent",
  "bg_messsage_2_color": "#d9d4ec",
  "border_messsage_2_color": "transparent",
  "border_btn_color": "#322e4d",
  "bg_main_color": "#f6f8ff",
  "top_bar_text": "Estamos disponíveis :)",
  "top_bar_text_color": "#293357",
  "top_bar_icon_color1": "#EAEDFF",
  "top_bar_icon_color2": "#293357",
  "top_bar_icon_close_color": "#293357",
  "widget_position": "right",
  "ensure_full_mode": true,
  "widget_min_spare_width_px": 120,
  "widget_start_open": false
}
```

## Validar depois de instalar

1. Abra o site em uma janela anônima.
2. Confirme se o widget aparece no lado esperado.
3. Abra e feche o chat para validar altura, posição e modo mobile.
4. Envie uma mensagem como visitante.
5. Confirme se a conversa entra na Agilize pelo LiveChat correto.
6. Verifique se o fluxo de bot executou, quando configurado.
7. Responda pela Agilize e confira se a mensagem aparece no widget.
8. Conclua o atendimento e revise histórico e protocolo.

No uso diário, conversas distribuídas devem chegar ao Flow do usuário. Use telas de monitoramento para supervisão, auditoria e exceções.

## Problemas comuns

| Sintoma | O que verificar |
| --- | --- |
| Widget não aparece | Script instalado antes do fechamento da tag `body`, token correto, bloqueio de scripts no site e console do navegador. |
| Widget abre no canal errado | Token copiado de outro cadastro de LiveChat. |
| Estilos não aplicam | `window.__agilize_config` precisa estar antes do script do widget e as chaves precisam manter a grafia correta. |
| Cores aparecem diferentes do esperado | Revise se as cores estão em HEX válido e se `action_bar_bg` está como `solid` ou `linear_gradient_90_3_colors`. |
| Widget fica apertado no site | Ative `ensure_full_mode` e ajuste `widget_min_spare_width_px`, offsets ou largura desktop. |
| Chat inicia aberto sem intenção | Revise `widget_start_open`. |
| Conversa não chega ao time | LiveChat correto, fluxo padrão, departamentos envolvidos no fluxo e usuários habilitados para receber atendimento. |
| Protocolo não foi gerado | Revise se **Gerar Protocolo** está ativo no cadastro. |

## Boas práticas

- Crie um LiveChat por site, produto ou landing page quando precisar medir e operar entradas separadas.
- Use nomes estáveis, como `Site institucional`, `Landing campanha julho` ou `Portal do cliente`.
- Teste cores em desktop e mobile antes de publicar.
- Evite textos longos na barra recolhida; ela tem pouco espaço.
- Mantenha contraste suficiente entre texto e fundo.
- Não publique tokens, dados de cliente ou credenciais em repositórios públicos.
- Quando houver fluxo de bot, teste entrada, coleta de dados, transferência e encerramento antes do go-live.

## Próximos passos

- Para revisar outros canais, veja [Canais e integrações](/docs/configuracao/canais-whatsapp-integracoes/canais-e-integracoes).
- Para criar a triagem automática, veja [Guia geral de fluxos do bot](/docs/configuracao/fluxos-automacoes/guia-geral-de-fluxos-do-bot).
- Para definir distribuição e departamentos, veja [Regras de roteamento e distribuição](/docs/configuracao/roteamento-distribuicao/regras-de-roteamento-e-distribuicao).