Como preencher automaticamente os dados do cliente no widget da Nvoip

Seu site pode informar nome, e-mail, telefone e empresa ao widget da Nvoip. Assim, uma pessoa que já se identificou no seu sistema não precisa digitar novamente os mesmos dados para iniciar o atendimento.

A integração funciona em qualquer site que permita JavaScript personalizado. Você pode instalar o código diretamente na página, consultar os dados na API do seu sistema ou usar o Google Tag Manager (GTM). O widget não descobre sozinho quem fez login: seu site precisa fornecer esses dados.

Antes de começar

• Tenha o widget configurado e o código de instalação fornecido pela Nvoip. Use o token público que aparece nesse código no lugar de SEU_TOKEN_PUBLICO.
• Tenha acesso ao código do site ou ao container web do GTM. A equipe responsável pelo login deve informar onde os dados do cliente ficam disponíveis.
• Use HTTPS no site.
• Registre a função identityProvider antes de carregar o script do widget, inclusive se o chat tiver abertura automática.
• Escolha uma das opções abaixo. Não instale dois loaders nem dois provedores para o mesmo widget.

O token público identifica a configuração do widget. Ele não é uma chave de API nem uma credencial de login.

Quais dados podem ser enviados?

Além do id, forneça pelo menos um dos quatro campos de dados com conteúdo. Para um atendimento bem identificado, preencha todos os campos disponíveis. O formulário ou canal escolhido pode exigir informações adicionais. Textos acima dos limites são cortados pelo widget.

Mantenha o mesmo id para a mesma pessoa. Se seu sistema separa lojas ou contas, inclua essa separação no identificador. Não use o mesmo id para pessoas diferentes nem gere um valor novo a cada carregamento.

Opção 1 — JavaScript com dados já disponíveis na página

Use esta opção quando sua aplicação já conhece o cliente ao carregar o widget. No exemplo, window.clienteAtual é uma variável criada pelo seu site; adapte os nomes ao seu sistema.

<script>
window.NvoipWidgetSettings = window.NvoipWidgetSettings || {};
window.NvoipWidgetSettings['SEU_TOKEN_PUBLICO'] = {
  identityProvider: function () {
    var cliente = window.clienteAtual;

    // undefined: seu site ainda não informou o resultado do login.
    if (cliente === undefined) {
      throw new Error('Identificação ainda não disponível');
    }
    // null: seu site confirmou que não há cliente logado.
    if (cliente === null) return null;
    if (!cliente || cliente.id == null) {
      throw new Error('Cliente sem identificador');
    }

    return {
      id: String(cliente.id),
      name: cliente.nome,
      email: cliente.email,
      phone: cliente.telefone,
      company: cliente.empresa
    };
  }
};
</script>
<!-- Depois deste bloco, mantenha o código de instalação do widget. -->

Antes desse bloco, seu sistema deve definir window.clienteAtual com um objeto do cliente ou com null quando a visita for anônima. Não copie dados fixos de uma pessoa para todas as páginas: cada visitante deve receber apenas os próprios dados.

Se o site monta essa informação no servidor, use o serializador JSON seguro do seu framework para inseri-la na página. Não concatene nome ou e-mail diretamente dentro de código JavaScript.

Opção 2 — Consultar a API do seu sistema após o login

Use uma função assíncrona quando os dados só ficam disponíveis depois de uma consulta. O widget aguarda a resposta antes de iniciar seus canais.

O endereço /api/cliente-atual e os nomes dos campos abaixo são exemplos. Esse endpoint deve existir no seu site, retornar apenas o usuário da sessão atual e ser substituído pelo endereço real da sua aplicação.

<script>
window.NvoipWidgetSettings = window.NvoipWidgetSettings || {};
window.NvoipWidgetSettings['SEU_TOKEN_PUBLICO'] = {
  identityProvider: async function () {
    var resposta = await fetch('/api/cliente-atual', {
      credentials: 'same-origin',
      cache: 'no-store'
    });

    // Use esta regra se 401 significar "sem login" na sua API.
    if (resposta.status === 401) return null;
    if (!resposta.ok) throw new Error('Falha ao consultar o cliente');

    var cliente = await resposta.json();
    if (cliente === null) return null;
    if (!cliente || cliente.id == null) {
      throw new Error('Resposta de identificação inválida');
    }

    return {
      id: String(cliente.id),
      name: cliente.nome,
      email: cliente.email,
      phone: cliente.telefone,
      company: cliente.empresa
    };
  }
};
</script>
<!-- Depois deste bloco, mantenha o código de instalação do widget. -->

A consulta do exemplo usa a sessão do seu próprio site. Senhas, cookies, tokens de acesso e chaves privadas não devem fazer parte do objeto retornado ao widget. Adapte a regra de visitante anônimo ao contrato real da sua API; não converta falhas de rede em null.

O provedor deve concluir em até 10 segundos. Em caso de erro, retorno inválido ou timeout, o widget oferece uma tentativa de carregamento e não cria um atendimento anônimo como alternativa. Uma nova tentativa pode consultar o provedor novamente; por isso, a função deve apenas ler a identidade, sem criar pedidos ou executar outras ações.

Opção 3 — Instalar pelo Google Tag Manager

O GTM pode entregar o mesmo código das opções anteriores. Ele não substitui a integração com o login: os dados precisam estar disponíveis no seu site ou em uma API da sua aplicação.

