Widget Javascript API

Instalação e ordem de carregamento

Inicialize a fila window.Tolv, envie os dados conhecidos e só então inclua o script assíncrono do widget.

<script>
  window.Tolv = window.Tolv || [];

  Tolv.push(["identify", {
    name: "João Silva",
    email: "joao@example.com",
    phones: ["+55 51 99999-9999"],
    external_id: "customer-123",
    unique_id: "customer-123",
    display: "João Silva [Plano Pro]"
  }]);

  Tolv.push(["setFields", {
    company: "Empresa Exemplo",
    plan: "Pro"
  }]);

  Tolv.push(["setContext", {
    source: "logged_area",
    page_type: "account"
  }]);
</script>
<script async src="https://widget.tolv.io/widget/WIDGET_UUID"></script>

Métodos da API atual

Tolv.identify({ name: "Maria", unique_id: "usr-456" })
  .setFields({ company: "Empresa Exemplo" })
  .setContext({ source: "checkout" });

Campos de identify

external_id e unique_id podem ter o mesmo valor, mas possuem responsabilidades diferentes. O primeiro descreve o visitante; o segundo participa da restrição de resposta única.

setFields, setContext e dados automáticos

Campos livres

Tolv.setFields({
  document: "00000000000",
  company: "Empresa Exemplo",
  plan: "Enterprise"
});

Campos podem preencher perguntas equivalentes e aparecer em dados operacionais ou analíticos.

Metadados e roteamento

Runtime coletado automaticamente

Visibilidade e resposta única

1. Configure um caller de formulário com visibilidade Até responder (unique_id).
2. Informe Tolv.identify({ unique_id }) antes do loader.
3. O tracker consulta a disponibilidade em lote e só renderiza callers ainda não respondidos.
4. O backend mantém um Set Redis por conta + formulário e protege a gravação com índice único no MongoDB.
5. Após a submissão, o caller mostra sucesso por 5 segundos, fecha e desaparece na página atual.

O Redis armazena apenas o hash SHA-256 do identificador. O valor original permanece associado à resposta para identificação autorizada no produto.

Eventos públicos

Tolv.on("load", (event, api) => console.log(event.status));
Tolv.on("open", () => console.log("aberto"));
Tolv.on("close", () => console.log("fechado"));
Tolv.on("form-submitted", (event) => {
  console.log("Resposta confirmada", event.submission_id);
});

Validação e limites

API legada e retrocompatibilidade

A fila antiga window._tn continua aceita. A fachada window._tno expõe load, open, close, deptos e a propriedade status.

Comandos obsoletos aceitos e ignorados: _setChatMode, _setCallMode, _setTheme, _setEyeCatcher e _addAgentLink.

Exemplo completo

<script>
  window.Tolv = window.Tolv || [];

  Tolv.push(["identify", {
    name: currentUser.name,
    email: currentUser.email,
    phones: currentUser.phones,
    external_id: currentUser.customerId,
    unique_id: currentUser.id,
    display: currentUser.name + " [" + currentUser.plan + "]"
  }]);

  Tolv.push(["setFields", {
    company: currentUser.company,
    plan: currentUser.plan
  }]);

  Tolv.push(["setContext", {
    source: "logged_area",
    page_type: "dashboard"
  }]);

  Tolv.push(["on", "form-submitted", function (event) {
    console.log("Pesquisa respondida", event.submission_id);
  }]);
</script>
<script async src="https://widget.tolv.io/widget/WIDGET_UUID"></script>