Referência: o que o chat envia e o que a sua API recebe

Atualizado em 01/10/2026

Esta é a página para quem está integrando o chat ao próprio sistema e precisa da lista completa, sem caçar em cinco artigos. Se você está começando, leia antes Chat (widget do site) e Verificação de identidade — aqui é só a referência.

Integrando com uma IA de programação? Existe uma versão desta integração feita para ela: um guia auto-contido, já preenchido com a sua chave, os seus endereços e os nomes de credencial da sua conta, servido em GET /api/v1/public/chat/llms.txt?key=A-CHAVE-DO-SEU-CHAT. Os botões “Copiar guia” e “Copiar só o link” ficam junto do código de instalação, em Administração › Configurações › Canais › Chat. O guia inclui o teste de assinatura por API (POST /api/v1/public/chat/verify-identity), para a IA provar o próprio código antes de entregar.

O ponto que organiza tudo: os dados chegam ao chat por quatro caminhos diferentes, e eles não valem a mesma coisa.

O que o seu site envia

Uma URL, e só uma. O código de instalação tem o endereço do arquivo chat.js e mais nada: para onde o chat conversa já vem embutido nesse arquivo, então não existe endereço de API para você preencher. Quem serve o widget a partir de outro ambiente pode apontar o destino com data-api (ou api no Chat.init) — é a única situação em que ele faz falta, e o valor tem de terminar em /api/v1.

Em aplicações de página única (SPA), onde o login acontece depois que o chat já carregou: use Chat.identify({ name, email, meta, auth, sig }). Os valores valem já na conversa aberta — seguem junto da próxima mensagem, sem fechar e abrir o painel. Chame no login e de novo sempre que algo mudar do seu lado; para o token do usuário, o caminho melhor é a função em credentials, que dispensa você acertar o momento. A lista completa de chamadas está em Controlar o chat pelo JavaScript.

As duas imagens do chat, e quem manda em cada uma

O chat mostra a sua identidade em dois lugares independentes: o logo do topo e o avatar ao lado de cada resposta. Eles podem ser imagens diferentes, e muitas vezes é o que você quer (a marca por extenso no topo, um ícone quadrado nas respostas, que cai melhor dentro do círculo).

Cada um tem a sua própria ordem. Vale a primeira linha que existir:

Logo do topo

1. header.logo no Chat.init (sobreposição por página)
2. A imagem enviada em Administração › Configurações › Canais › Chat, etapa Aparência › Imagem do logo
3. O avatar de quem responde (data-agent-avatar)
4. O ícone (favicon) da marca
5. O logo da marca

Avatar ao lado das respostas

1. A foto de quem respondeu, quando foi uma pessoa da sua equipe (veja abaixo)
2. data-agent-avatar (ou agentAvatar no Chat.init)
3. A imagem enviada em Administração › Configurações › Canais › Chat, etapa Aparência › Avatar de quem responde
4. O ícone (favicon) da marca
5. O logo da marca
6. A inicial do nome, quando não há imagem nenhuma

Duas leituras práticas:

• Para ter uma imagem no topo e outra nas respostas, não precisa de código. Envie o logo em Aparência: o topo passa a usar esse arquivo e as respostas seguem com o ícone da marca.
• data-agent-avatar sozinho troca as duas, porque o topo cai nele quando o canal não tem imagem própria. Se você quer mexer só nas respostas, envie também a imagem do logo em Aparência.

O interruptor "Logo no topo", na mesma tela, esconde a imagem do topo por completo e deixa só o título. É o ajuste de quem embute o chat dentro do próprio produto, onde a identidade já está na tela.

Quando uma pessoa responde

Enquanto a IA atende, o visitante vê a identidade da marca. Assim que alguém da sua equipe assume a conversa, as respostas dessa pessoa passam a sair com o primeiro nome e a foto dela, e o topo continua igual. É o que avisa o visitante de que agora tem gente do outro lado.

Quem manda nisso são três controles, e é sempre o mais restritivo que vence:

A imagem que o seu código define em data-agent-avatar continua valendo para as respostas automáticas: ela diz qual é a cara da marca, e não quem assinou cada mensagem.

Aparência por página

A aparência normal do chat se configura em Administração › Configurações › Canais › Chat, etapa Aparência, e vale para todas as páginas onde o código está colado, sem recolar nada. Quando uma página precisa fugir desse padrão (a área logada com outra cor, por exemplo), o Chat.init sobrepõe:

Chat.init({
key: 'SUA_CHAVE',
colors: { primary: '#0F172A', message: '#EEF2FF', action: '#2563EB' },
header: { style: 'plain', logo: 'https://seu-site.com/logo.png', title: 'Ajuda', subtitle: '' },
})

• colors: primary (topo e bolha que abre o chat), message (balão de quem escreve) e action (botões e links). Cada uma aceita o par onPrimary, onMessage e onAction para a cor da letra. Sem eles, a letra é calculada para ficar legível sobre o fundo que você escolheu.
• header: style (solid, gradient, image ou plain), gradientTo, image, logo, showLogo, title, subtitle e showEndButton. Subtítulo vazio (subtitle: '') esconde a linha de apoio. O style: 'plain' é o mesmo topo neutro do antigo theme: { header: 'plain' }, que continua funcionando.
• O que o código declara sempre ganha do que está na tela. É proposital: instrução explícita na página manda mais que configuração remota. Em compensação, cor colada no código não muda mais quando você troca a cor em Aparência.

Limites do contexto livre

