« Voltar

Integrando o Web Chat em seu site

Índice


Introdução

O Web Chat também pode ser utilizado integrado em seu site. Existem várias configurações e possibilidades de uso, mas a integração mais básica pode ser feita assim:

<html>
  <head>
    <title>Meu site de exemplo</title>
  </head>
  <body>
    <div>Conteúdo Original do site.</div>

    <!-- Início do código do chat -->
    <script src="https://static.zenvia.com/embed/js/zenvia-chat.min.js"></script>
    <script>new ZenviaChat('id-do-chat-aqui').build();</script>
    <!-- Fim do código do chat -->
  </body>
</html>


No trecho do código: 'id-do-chat-aqui' é necessário que seja utilizado um Id válido de Web Chat.
Um exemplo de Web Chat Embedded usando as configurações acima pode ser visto abaixo.

Exemplo de Web Chat Embedded usando as configurações padrão:



Glossário

Os “componentes” do Web Chat Embedded são:

  • Botão flutuante
    Botão flutuante

  • Botão de início
    Botão de início

  • Mensagem de boas-vindas e botão de início
    Mensagem de boas-vindas

  • Janela do Web Chat
    Janela do Web Chat

  • Id Web Chat
    O Id Web Chat é o identificador da “identidade” do Chatbot, a qual é usada para determinar inúmeras informações para uso no Web Chat, como o nome e logo do Chatbot, assim como qual Chatbot será usado para executar a conversa.

    O Id Web Chat pode ser obtido na lista de integrações, disponível no painel de controle.

Inicialização

A inicialização do chat é composta de 3 etapas:

  1. Carregamento do script
  2. Configuração
  3. Construção

Carregamento do script

A etapa mais simples da inicialização: simplesmente o código do Web Chat é carregado na página. Isso é feito através do seguinte bloco HTML:

<script src="https://static.zenvia.com/embed/js/zenvia-chat.min.js"></script>

Esse bloco HTML pode ser inserido tanto na tag head da página como na tag body. Esse bloco precisa ser inserido antes dos blocos das outras etapas da inicialização do Web Chat.

Configuração e Construção

As etapas de configuração e contrução podem ser executadas separadamente, mas, normalmente, é mais simples e mais fácil efetuá-las em conjunto.

A etapa de configução é composta da criação da instância da classe ZenviaChat na página, seguida, opcionalmente, de configurações descritas na seção de configurações dessa documentação.

Para efetuar a criação da instância da classe ZenviaChat, é necessário fornecer o Id Web Chat.

A etapa de construção consiste execução do método build(). Esse método que faz o botão flutuante do Web Chat aparecer na página.

Exemplo contendo as etapas de configuração e construção:

<script>
    new Zenvia('id-do-chat-aqui')
      .button('Tirar dúvidas')
      .build();
</script>


Elemento para construção do Web Chat

Opcionalmente, e particularmente importante para Web Chat Embedded utilizando a configuração embedded(“room”), é possível indicar o id de um elemento da página onde os elementos do Web Chat serão criados. Esse id é indicado como parâmetro no método build(). Exemplo:

<div id="id-do-elemento-html"></div>
<script>
    new Zenvia('id-do-chat-aqui')
      .build('id-do-elemento-html');
</script>

Em exemplo prático pode ser visto em embedded(“room”).

Informações de contexto do site disponíveis no Chatbot

Todo Web Chat Embedded, por padrão, durante sua inicialização, envia informações do contexto do site onde ele está integrado, como URL do site, hostname, path e query string. Todas as informações de contexto estão agrupadas dentro da variável website e seus atributos são os seguintes:

  • url: URL do site onde o Web Chat está integrado.
  • hostname: Hostname do site onde o Web Chat está integrado.
  • path: Path do site onde o Web Chat está integrado.
  • rawQueryParams: Dado bruto dos parâmetros query string da página onde o Web Chat está integrado.
  • queryParams: Parâmetros query string separados em “nome do parâmetro” e “valor do parâmetro.
  • referrer: Agrupamento das informações referentes à página que continha o link para o site onde o Web Chat está integrado. Similar à variável website, possui os seguintes atributos:
    • url: URL do site que continha o link para o site onde o Web Chat está integrado.
    • hostname: Hostname do site que continha o link para o site onde o Web Chat está integrado.
    • path: Path do site que continha o link para o site onde o Web Chat está integrado.
    • rawQueryParams: Dado bruto dos parâmetros query string do site que continha o link para o site onde o Web Chat está integrado.
    • queryParams: Parâmetros query string separados em “nome do parâmetro” e “valor do parâmetro do site que continha o link para o site onde o Web Chat está integrado.

