09. Widget - Zenvia

Nesta página você encontra todas as informações necessárias para conectar seu assistente da Zenvia NLU ao Widget.

Visão Geral

O widget é um dos meios de comunicação que a 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 e 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. Para isso, siga as etapas abaixo:

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. Para mais informações, acesse a documentação Visão Geral dos Assistentes;
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({ }).

⚠️Atenção: A URL a ser adicionada deve ser apenas o "Origin" onde o chatbot será instalado. "Origin" é uma combinação de um esquema (também conhecido como protocolo, como HTTP ou HTTPS) e um nome de host. Por exemplo, considerando um URL https://www.example.com/foo/bar, a "origem" é https://www.example.com.

Se o chatbot precisar ser instalado em várias origens, você pode utilizar o caractere curinga * (asterisco) para permitir todas as origens.
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;
Ativar status das mensagens em Live Chats: ao marcar essa opção, cada mensagem enviada pelo usuário, durante um livechat, possuirá um status;
Exibir versão alternativa das mensagens informativas: ao marcar essa opção, durante um livechat o atendimento exibirá todas as mensagens informativas, com a formatação customizada (configurada na aba "Aparência e Comportamento"). Caso contrário, serão exibidas como as demais mensagens de texto simples.

💡 Dica: 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.

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

https://altu-assets.s3-sa-east-1.amazonaws.com/sounds/notification-livechat.mp3

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:

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.

Também é possível adicionar um logo e avatar de até 1MB nos formatos: png, jpeg, jpg, svg e gif.

⚠️Atenção: é necessário escolher um template para conseguir salvar o Widget.

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 <head>

Há duas configurações básicas a serem feitas:

Botão Flutuante

Para que o site exiba um botão e, 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.

widget 8.webp

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

💡 Dica: 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

⚠️Atenção: só será possível publicar a Tag após a publicação do Widget.

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

<script type="text/javascript">
   altubots.sendDataToContext({
     "nome": "José da Silva",
     "email": "[email protected]"
 });
</script>

altubots.showButton() - 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.

Os dados recebidos no contexto podem ser utilizados a partir do caminho <?context.url_params.nome_variavel?>onde nome_variavel é o campo enviado pelo script. Considerando o exemplo acima, seria <?context.url_params.email?>que recebeu o valor "[email protected]".

⚠️Atenção: 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.

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 para que as mudanças sejam efetivas na URL do assistente.

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:

{
 "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, que chama a função.

Você deve incluir na configuração do Widget, no bloco body, o seguinte código:

<script type="text/javascript">
   $(document).ready(function() {
      if(socket)
 {
       socket.on('exportPDF', function(payload) {
          download_chat_history(payload.chat_name)
 });
 }
 });
</script>

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:

[
 {
 "name": "socket_event",
 "parameters": {
     "event": "exportPDF",
     "payload": {
        "chat_name": "ALTU"
 }
 },
 "result_variable": "event_response"
 }
]

PDF

Cabeçalho

O cabeçalho do PDF irá conter três informações:

Título: "Histórico do Atendimento".
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á 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 e, nele, também exibimos o momento (data e hora) em que ocorreu a troca de mensagens de cada bloco.

⚠️Atenção: links no atendimento, que possibilitam download do arquivo pré-visualizado, não estarão acessíveis dentro do PDF.

Como podemos ajudar?