Pular para o conteúdo
ChatMade
Entrar Falar com a gente

Conversas identificadas

Quando o visitante já está logado no seu site, o widget pode saber quem ele é — e essa ligação exige um passo no seu servidor.

Por padrão, quem abre o chat no seu site é anônimo. Se o seu site tem área logada — um painel de cliente, uma loja com conta, um sistema de assinatura — você pode fazer o chat já saber quem está do outro lado, sem perguntar.

Esta é a única página desta documentação que exige uma pessoa que programe. O passo central acontece no servidor do seu site, e não há como contornar isso: a chave envolvida não pode aparecer no navegador.

Quando isso vale a pena

Vale quando o atendimento fica melhor sabendo quem é a pessoa: o agente cumprimenta pelo nome, seu time vê o e-mail sem pedir, o histórico se acumula na ficha certa. E vale quando você não quer que qualquer pessoa da internet consuma sua conta do provedor de IA.

Não vale para site institucional sem login. Aí o custo não se paga.

Como funciona, em quatro passos

  1. Você cria uma chave de API no painel, na tela Widget Apps.
  2. O seu servidor guarda essa chave e, quando um cliente logado abre uma página, usa a chave para pedir ao ChatMade um token de conversa — curto, temporário, daquele cliente.
  3. A sua página recebe o token do seu próprio servidor e o entrega ao widget.
  4. O widget usa o token para conversar. O ChatMade confere e sabe de quem se trata.

O que importa entender: a chave nunca sai do seu servidor. Quem vai para o navegador é o token — que vale pouco tempo e serve para uma conversa só.

Passo 1: criar a chave

  1. No menu lateral, em Settings (“Configurações”), clique em Widget Apps (“Apps de widget”). A tela se descreve como Generate secure API keys to authenticate your chat widgets (“Gere chaves de API seguras para autenticar seus widgets de chat”).
  2. Clique em Create app (“Criar app”).
  3. Preencha Name (“Nome”) — o exemplo é e.g. Marketing Site — e, se quiser, Description (“Descrição”), respondendo a Where will this widget live? (“Onde este widget vai ficar?”).
  4. Clique em Create app.

A chave aparece uma vez só, na janela API Key Created, com o aviso Save this key now! (“Salve esta chave agora!”) e a explicação: This is the only time you’ll see this API key. It cannot be retrieved later. (“Esta é a única vez que você verá esta chave. Ela não pode ser recuperada depois.”)

Copie e guarde em lugar seguro antes de fechar. Perdendo, o caminho é o botão Regenerate key (“Regerar chave”) na linha do app — o que invalida a chave anterior e exige atualizar o seu servidor.

A chave começa com wak_.

Atenção: essa chave serve exclusivamente para gerar token de conversa do widget. Ela não é uma chave da API do ChatMade: não lê conversas, não cria usuários, não consulta nada. Se você procura uma chave para integrar o ChatMade a outro sistema pela API, ela não existe — a API é autenticada por sessão de usuário.

Passo 2: ligar a exigência no agente

  1. Vá em AI Agents (“Agentes de IA”) → Configure (“Configurar”) → aba Advanced (“Avançado”).
  2. No cartão Widget authentication (“Autenticação do widget”), descrito como Require server-side token authentication for widget access (“Exigir autenticação por token no servidor para acessar o widget”), ligue a chave.

Com ela desligada, o cartão mostra Anonymous access allowed (“Acesso anônimo permitido”). Com ela ligada, ninguém sem token conversa com esse agente — inclusive a pré-visualização dentro do painel deixa de funcionar, com o aviso Preview Unavailable (“Pré-visualização indisponível”). Para testar durante o desenvolvimento, desligue a chave temporariamente.

Passo 3: gerar o token no seu servidor

No seu servidor, crie um endereço interno que o seu site consulte. Ele chama o ChatMade assim:

const response = await fetch('https://SEU-SERVIDOR/api/v1/generate-token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer SUA_CHAVE_WAK'   // vinda de Widget Apps
  },
  body: JSON.stringify({
    widget_id: 'SEU-ID-DE-WIDGET',
    customer_email: 'cliente@exemplo.com',    // opcional
    customer_name: 'Maria Silva',             // opcional
    ttl_seconds: 3600                         // validade do token, 1 hora
  })
});

const { data } = await response.json();
// devolva data.token para a sua página

Sobre os campos:

  • widget_id é o identificador do agente, o mesmo que aparece no trecho de instalação, na aba Widget.
  • customer_email e customer_name são o que identifica a pessoa. Preencha com os dados do usuário logado.
  • ttl_seconds é a validade em segundos. Aceita de 60 (um minuto) a 86400 (24 horas). Fora dessa faixa, o pedido é recusado. Uma hora é um valor razoável.
  • É possível mandar ainda um campo custom_data, com até 20 chaves e 4 KB no total, para carregar informação extra sobre o cliente.

A resposta traz o token, o widget_id, a validade em segundos e as datas de criação e expiração.

O token e o widget_id ficam ligados criptograficamente: um token gerado para um agente não serve para outro.

Passo 4: entregar o token ao widget

Com a autenticação ligada, o painel gera um trecho de instalação diferente na aba Widget. Copie de lá — ele já vem com os seus valores. O formato é este:

<script>
(function() {
  fetch('/api/chattermate')            // troque pelo endereço do SEU servidor
    .then(r => r.json())
    .then(d => {
      const token = d.data.token;
      const widget_id = d.data.widget_id;
      if (!token || !widget_id) throw new Error('Failed to extract token or widget_id');
      window.chattermateId = widget_id;
      window.chattermateBaseUrl = 'https://SEU-SERVIDOR/api/v1';
      localStorage.setItem('ctid', token);
      const script = document.createElement('script');
      script.src = 'https://app.chatmade.com.br/webclient/chattermate.min.js';
      document.head.appendChild(script);
    })
    .catch(e => console.error('[ChatterMate] Initialization failed:', e));
})();
</script>

O único ponto a trocar é /api/chattermate: substitua pelo endereço do endpoint que você criou no passo 3. O próprio painel diz isso: “Add this code to your HTML, replacing /api/chattermate with your backend endpoint”.

Atenção: o painel repete e vale repetir aqui — Never expose your API key in client-side code. The token generation must happen on your server. (“Nunca exponha sua chave de API no código do navegador. A geração do token precisa acontecer no seu servidor.”) Uma chave wak_ colada numa página é uma chave pública: qualquer visitante pode ler o código-fonte e passar a gerar tokens na sua conta.

Encerrar o acesso antes da hora

Quando um cliente sai da conta, muda de permissão ou você suspeita de problema, o token pode ser invalidado antes de expirar. O seu servidor chama POST /api/v1/revoke-token, com o token e uma razão. Os usos previstos são exatamente esses: logout, mudança de permissão, incidente de segurança e revogação manual.

Se der errado

  • O widget não aparece e o navegador registra erro. Seu endereço de token não respondeu ou devolveu formato diferente do esperado. Teste o endereço direto no navegador.
  • Aparece “This chat widget is not currently configured”. O ChatMade recusou o acesso: normalmente token faltando, expirado, ou gerado para outro agente.
  • A pré-visualização no painel não abre. É esperado com a autenticação ligada. Desligue para testar dentro do painel.
  • Funcionou e parou depois de um tempo. O token expirou e a página não pegou outro. O trecho acima pede um token novo a cada carregamento da página; se o seu site é de página única e fica horas aberto, gere um token com validade maior ou renove pelo seu código.

Próximo passo

Para revisar como o chat aparece para esse cliente identificado, veja Aparência do widget.