Pular para o conteúdo principal

Resolução de problemas

Utilize esta página quando o widget estiver instalado, mas não funcionar como esperado.

O widget não aparece​

Verifique primeiro a consola do navegador. O ChattyBox indica aí quando faltam atributos obrigatórios.

Causas comuns:

  • O script não está presente nem no HTML publicado nem no DOM ativo.
  • O script foi adicionado ao modelo, ao layout, ao contentor do Tag Manager ou à área de código do CMS errados.
  • O script está sujeito a uma regra de consentimento ou a um acionador do Tag Manager que não foi ativado.
  • O componente da aplicação que monta o loader não é executado nessa rota.
  • Uma Content Security Policy bloqueia https://chattybox.ai/widget.js.
  • O CSS ou outro widget sobrepõe-se ao botão de abertura.
  • A configuração publicada tem widget.enabled: false.

Correção mais simples:

  1. Abra a página pública publicada numa janela anónima.
  2. Pesquise chattybox.ai/widget.js no código-fonte da página e no painel Elements do navegador; um loader inserido por um SDK ou por JavaScript pode aparecer apenas no DOM ativo.
  3. Confirme que o script aparece uma vez e inclui data-api-key e data-api-url.
  4. Se estiver em falta, coloque o script no rodapé global, no layout da aplicação, na raiz do Docusaurus ou no acionador GTM All Pages.

Em projetos geridos por configuração, widget.enabled: false impede a inicialização do widget alojado e faz com que os pedidos públicos POST /chat devolvam 403 Widget is disabled, incluindo os pedidos do SDK headless. Altere essa definição através do fluxo de implementação da configuração, não rodando a chave pública. Remover o script loader depois da inicialização não remove o widget já apresentado.

Falta data-api-url​

O widget termina imediatamente se faltar data-api-url.

Utilize o snippet completo do dashboard ou adicione o atributo obrigatório:

<script
  src="https://chattybox.ai/widget.js"
  data-api-key="YOUR_API_KEY"
  data-api-url="https://adorable-woodpecker-629.convex.site/chat"
  async
></script>

Utilize o URL da API indicado no dashboard, em vez de o adivinhar. Em produção, deverá ser um URL estável https://...convex.site/chat.

Erro genérico 401 Invalid API key​

Por motivos de segurança, os endpoints da API do widget devolvem a mesma resposta genérica 401 Invalid API key para uma chave pública desconhecida, expirada ou rejeitada devido à origem. Não use a resposta para determinar a causa.

Causas comuns:

  • A chave pública do widget foi copiada incorretamente.
  • A chave foi eliminada, expirou ou pertence a uma implementação de backend diferente da do URL da API.
  • O projeto ou o proprietário da chave está a ser eliminado.
  • A restrição opcional de origens está ativa para a chave e a origem atual do site não está incluída.

Correções:

  1. Abra o projeto no dashboard ChattyBox.
  2. Abra Instalar → Instalação no site, introduza o URL do site e copie um snippet elegível, se estiver disponível.
  3. Em Chaves e domínios, na mesma página, escolha Editar origens para a chave do snippet instalado. Se a opção Restringir esta chave a origens específicas estiver ativa, adicione a origem exata que serve a página ou desative a restrição opcional. O esquema, o nome do anfitrião e a porta têm de corresponder: https://example.com, https://preview.example.com e http://localhost:3000 são origens diferentes. Não é necessário adicionar entradas separadas para os caminhos.
  4. Volte a implementar ou a publicar o site e teste novamente numa janela anónima.

Uma chave válida de outro chatbot no mesmo backend normalmente seleciona esse chatbot em vez de devolver um 401; verifique o projeto se as respostas forem inesperadas. Nomes de chaves como "production" e "staging" não impõem ambientes. A API HTTP utiliza Origin quando esse cabeçalho está presente; só utiliza a origem de Referer quando Origin está ausente. Uma chave restrita rejeita o pedido se a origem selecionada estiver ausente, for inválida ou não for permitida. Um Referer permitido não substitui um Origin não permitido. As restrições de origem não substituem a autenticação dos visitantes.

Limites de mensagens ou de pedidos​

Consulte Conta e faturação em /settings/account para ver a utilização de mensagens, o plano e os eventuais orçamentos PAYG Pro/Business. Testar chatbot e a conversa pública consomem ambos a quota de mensagens partilhada do proprietário. Eliminar conversas ou criar outra chave não repõe essa quota.