Se, por exemplo, um usuário entrou no Google, pesquisou por “Empresa XYZ” e clicou no anúncio da Empresa XYZ que o Google forneceu ele será direcionado ao site da empresa. Caso ele interaja com o Chatbot integrado à essa página, a variável website seria disponibilizada para uso no Chatbot contendo uma estrutura parecida com a seguinte:

{
  "url": "https://www.empresa-xyz.com/produtos/X-Produto?utm_source=google&utm_medium=cpc&utm_campaign=google_xproduto&gclid=IsAEAIaIQobChMIyr38o_CS3QIVFoCRCh0jPwlbEAAYASAAEgKWXfD_BwE",
  "hostname": "www.empresa-xyz.com",
  "path": "/produtos/X-Produto",
  "rawQueryParams": "utm_source=google&utm_medium=cpc&utm_campaign=google_xproduto&gclid=IsAEAIaIQobChMIyr38o_CS3QIVFoCRCh0jPwlbEAAYASAAEgKWXfD_BwE",
  "queryParams": {
    "utm_source": "google",
    "utm_medium": "cpc",
    "utm_campaign": "google_xproduto",
    "gclid": "IsAEAIaIQobChMIyr38o_CS3QIVFoCRCh0jPwlbEAAYASAAEgKWXfD_BwE"
  },
  "referrer": {
    "url": "https://www.google.com.br/",
    "hostname": "www.google.com.br",
    "path": "/",
    "rawQueryParams": "",
    "queryParams": {}
  }
}


Para acessar algum destes atributos diretamente no Chatbot, basta utilizar a diretiva #{session['website']} respeitando a hierarquia da variável, como por exemplo:

  • #{session['website']['queryParams']['utm_source']} ou somente #{website.queryParams.utm_source} retornará o valor google.
  • #{session['website']['referrer']['hostname']} ou #{website.referrer.hostname} retornará o valor www.google.com.br.

É possível incluir informações extras nos dados do website que serão enviadas para o Chatbot. Essas informações ficarão na variável extra dentro de website. Para enviar informações extras para o Chatbot, é necessário setar o campo extraData durante a integração do Web Chat em seu site conforme mostrado abaixo:

<script src="https://static.zenvia.com/embed/js/zenvia-chat.min.js"></script>
<script>
  new ZenviaChat('id-do-chat-aqui')
    .extraData({ campoA: 'valor A', campoX: 'valor de X', outroCampo: { campoInterno: "um valor qualquer" }})
    .build();
</script>


Vale salientar que o campo extraData pode assumir qualquer estrutura pois é um objeto JavaScript ou pode ser somente uma string. Para acessar os dados extras no Chatbot basta utilizar a diretiva #{session['website']['extra']} respeitando a hierarquia do objeto enviado, como por exemplo:

  • #{session['website']['extra']['outroCampo']['campoInterno']} retornará o conteúdo um valor qualquer.

JavaScript

Alguns métodos são disponibilizados para permitir o controle e uso do Web Chat por elementos do site, tornando o uso do botão flutuante opcional.

Os seguintes métodos estão disponível para uso:

Um exemplo de uso pode ser visto em embedded(‘buttonless’).

Configurações

Existem algumas configurações que podem ser realizadas através de métodos da instância da classe ZenviaChat:

embedded

Controla o tipo de Web Chat embedded que será utilizado. O valor padrão é button+keyword, mas o recomendado é utilizar o valor button em seu lugar.

As opções são:

<script src="https://static.zenvia.com/embed/js/zenvia-chat.min.js"></script>
<script>
    new ZenviaChat('85b287488b82d36ca599382fd36c2695')
      .embedded('button')
      .build();
</script>




<script src="https://static.zenvia.com/embed/js/zenvia-chat.min.js"></script>
<script>
    new ZenviaChat('85b287488b82d36ca599382fd36c2695')
      .embedded('button+keyword')
      .build();
</script>




<!-- Início do código do chat -->
<script src="https://static.zenvia.com/embed/js/zenvia-chat.min.js"></script>
<script>
    var zchat = new ZenviaChat('85b287488b82d36ca599382fd36c2695')
      .embedded('buttonless')
      .build();
</script>
<!-- Fim do código do chat -->
<div class="example">
  <input type="button" value="open()" onclick="zchat.open()" />
  <input type="button" value="close()" onclick="zchat.close()" />
  <input type="button" value="toggle()" onclick="zchat.toggle()" />
</div>




