Solução de problemas e checklist

Ferramentas

• Ferramentas do desenvolvedor → Rede: loader.js, core.<hash>.js, a conexão WebSocket (a aba “Mensagens” ou “Quadros” mostra init, init_ok, error) ou as requisições do fallback HTTP (h/auf, …/sse, …/tx).
• Ativar o diagnóstico: data-rc-debug="true" na tag do carregador ou localStorage.setItem('rc_debug','1') no console; depois, recarregue a página.
• Console: ReactiveChat('getSession'), ReactiveChat('getEndpoint'), ReactiveChat('isOpen'), ReactiveChat.version.

O botão do chat não aparece

• Chave do site ausente ou inválida. O carregador encerra sem avisar. Verifique data-rc-site-key (8–64 caracteres de A–Z a–z 0–9 _ -) na tag executada: gerenciadores de tags e recursos auxiliares de frameworks às vezes descartam atributos.
• type="module" na tag script: nesse caso, o carregador não consegue encontrar sua tag. Incorpore-o como script clássico.
• data-rc-hide-launcher="true", ou “Só pelos seus próprios links (sem ícone de chat)” definido na conta.
• Sem cor da marca no código de incorporação: sem uma cor válida em data-rc-brand, o botão só aparece depois que a conexão é estabelecida. Copie novamente o código da conta.
• Projeto pausado ou chave do site desconhecida: o servidor responde com unknown_site_key (fechamento 4002); nessa aba, o widget não tenta novamente por dez minutos.
• O núcleo não carrega: o console mostra [reactive.chat] core.js …. Muitas vezes, script-src ou um bloqueador de anúncios bloqueia o endereço; veja Domínio próprio.

O botão aparece, mas nenhuma mensagem chega

• loader.js hospedado por você sem data-rc-ws-url: o widget procura o servidor do chat no seu domínio. Na aba de rede, você vê tentativas de conexão sem sucesso com wss://ws.<your-domain>/rc_wss/. Solução: data-rc-ws-url="wss://ws.reactive.chat/rc_wss/".
• origin_denied, fechamento 1008: o domínio da página não está em Origens permitidas. Informe o domínio do site, não o subdomínio do chat.
• Bloqueio pela CSP: o console mostra uma mensagem de CSP sobre wss://… ou https://…/rc_wss/h/auf. Adicione os dois formatos a connect-src.
• Rede corporativa sem WebSocket: após duas tentativas malsucedidas, o widget muda para o fallback HTTP. Se ele também não funcionar, verifique se há proxies que encerram requisições em menos de 30 segundos ou armazenam respostas em buffer (Transporte).
• Bloqueio pela proteção contra abuso (fechamento 1008 blocked): comum quando há um proxy próprio sem uma chave de proxy válida, pois todos os visitantes passam a ter o mesmo endereço.
• Mensagem longa demais: o widget não envia textos acima do limite do plano (1.000 ou 4.000 caracteres).

Um usuário conectado aparece como anônimo

O quadro error contém auth_failed com detail.reason:

• no_hash – userHash está ausente em identify.
• no_secret – nenhum segredo foi configurado no projeto.
• bad_exp – exp está em milissegundos em vez de segundos ou não é um número inteiro.
• expired – a página está aberta há muito tempo ou o relógio do servidor está errado; calcule um novo hash quando a página carregar.
• exp_too_far – mais de 24 horas no futuro.
• bad_hash – o segredo, a sequência (userId + "." + exp) ou o conjunto de caracteres não corresponde; o segredo é a chave como string, não como bytes decodificados. Se houver um endereço de e-mail, ele deve ser assinado exatamente como é passado.

Detalhes: Identificar visitantes.

Os dados de clientes não chegam

• O assistente pede que o usuário entre, embora ele já esteja conectado: exp está ausente ou expirou; sem exp, não há dados de clientes.
• Testar conexão na conta informa o motivo (http_401, zeitueberschreitung, umleitung, adresse_privat …). A string assinada é X-RC-Zeit + "." + raw body: verifique com os bytes recebidos, não com o JSON recodificado.
• Um campo está ausente na resposta do assistente: ele não está habilitado na conta ou está na lista de campos que nunca são aceitos.

Detalhes: Endpoint de dados de clientes.

Os webhooks não chegam

• A integração está ativada e o evento selecionado (nenhuma seleção = todos)? Depois de ativar, aguarde até 15 segundos.
• Seu endpoint leva mais de 10 segundos para responder ou responde com um redirecionamento.
• Seu endpoint respondeu com 410 alguma vez: isso desativa a integração. Ative-a novamente.
• A assinatura não corresponde: calcule com o corpo bruto e X-RC-Timestamp + "." + body, observando o prefixo sha256=.
• Falta conteúdo em data: os campos de cada evento estão listados em Webhooks; um evento não selecionado não chega.

API do servidor

• 401 auth_failed: chave revogada, digitada incorretamente ou criada por uma pessoa que deixou de ser admin.
• 403 insufficient_scope: o escopo não é suficiente; required_scope informa o necessário.
• 429: limite de 120 requisições por minuto excedido; respeite Retry-After.
• 415/413: Content-Type: application/json ausente ou corpo acima de 64 KiB.

O texto de privacidade não aparece

• O carregador está ausente na página ou bloqueado pela plataforma de consentimento: incorpore datenschutz.js diretamente.
• O site não está cadastrado como domínio no projeto ou o projeto está pausado.
• data-rc-privacy-state="error" no elemento indica uma requisição malsucedida.

Checklist antes de colocar em uso

1. Todos os domínios do site cadastrados em Origens permitidas.
2. Código de incorporação da conta sem alterações em todas as páginas nas quais o chat deve aparecer, incluindo a página de privacidade.
3. CSP: script-src com o local de distribuição, connect-src com wss:// e https://, img-src para imagens.
4. Consentimento: data-rc-consent ou plataforma de consentimento (TCF v2 / consented.eu) verificado, com testes com e sem consentimento.
5. Política de privacidade ampliada (<div data-rc-privacy> ou bloco de texto).
6. Identidade: userHash com exp calculado no servidor, segredo somente no ambiente do servidor, init_ok.identity.verified igual a true.
7. Áreas com texto confidencial marcadas com data-rc-private.
8. Com domínio próprio: todas as cinco etapas de verificação com “OK”, chave de proxy apenas na configuração do proxy, /rc_wss/h/ fora do log de acesso.
9. Webhooks: assinatura e timestamp verificados, duplicatas detectadas por X-RC-Delivery, resposta 2xx rápida.
10. Fallback HTTP testado uma vez com data-rc-transport="http".
11. Visualização móvel (abaixo de 480 pixels, o chat abre em tela cheia) e operação pelo teclado verificadas.