> For the complete documentation index, see [llms.txt](https://docs.altu.d1.cx/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.altu.d1.cx/connect/canais/widget.md).
# Widget
## Visão Geral
O widget é um dos meios de comunicação que o Zenvia NLU disponibiliza. Ao optar por esse canal, o assistente fica disponível diretamente no site do cliente.
Uma de suas vantagens é a possibilidade de configurar a interação do usuário utilizando diversos componentes: botões de resposta rápida, máscara para preenchimento de campos, autocomplete entre outros.
## **Compatibilidade**
É possível **receber** mensagens como:
* Texto
* Arquivos
É possível **enviar** mensagens como:
* Pergunta aberta
* Autocomplete
* Data
* Encerrar Chat
* Feedback NPS
* Feedback Emoji
* Lista de opções: Modal e Inline
* Quick Replies
* Upload de arquivo
* Carrossel de Opções
## **Adicionar Widget**
Para começar, vamos criar a integração do seu assistente com o canal. Acesse **Connect > Canais > Widget.**
Na página que se abrirá, você encontra todos os Widgets publicados ou em configuração da sua conta.
Clique em “**+ Adicionar widget**” no canto superior direito da página.
### **Configurações**
Nessa aba adicione as informações solicitadas:
* **Assistente**: selecione o [assistente ](/build/assistentes.md)
* **Título da Página**: nome que será informado na aba do navegador
* **Nome do Widget**: nome que deseja dar ao canal Squad: selecione o nome da squad se estiver disponível na lista, caso contrário mantenha como “geral”
* **Digitando**: escolha de que modo a mensagem deve aparecer para o usuário
* **Dinâmica**: apresenta uma imagem de “digitando” durante o tempo definido até o envio da mensagem
* **Estático**: envia a mensagem após o tempo de espera definido, sem indicação de carregamento
**Opcionais:**
* **Inatividade:** um novo atendimento será iniciado automaticamente após o usuário ficar inativo pelo tempo configurado (mínimo de 10 minutos e máximo de 1440 minutos).
* **Esperar por dados:** configuração específica para assistentes que são exibidos via Tag. Com essa opção selecionada, a conversa só se inicia após o envio de dados através do método `altubots.sendDataToContext({ })`
* **Continuidade da conversa:** ao final de uma interação, as mensagens serão salvas no histórico do navegador e o usuário poderá dar continuidade a conversa futuramente
* **Ativar avisos sonoros em Live Chat:** ao selecionar essa funcionalidade o cliente será notificado, por meio de um aviso sonoro, quando um agente enviar uma mensagem durante o atendimento. O aviso pode ser customizado ao adicionar o endereço web onde está hospedado o arquivo de áudio
{% hint style="info" %}
Para garantir o funcionamento da notificação sonora, é recomendado que o áudio seja verificado no campo “Validar”. Em seguida, se estiver tudo certo, o som será processado e executado, certificando sua performance no Live Chat
{% endhint %}
#### **Validação de avisos sonoros**
Para uma validação bem sucedida, o link informado deve conter um áudio com, no máximo, 5 segundos de duração. Exemplo de URL (nosso áudio padrão):
**Durante a conversa com o agente, o cliente pode desativar ou ativar essa notificação**. Por padrão, o Live Chat deixa o áudio ativado. O botão para realizar essa ação estará disponível no topo do chat, juntamente com os botões para "Sair do chat" e "Sair do live chat".
Confira nosso vídeo com a demonstração da funcionalidade:
{% embed url="" %}
Vídeo demonstração de aviso sonoro em Live Chat
{% endembed %}
### Aparência e Comportamento
Essa é a área de **personalização da aparência do assistente**. Temos dois temas padrões, o “**ALTU**” e o "**basic**", mas o CSS pode ser editado livremente para atender ao guia de estilo da empresa, [clique aqui para algumas dicas](/boas-praticas/personalizar-widget.md). Também é possível adicionar um logo e avatar de até 1MB nos formatos: png, jpeg, jpg, svg e gif.
{% hint style="info" %}
**É necessário escolher um template para conseguir salvar o Widget.**
{% endhint %}
### Tag
Na aba Tag você **configura a exibição do Widget no seu site**. Essa funcionalidade opera por meio de uma função javascript, que deve ser adicionada no HTML do site, antes de fechar o bloco ``
Há duas configurações básicas a serem feitas:
#### Botão Flutuante
Para que o site exiba um botão, que ao ser clicado mostre o chat, você deve deixar a opção "**Exibir Botão flutuante**" ativa.
Selecione a opção “**Padrão**” para utilizar o botão Padrão da ZENVIA NLU, onde a única customização possível é a cor.
Para alterar a cor, você pode inserir o hexadecimal da cor, como `#11ff1a` para verde, ou utilizar o picker, uma caixa de seleção manual de cores.
Caso você queira usar um botão personalizado, selecione a opção “**Customizado**”.
Preencha o campo URL com o link do arquivo que será usado como botão, podendo ser uma imagem ou um HTML. **Esse arquivo deve estar hospedado em um site com acesso público**.
Também é necessário incluir a largura e altura do botão, em pixels.
#### Dimensões do Widget
Logo abaixo do campo de botão flutuante, você deve inserir as dimensões que o Widget terá quando aparecer no seu site ou aplicativo.
As dimensões padrões são:
* **Largura**: 450px
* **Altura**: 600px
* **Espaçamento margem inferior**: 10px
* **Espaçamento margem direita**: 10px
Mas você pode alterar essas dimensões livremente, utilizando a formatação em pixels ou em porcentagem ao clicar no botão do campo dimensão.
Após fazer todas as configurações anteriores, clique em “**Criar widget**”
## Publicar Widget
Após a criação do Widget você verá uma aba chamada “**Utilização**”.
Nela você acompanha os status das alterações do Widget e também da Tag, com informações sobre a última publicação.
Nessa aba você também copia as **URL's de homologação e publicação**.
Para que seja possível utilizar o canal em produção, é necessário clicar em “**Publicar Widget**”.
## Publicar Tag
{% hint style="info" %}
**Só será possível publicar a Tag após a** [**publicação do Widget**](#publicar-widget)
{% endhint %}
Na aba “**Utilização**”, logo abaixo das informações sobre a publicação do Widget, você verá as informações da Tag.
Clique em “**Publicar Tag**” para acessar o script necessário para a configuração do seu assistente no seu site.
### Instalação
Para o chat aparecer no seu site, insira o script que você encontra na página "**Utilização**"
### **Utilização manual da TAG**
Uma vez que a TAG está inserida no site, a exibição do chat ou botão pode ser controlada a partir dos seguintes eventos javascript:
* **altubots.openChat( )** - Usado para exibir o chat já expandido, independente da opção "Exibir botão flutuante" estar desativada ou ativa;
* **altubots.closeChat()** - Fechar o chat que estava em andamento, independente da opção "Exibir botão flutuante" estar desativada ou ativa;
* **altubots.sendDataToContext({ })** - Quando a opção "**Esperar por dados**" estiver ativa no widget, esse evento serve para enviar os dados para o contexto da conversa na abertura do chat.
Exemplo:
```javascript
```
* **altubots.showButton()** - Utilizado para exibir o botão flutuante manualmente na página, quando a opção "Exibir botão flutuante" estiver desativada;
* **altubots.hideButton()** - Utilizado para ocultar o botão flutuante manualmente na página onde a TAG está instalada.
{% hint style="info" %}
Caso um dos eventos acima seja chamado antes do script da TAG ser carregado na página, a referida ação não será executada.
{% endhint %}
## Editar Widget
Para editar, acesse **Connect > Canais > Widget** e escolha na lista o Widget para edição.
Após qualquer alteração feita nas abas de Configuração e Aparência e Comportamento, como uma mudança no nome do Widget ou no CSS, será necessário salvar, clicando em “**Salvar alterações**” no canto superior direito da página.
Será necessário **refazer o processo** [**publicação do canal**](#publicar-widget), para que as mudanças sejam efetivas na URL do assistente.
## Editar Tag
Ao editar as configurações de uma Tag, será necessário clicar em “**Salvar alterações**” no canto superior direito da página e também **refazer o processo de** [**publicação da tag**](#publicar-tag).
## Coletar IP e user agent em acessos
O IP do usuário e User Agent serão coletados quando o usuário acessar o Widget. As informações serão direcionadas para a variável `url_params` do `context`.
Com as informações do `user_agent` é possível identificar:
* Aplicação
* Sistema operacional
* Fornecedor
* Navegador de internet
Exemplo de como fica estruturado o IP e user agent no url\_params:
```json
{
"url_params": {
"ip": "127.0.0.1",
"user_agent": {
"os": {
"name": "Linux",
"version": "x86_64"
},
"ua": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/89.0.4389.90 Safari/537.36",
"cpu": {
"architecture": "amd64"
},
"device": {},
"engine": {
"name": "Blink",
"version": "89.0.4389.90"
},
"browser": {
"name": "Chrome",
"major": "89",
"version": "89.0.4389.90"
}
}
}
}
```
## Baixar conversa
Durante todo o atendimento, o usuário poderá realizar o download da conversa. Isso é realizado através da chamada de uma função: `download_chat_history ()`.
### Como usar?
O PDF pode ser gerado por meio de um [Socket Event](https://docs.altu.com.br/builder/assistentes/componentes/actions/socket-event), que chama a função. Você deve incluir na **configuração do Widget**, no bloco **body**, o seguinte código:
```javascript
```
Pode-se perguntar se o usuário deseja exportar a conversa, tal qual um protocolo. Se a resposta for positiva, em seguida, chamaria um Socket Event, como o que está abaixo:
```json
[
{
"name": "socket_event",
"parameters": {
"event": "exportPDF",
"payload": {
"chat_name": "ALTU"
}
},
"result_variable": "event_response"
}
]
```
Exemplo de um atendimento com download de PDF:
## PDF
### Cabeçalho
O cabeçalho do PDF irá conter três informações:
* **O título:** "Histórico do Atendimento".
* **O** **subtítulo:** será opcional e é o único que pode ser passado por parâmetro na função. A imagem acima é resultante da chamada: `download_chat_history ("ALTU")`. Se não não for houver parâmetro passado, o cabeçalho será o seguinte:
* **A data da exportação**
### Corpo
O corpo do PDF é composto pelo conteúdo do atendimento, ou seja, a troca de mensagens. É compatível com pré-visualização de imagens. Nele, também exibimos o momento (data e hora) em que ocorreu a troca de mensagens de cada bloco. Links no atendimento, que possibilitam download do arquivo pré-visualizado, não estarão acessíveis dentro do PDF.