1. No container web do GTM, crie uma tag do tipo HTML personalizado, com o nome “Nvoip — Identificação do cliente”.
2. Cole o bloco completo da opção 1 ou 2, incluindo as tags <script>, e substitua SEU_TOKEN_PUBLICO e os campos de exemplo.
3. Abra a tag que instala o widget. Em Configurações avançadas → Sequenciamento de tags, configure a tag de identificação para executar antes dela. Ative a opção de não executar a tag principal se a tag de configuração falhar.
4. Faça o widget carregar uma única vez por página. A função de identidade deve estar registrada antes do loader; se ela retornar uma Promise, quem aguarda os dados é o widget.
5. Use o modo Visualizar do GTM para testar a ordem e os cenários de login. Depois, publique a versão do container.

Se o widget está instalado diretamente no HTML e o provedor está no GTM, pode haver uma disputa de carregamento. Coloque ambos sob uma ordem controlada: mova a instalação do widget para a sequência do GTM ou registre o provedor diretamente antes do loader no site.

Não é necessário enviar nome, e-mail ou telefone ao dataLayer. A tag pode consultar uma variável em memória, como window.clienteAtual, ou a API do site. Se sua aplicação já usa eventos de login no dataLayer, eles podem acionar uma tag de atualização, mas os dados pessoais não precisam acompanhar o evento.

Referências do Google: tags HTML personalizadas e sequenciamento de tags.

Login, logout e troca de cliente sem recarregar a página

Em sites com navegação dinâmica, alterar uma variável não atualiza sozinho o widget. Primeiro atualize o resultado do provedor; depois emita o evento abaixo. Use o mesmo token público da instalação.

window.dispatchEvent(new CustomEvent('nvoip:identity-changed', {
  detail: { publicToken: 'SEU_TOKEN_PUBLICO' }
}));

Para a opção 1, após concluir o login:

// dadosDoCliente deve ser o objeto retornado pelo login do seu site.
window.clienteAtual = dadosDoCliente;
window.dispatchEvent(new CustomEvent('nvoip:identity-changed', {
  detail: { publicToken: 'SEU_TOKEN_PUBLICO' }
}));

No logout, se quiser continuar oferecendo atendimento anônimo:

window.clienteAtual = null;
window.dispatchEvent(new CustomEvent('nvoip:identity-changed', {
  detail: { publicToken: 'SEU_TOKEN_PUBLICO' }
}));

Se quiser ocultar o widget durante a troca de conta ou após sair, faça o provedor retornar false e emita o evento:

window.NvoipWidgetSettings['SEU_TOKEN_PUBLICO'].identityProvider = function () {
  return false;
};
window.dispatchEvent(new CustomEvent('nvoip:identity-changed', {
  detail: { publicToken: 'SEU_TOKEN_PUBLICO' }
}));

Após autenticar a nova pessoa, restaure a função da opção escolhida e emita o evento novamente. Na opção 2, emita o evento depois que a sessão do site estiver atualizada para que o widget consulte a API outra vez.

Durante uma troca de conta, bloqueie a identidade anterior imediatamente, antes de aguardar o novo login. Não deixe os dados do cliente anterior disponíveis enquanto carrega os dados do próximo. Descarte também respostas antigas no código da sua aplicação.

O que significa cada retorno?

O widget separa o armazenamento da sessão por site, token e identificador. Na troca de identidade, desmonta a interface e a conexão anteriores. A primeira adoção dessa integração não vincula automaticamente uma conversa anônima antiga ao cliente identificado.

Como testar a configuração

1. Entre no seu site com uma conta de teste e abra o widget. Confira nome, e-mail, telefone e empresa no formulário ou no novo atendimento.
2. Recarregue a página: a identidade deve continuar correta.
3. Saia da conta. Confirme o comportamento escolhido: visitante anônimo (null) ou widget oculto (false).
4. Entre com uma segunda conta de teste e confirme que os dados e a conversa da primeira não aparecem.
5. Simule uma consulta lenta ou com erro. O widget não deve criar atendimento anônimo para contornar a falha de identificação.
6. Se houver abertura automática do chat, teste também esse caminho.

Para diagnosticar, confira no navegador se a função existe antes do loader e se o token é o mesmo nos dois lugares. No GTM, use a visualização para conferir a sequência. Não registre dados pessoais ou credenciais em logs de produção.

Dúvidas comuns

O chat ainda mostra um nome de visitante. Confira se o provedor foi registrado antes do widget, se o token está correto e se sua aplicação retornou null antes de terminar o login. Uma conversa antiga já criada não é corrigida retroativamente por esta integração.

Apareceu “Não foi possível carregar os dados do atendimento”. Verifique o endpoint da sua aplicação, o prazo de 10 segundos, o id textual e pelo menos um campo preenchido. Corrija a origem dos dados e tente novamente.

Posso mudar nome ou telefone mantendo o mesmo cliente? Sim. Mantenha o id, atualize os dados e emita o evento. Isso não garante a reescrita de cadastros ou atendimentos já persistidos; confira o resultado no fluxo que você utiliza.

Isso autentica o cliente perante a Nvoip? Não. Os dados enviados pelo navegador são informações fornecidas pelo seu site, como as de um formulário. Não concedem acesso ao histórico de outra pessoa nem alteram filas, conta ou permissões.

Funciona em WordPress, Wix, lojas e sistemas próprios? O contrato é o mesmo: a plataforma precisa permitir o JavaScript, disponibilizar a identidade e respeitar a ordem de carregamento. A forma de obter os dados depende da sua plataforma. Um campo de HTML dentro de iframe isolado pode não compartilhar a página onde o widget está instalado.

Vale para formulários avulsos? Este manual se refere ao widget de contato da Nvoip. Formulários independentes instalados com NvoipForms têm inicialização própria.