Os erros da quota mensal e os limites de frequência de curto prazo são diferentes. Nas respostas HTTP 429, respeite Retry-After quando for fornecido, em vez de repetir o pedido continuamente. Perante um erro de limite mensal de mensagens, aguarde pela reposição da quota ou ajuste o plano/o orçamento PAYG elegível. A página Conversas → Histórico mostra as conversas, não uma consola de erros por pedido; utilize o painel Network do navegador para inspecionar falhas HTTP.

Idioma incorreto​

Verifique primeiro as definições de idioma do widget em Personalizar → Aparência. O widget alojado no código-fonte atual escolhe o idioma da interface nesta ordem:

  1. data-locale no script do widget, apenas se Permitir substituição através de script estiver ativado.
  2. No modo Fixo, o idioma predefinido configurado.
  3. No modo Detetar automaticamente, o valor de <html lang> da página, depois as opções de idioma do navegador e, por fim, o idioma predefinido configurado.

As opções não suportadas são ignoradas. O inglês é a opção final se nenhuma for suportada; o idioma predefinido inicial é o inglês.

Correções:

  • Para a seleção automática do idioma, escolha Detetar automaticamente e remova um data-locale incorreto ou desative Permitir substituição através de script.
  • Defina <html lang="de">, <html lang="fr"> ou o código de idioma suportado correspondente nas páginas localizadas.
  • Para impor o idioma configurado, escolha Fixo e desative Permitir substituição através de script. Com as substituições ativadas, data-locale continua a ter prioridade sobre o modo Fixo.
  • Confirme que as definições foram guardadas, reinicialize o widget instalado para obter as alterações às definições do dashboard e teste novamente. O widget.js v16 alojado no código-fonte atual pode atualizar os rótulos do produto quando uma alteração a <html lang> ou ao data-locale do loader altera o idioma resolvido. Confirme a versão do loader implementada antes de depender de atualizações em tempo real; este comportamento do loader alojado é distinto do SDK npm publicado 0.1.4. Os títulos personalizados e as mensagens de boas-vindas escritos pelo proprietário do projeto são apresentados tal como estão e não são traduzidos automaticamente. Um locale fornecido a mountWidget() passa a data-locale e segue a mesma política do projeto.
  • Se o widget estiver indisponível, verifique o pedido /widget-config e a chave pública. No widget.js v16 alojado do código-fonte atual, uma falha ao obter a configuração deixa o widget indisponível, em vez de o iniciar com valores predefinidos. Confirme a versão do loader implementada antes de depender deste comportamento.
  • Indexe cada versão linguística necessária se as respostas citarem ou recuperarem conteúdo no idioma errado. O gerador deteta o idioma da pergunta, independentemente do idioma da interface do widget: o idioma Fixo não impõe o idioma da resposta nem traduz o conteúdo de origem. Quando não há uma mensagem personalizada assistant.fallbackMessage, a resposta incorporada para conteúdo em falta usa o idioma detetado na pergunta quando apropriado, o idioma da interface do widget quando a deteção é incerta e o inglês como opção final.

Sem citações ou respostas fracas​

O ChattyBox utiliza conteúdo de origem recuperado para gerar respostas. A falta de citações ou as respostas fracas podem resultar de conteúdo de origem em falta ou inadequado, problemas de recuperação ou falhas de geração; por si só, não identificam a causa.

Um chatbot RAG fundamentado nas fontes beneficia de conteúdo de origem recuperado e claro, mas uma citação, por si só, não verifica uma resposta. Compare cada afirmação importante com a página citada.

Correções:

  • Faça a mesma pergunta no chat de teste do dashboard e compare as páginas citadas.
  • Confirme que a página de origem é pública e está incluída no scraping.
  • Acrescente à página de origem títulos claros, exemplos, perguntas frequentes e respostas diretas.
  • Não dependa apenas de capturas de ecrã, vídeos, markup oculto excluído, conteúdo disponível apenas por JavaScript ou iframes.
  • Volte a executar o scraping da página atualizada quando o cooldown o permitir, aguarde pela conclusão do processamento de embeddings e teste novamente.
  • Procure avisos de Indexação parcial: o texto acima do limite de 512 KiB por página não é conservado. Divida páginas de origem longas em vez de reconstruir repetidamente o mesmo texto truncado.
  • Sempre que possível, formule perguntas claras e autónomas. O gerador de respostas pode receber até 12 mensagens guardadas recentes, cada uma limitada a 2.000 caracteres; não recebe a transcrição completa da conversa.