• No máximo 25 chaves por conversa; nome de chave até 60 caracteres, valor até 500.
• O contexto fica gravado junto da conversa e é visível para o atendente que a abrir. Não mande nada que você não mostraria a ele.
• O contexto acompanha cada mensagem: o valor atual da página (ou do último Chat.identify) segue junto do envio e é mesclado chave a chave na conversa — valor trocado no meio do atendimento (a pessoa mudou de unidade no seu sistema, por exemplo) já vale na mensagem seguinte, e o que não veio permanece.
• A credencial não conta nesses limites. A chave cadastrada na API é reconhecida e separada do contexto: vai cifrada, cabe um token longo (até 4.000 caracteres, então JWT não é cortado) e não aparece para quem atende.

A recomendação sobre o token de quem está logado continua valendo: emita um de vida curta e escopo mínimo, só para o chat. Guardado aqui ele é cifrado, mas no navegador do visitante ele é o que é — e vida curta só funciona bem com renovação, que é o próximo assunto.

O que a sua API recebe

A credencial. Você escolhe o nome e o formato na tela da API: header com o nome que quiser (X-Auth-Token: <token>, sem Bearer), Bearer no Authorization, ou parâmetro na URL. O valor é o que veio no contexto livre, na chave de mesmo nome. Sem token na conversa (WhatsApp, por exemplo), a chamada cai na credencial fixa de reserva, se você tiver configurado uma.

Token que expira: mande uma função. A conversa é retomada por dias no mesmo navegador, então um token com prazo colado no código da página vira token vencido. Declarando credentials: { 'X-Auth-Token': () => token } no Chat.init, a plataforma pede o valor à sua função quando precisa: ao abrir a conversa, antes de cada envio e no instante em que a sua API recusa a credencial. A função pode ser assíncrona, e Chat.setCredential registra ou troca uma credencial com o chat já montado.

O 401 vira pedido de renovação. Respondendo 401 ou 403 a uma ação de credencial dinâmica, a resposta é segurada antes de o agente escrever qualquer coisa: a plataforma pede o token novo à sua função, refaz a consulta e entrega a resposta de verdade — quem perguntou não repete a pergunta nem recarrega a página. Sem função declarada, nada é segurado: a resposta sai explicando que o seu sistema recusou a credencial, para o cliente saber que precisa entrar de novo.

O nome tem que bater, e errar não dá erro. A plataforma envia uma credencial por chamada: a configurada na API, lendo a chave do contexto livre com exatamente aquele nome. Se o seu site grava o token em x-meu-token e a credencial está configurada como X-Auth-Token, o token nunca chega. Não aparece aviso nenhum: a chamada segue sem credencial (ou com a de reserva), e o sintoma surge longe, como um 401 ou um redirect de login na sua API. Antes de procurar em outro lugar, confira se a chave enviada no data-meta e o nome configurado na credencial são idênticos.

A identidade. Nos parâmetros adicionais da ação você escolhe o que enviar (visitor.email, visitor.name, visitor.id, visitor.phone, ou qualquer chave do contexto livre com meta:<chave>) e onde entregar: query, header ou corpo. Parâmetro sem valor no momento da chamada não é enviado.

O agente vê o contexto. As chaves do contexto livre aparecem para o agente de IA como visitor.<chave>, e as instruções da API ou de uma ação podem citá-las — por exemplo: "quando o cliente não pedir uma unidade específica, preencha o parâmetro com o visitor.unidade". O agente as trata como valor padrão: o que o cliente pedir na conversa vence, e o contexto nunca vale como prova de acesso — o portão continua sendo o verified. A credencial não aparece para o agente, só para as chamadas.

O verified, sempre. Havendo qualquer parâmetro de identidade, a plataforma anexa sozinha um campo verified com true ou false, no mesmo lugar dos outros (query, header ou corpo). É o seu portão: só devolva dado privado quando vier true. Você não precisa configurar nada para recebê-lo.

A assinatura dos parâmetros (opcional). Marcando parâmetros como assinados e definindo um segredo compartilhado na API, a chamada leva sig na query: HMAC-SHA256 em hexadecimal sobre chave=valor&chave2=valor2, com as chaves em ordem alfabética. O verified entra nessa conta quando a identidade é assinada — assim ninguém forja um true no caminho.

O que a sua ação devolve

Texto, JSON ou o que a sua API já responde — o agente lê e escreve a resposta com isso, montando tabela e gráfico quando os dados pedem (o visitante baixa em Excel ou PDF pelo botão da mensagem). Arquivo binário não vira anexo: se o seu sistema gera um PDF ou uma planilha, devolva a URL dele, que o agente entrega o link — e o controle de acesso ao arquivo continua sendo seu.

Limites e regras

• Quando a ação roda para o cliente final (conversas de subconta): só consulta, só com identidade assinada, só com credencial do próprio usuário ou identidade assinada nos parâmetros. Regra completa em APIs.
• Rotação do segredo não tem convivência. Gerou um novo, as assinaturas antigas param de valer na hora e o selo de validação zera. Para migrar sem derrubar ninguém, use um segundo chat (o segredo é por chat) e mude o site quando o novo estiver validado.
• Assinatura exigida só fica disponível depois que uma assinatura de teste foi validada. Ligada, identidade sem assinatura não vira cadastro — a conversa continua acontecendo, apenas anônima.
• Falha ao assinar (o seu servidor fora do ar, por exemplo) não recusa o visitante: ele conversa como anônimo, e as ações que exigem identidade ficam de fora.
• Um chat por marca, cada um com o seu segredo e a sua chave. O consumo de todos eles cai na sua conta.