<section class="hero is-white">
  <div class="hero-body">
    <div class="container">
      <!-- ELEMENTO HTML ONDE A JANELA DO CHAT SERÁ INSERIDA -->
      <div id="elemento-html" style="
          width: 500px;
          height: 500px;
          float: right;
          margin-left: 10px;
          border: 5px solid black;">
      </div>
      <!-- Conteúdo da página -->
      <h3 class="title is-4">Sobre nós</h3>
      <div class="content">
        <p>Somos uma empresa que acredita no futuro! Acima de tudo, no futuro das relações entre empresas e clientes.</p>
        <p> Com uma história de mais de 14 anos e a liderança em mobilidade corporativa no Brasil, oferecemos soluções capazes de fazer com que os clientes percebam os processos de negócio das empresas como experiências ricas em significado e valor.</p>
        <p>Vem simplificar o mundo com a gente!</p>
      </div>
    </div>
  </div>
</section>
<!-- Início do código do chat -->
<script src="https://static.zenvia.com/embed/js/zenvia-chat.min.js"></script>
<script>
    new ZenviaChat('85b287488b82d36ca599382fd36c2695')
      .embedded('room')
      .build('elemento-html');
</script>
<!-- Fim do código do chat -->



button

Controla o texto a ser exibido quando uma message é definida ou quando embedded é do tipo button+keyword, e o conteúdo da mensagem que é gerada para iniciar o Chatbot caso a sala do chat não esteja ainda inicializada.

O valor padrão é: Começar

Exemplo de Web Chat Embedded usando button(‘Olá’):

<script src="https://static.zenvia.com/embed/js/zenvia-chat.min.js"></script>
<script>
    new ZenviaChat('85b287488b82d36ca599382fd36c2695')
      .button('Olá!')
      .build();
</script>



message

Define uma mensagem de boas-vindas para ser exibida em um balão acima do botão flutuante.

Quando utilizada, o balão é carregado já aberto quando o site carrega, e a configuração embedded automaticamente muda para button.

Não tem valor padrão.

Exemplo de Web Chat Embedded usando message:

<script src="https://static.zenvia.com/embed/js/zenvia-chat.min.js"></script>
<script>
    new ZenviaChat('85b287488b82d36ca599382fd36c2695')
      .message('Olá! Eu sou o Testbot! Vamos conversar?')
      .build();
</script>



format

Define o formato da mensagem que pode ser gerada quando o botão de início é clicado. Existem cenários onde essa mensagem não é gerada.

Os formatos disponíveis são:

  • text: A mensagem inicial fica visível na conversa
  • json: A mensagem inicial não fica visível na conversa, e ainda permite o envio de informações adicionais ao Chatbot.

O valor padrão é json, exceto quando o embedded é configurado como button+keyword.

color

Define a cor do botão flutuante.

O valor padrão é: #333.

Exemplo de Web Chat Embedded usando color(‘#FF7F00’):

<script src="https://static.zenvia.com/embed/js/zenvia-chat.min.js"></script>
<script>
    new ZenviaChat('85b287488b82d36ca599382fd36c2695')
      .color('#FF7F00')
      .build();
</script>



width

Define a largura da janela flutuante do Web Chat.

O valor padrão é: 400px, exceto quando embedded é configurado como room, aí o valor padrão passa a ser 100%.

height

Define a altura da janela flutuante do Web Chat.

O valor padrão é: 567px, exceto quando embedded é configurado como room, aí o valor padrão passa a ser 100%.

user

Define o id do usuário no Web Chat. Juntamente com o Id Web Chat, determina o id da conversa.

Por padrão, esse id é gerado aleatoriamente, e armazenado no navegador até que o mesmo seja encerrado. Dessa forma, esse id será sempre o mesmo enquanto o usuário não fechar o navegador, então mesmo que o usuário saia da página ou abra várias abas, a conversa carregada será sempre a mesma.

Mas também é possível utilizar algum outro identificador, como por exemplo, um e-mail.

Integrações alternativas

Link/URL

São URLs que quando acessadas, iniciam o Chatbot identificado pelo Id Web Chat utilizado em sua composição.

Podem ser utilizados em diversos cenários, sendo portanto, bem flexível.

Domínios:

Existem diversas opções de domínio que podem ser usados para esse propósito. Seguem algumas delas com suporte a https:

  • zenvia.chat
  • seuchat.com

Composição:

O URL de redirecionamento a um Chatbot possui o seguinte formato:
http://[domínio]/bot/[Id Web Chat]

ou

http://[domínio]/bot/[Id Web Chat]/[palavra-chave]


Exemplos (funcional):

http://chat.zenvia.com/bot/85b287488b82d36ca599382fd36c2695