Persona acrescenta instruções específicas do site às regras de fundamentação incorporadas; não pode fornecer conteúdo indexado em falta nem substituir a resposta de fallback para falta de contexto ou lacunas de conteúdo quando esta é acionada. O detetor de lacunas de conteúdo é heurístico e pode não detetar todas as respostas sem suporte nas fontes. Essa resposta tem uma definição separada, assistant.fallbackMessage, em configuração como código.

Páginas não recolhidas ou com conteúdo desatualizado​

Causas comuns:

  • A página não consta do sitemap enviado.
  • O modo de URL manual não incluiu a página.
  • A página bloqueia pedidos HTTP normais, requer autenticação, devolve uma página CAPTCHA/de erro ou redireciona para um destino bloqueado.
  • O conteúdo da página foi alterado depois do último scraping.
  • O conteúdo é apresentado apenas por JavaScript ou está fora da raiz semântica selecionada.
  • Os URLs selecionados excederam o limite de páginas, o orçamento mensal de atualizações esgotou-se ou uma regra de inclusão/exclusão filtrou-os.

Correções:

  1. Confirme que a página está acessível publicamente numa janela privada do navegador.
  2. Utilize o modo sitemap para uma cobertura ampla ou URLs manuais para um conjunto selecionado.
  3. Envie o URL canónico em vez de um URL de rastreamento, de redirecionamento ou de início de sessão.
  4. Volte a executar o scraping depois de publicar as alterações e de passar o cooldown: pelo menos sete dias desde a criação do trabalho mais recente no Free, ou 24 horas nos planos pagos, mesmo que esse trabalho tenha falhado.
  5. Em Conhecimento → Páginas, abra Histórico de importações quando existirem tarefas e selecione uma tarefa em Tarefas de recolha. Compare as suas contagens de páginas guardadas/selecionadas e a lista Páginas com os URLs pretendidos. Concluído pode incluir URLs ignorados ou falhados; Concluída com avisos assinala especificamente texto de página conservado parcialmente, não todas as falhas de recolha. A interface não disponibiliza uma lista completa de falhas por URL.

O ChattyBox não aplica as diretivas de rastreamento de robots.txt, mas pode ler o ficheiro para descobrir declarações de sitemaps. Não trate robots.txt como um mecanismo de controlo de acesso. O ChattyBox segue redirecionamentos HTTP seguros, pelo que um redirecionamento, por si só, não é uma falha. Não remova proteções de acesso nem coloque conteúdo privado num URL público para o tornar acessível ao scraping.

Se um URL tiver sido removido do site ou da seleção de origens, a página guardada ainda poderá ser utilizada. Elimine-a também em Conhecimento → Páginas, além de a excluir de futuras descobertas. Reconstruir índice utiliza o texto guardado, não volta a obter a página pela rede e tem um período de espera próprio do plano, além de consumir o orçamento mensal de atualizações.

As definições não são guardadas​

As alterações aos detalhes do chatbot e às definições das origens são guardadas automaticamente. Verifique o estado da gravação, resolva os erros de validação ou tente novamente uma gravação falhada antes de continuar. O dashboard exige um Website URL guardado mesmo quando introduz URLs manuais. A descoberta e a gravação automática não iniciam uma importação; reveja as páginas selecionadas e inicie a importação explicitamente.

Se o projeto estiver com a Configuração bloqueada, a configuração tem de ser implementada através do fluxo CLI. O bloqueio é irreversível; guardar Persona, alterar a configuração de recolha, Recolher agora, eliminar conteúdo e reconstruir o índice são operações rejeitadas, mesmo que os controlos continuem visíveis. Apenas a preferência de marca continua editável no dashboard, na configuração do widget alojado, consoante o plano. As chaves públicas do widget e os tokens de implementação são credenciais distintas.

Se o projeto não aparecer ou o acesso for recusado, confirme que iniciou sessão como proprietário. Uma chave do widget, um token de implementação ou a adesão a uma organização não concede permissões de proprietário no dashboard. Em Conversas, Análises e Perguntas sem resposta estão incluídas nos planos Pro e Business; as vistas indisponíveis apresentam uma opção de atualização do plano. Histórico está disponível em todos os planos.

Continua com dificuldades?​

Reúna estes dados antes de contactar o suporte:

  • O URL da página pública onde o widget deveria aparecer.
  • Uma captura de ecrã ou cópia de qualquer erro da consola do navegador.
  • Se a página utiliza HTML simples, Next.js, Docusaurus, WordPress, um CMS ou Google Tag Manager.
  • Se o snippet inclui data-api-key e data-api-url.
  • Uma pergunta de teste que deveria funcionar e a página de origem que contém a resposta.