Pular para o conteúdo principal
ChattyBox Logo

:::note Estado da versão O SDK npm publicado 0.1.4 com widget.js v15 suporta teardown por remove() ou window.ChattyBox.destroy(): remove UI/estilos e cancela inicialização, tentativas e chats pendentes. O chat v15 faz no máximo 10 tentativas num orçamento de agendamento de 30 s, não num timeout rígido por pedido. sendMessage() headless não tenta novamente automaticamente. :::

Personalização do widget hospedado

Definições guardadas aplicam-se apenas na próxima inicialização; recarregue a página. O locale da UI resolve-se uma vez: override de script permitido, depois default fixed ou, em auto, <html lang>, navegador e default. A UI traduzida não garante o idioma ou a qualidade da resposta.

Personalize a interface pronta carregada por https://chattybox.ai/widget.js. Para exemplos oficiais de instalação por framework e plataforma, consulte os Guias de instalação.

Antes de personalizar​

Crie o projeto, indexe seu conteúdo e verifique respostas representativas no Test Chat antes de dedicar tempo à apresentação. Consulte Primeiros passos para ver a sequência completa.

Configure o widget hospedado​

  1. Acesse o painel e selecione seu projeto.
  2. Navegue até a aba Embed.
  3. Visualize e salve a aparência e o comportamento de idioma do widget.

A aba Embed controla a apresentação e gera o código de instalação, mas as chaves públicas são gerenciadas separadamente. Quando estiver pronto para instalar:

  1. Abra Public Keys e crie uma chave para o navegador.
  2. Restrinja as origens permitidas aos domínios pretendidos do site.
  3. Volte a Embed, selecione a chave e copie o snippet gerado.
  4. Siga os Guias de instalação da sua plataforma.
<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>
dica

As alterações de apresentação do widget salvas no painel são aplicadas sem que você precise substituir o snippet no site.

Personalização visual​

O ChattyBox inclui um editor visual totalmente integrado. Você pode ajustar a aparência do widget para combinar perfeitamente com sua marca sem tocar em código.

Controles do painel​

  1. Accent Color – Escolha a cor principal da sua marca. Ela afeta o launcher, os destaques principais e as mensagens do usuário.

  2. Position – Escolha onde o widget aparece na tela.

  3. Header Title – Defina o título exibido na parte superior da janela de chat.

  4. Welcome Message – Personalize a primeira mensagem que os visitantes veem ao abrir o chat.

observação

As alterações feitas no painel são aplicadas imediatamente. Você não precisa atualizar o código de incorporação no site.

Opções avançadas​

Configurações do painel e atributos do script​

A maior parte do comportamento do widget deve ser gerenciada pelo painel, para que você não precise reimplantar o site para fazer alterações simples.

Use o painel para cores, posição, ícone, título do cabeçalho, mensagem de boas-vindas, idiomas padrão, gerenciamento de chaves públicas, scraping e Analytics.

Se o projeto usar restrições de origem para chaves públicas, mantenha essas restrições sincronizadas com os domínios em que o widget está instalado.

Use atributos de script apenas para valores de que o widget precisa no carregamento da página:

  • data-api-key identifica a chave pública do widget.
  • data-api-url informa ao widget para onde enviar solicitações. Em produção, é uma URL estável https://...convex.site/chat do seu painel.
  • data-locale solicita um idioma específico da interface do widget na inicialização somente se o projeto permitir substituições por script.

Se o widget não aparecer após a instalação, consulte a solução de problemas.

Para exemplos específicos de cada plataforma, comece por Docusaurus, MkDocs, VitePress, WordPress ou GitBook.

Ocultar o widget em páginas específicas​

Se precisar ocultar o widget em páginas selecionadas, você pode fazer isso com CSS:

.chattybox-widget {
  display: none;
}

Integrações personalizadas​

Precisa de uma configuração mais específica do que o widget hospedado? Crie sua própria interface com o SDK JavaScript ou entre em contato com support@chattybox.ai para obter ajuda de arquitetura.

Suporte multilíngue​

O widget do ChattyBox resolve o locale da UI na inicialização, de acordo com o modo Fixed ou Auto do projeto; não observa alterações posteriores de atributos ou rotas do cliente.

Idiomas oficialmente compatíveis​

O widget possui catálogos de tradução para 14 idiomas. A existência de um catálogo não significa que todas as strings visíveis ou acessíveis estejam traduzidas e não garante a qualidade das respostas.

IdiomaCódigo
Inglêsen
Francêsfr
Alemãode
Espanholes
Italianoit
Holandêsnl
Portuguêspt
Polonêspl
Suecosv
Indonésioid
Estonianoet
Finlandêsfi
Galêscy
Tchecocs

:::note Idioma da UI e respostas O locale da UI não é enviado como parâmetro de idioma do chat. O backend detecta o idioma da pergunta e tenta recuperação e geração sensíveis ao idioma; o idioma e a qualidade das respostas dependem do conteúdo indexado e do modelo. :::

Como funciona a detecção de idioma​

O widget usa um sistema de detecção em cascata:

  1. Substituição de script permitida – Um data-locale não vazio vence somente quando allowLocaleOverride não é false, inclusive no modo Fixed.
  2. Modo Fixed – Sem uma substituição permitida, usa defaultLocale.
  3. Modo Auto – Usa o primeiro valor não vazio entre <html lang> da página, navigator.language do navegador (ou o antigo userLanguage) e, por fim, defaultLocale.
  4. Normalização – Valores regionais compatíveis, como fr-CA, são reduzidos ao código base; um valor incompatível muda imediatamente para inglês sem tentar o candidato seguinte.

Substituição manual do idioma​

Para solicitar um idioma específico independentemente das configurações do navegador, habilite Allow Script Override e adicione o atributo data-locale antes da execução do loader:

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

:::tip Caso de uso Isso é especialmente útil se você tem um site multilíngue em que cada versão de idioma possui sua própria URL (por exemplo, /de/, /fr/). Defina data-locale de acordo com o idioma de cada página e verifique a interface renderizada. :::

Configurações de idioma do painel​

O painel do aplicativo permite configurar as preferências de idioma do widget por projeto:

  • Auto-detect – Usa o idioma da página antes do idioma do navegador do visitante.
  • Fixed Language – Usa o idioma padrão configurado, salvo uma substituição data-locale permitida.
  • Allow Script Override – Ativa ou desativa a substituição pelo atributo data-locale.

Acesse essas configurações no painel → Projeto → aba Embed → seção Widget Language.

Correspondência do idioma do conteúdo​

Para uma experiência multilíngue útil, indexe conteúdo público nos idiomas dos visitantes e teste as fontes; a detecção e a recuperação não são garantidas. Para isso:

  1. Faça scraping de todas as versões de idioma da documentação usando o arquivo sitemap.xml.
  2. O scraper tenta detectar o idioma da página; inspecione o conteúdo e as citações.
  3. A recuperação tenta preferir o idioma da pergunta, mas pode recorrer a outro conteúdo indexado.

Configuração no painel do aplicativo: ao configurar o scraping, use a URL do seu sitemap.xml (por exemplo, https://yourdocs.com/sitemap.xml) para descobrir versões de idioma e, depois, verifique as páginas indexadas. Sitemaps não ignoram limites de rastreamento ou exclusões.

Solução de problemas​

O widget continua sendo exibido em inglês​

  • Atualização forçada para diagnóstico – Recarregue com Ctrl+F5 ou Cmd+Shift+R e verifique as solicitações do widget e de tradução no painel de rede do navegador.
  • Verifique data-locale – Confirme se o atributo está definido corretamente com um código de idioma compatível.
  • Verifique o idioma do navegador – Confirme se o idioma preferido do navegador está configurado corretamente.
  • Verifique o lang do HTML da página – Certifique-se de que a página contenha <html lang="de"> (ou o código adequado).

As fontes estão no idioma errado​

  • Faça novo scraping do conteúdo – Verifique se todas as versões de idioma estão indexadas.
  • Use sitemap.xml – Confirme que as URLs desejadas foram realmente indexadas; limites de rastreamento e exclusões podem omiti-las.
  • Verifique o idioma da consulta – A IA tenta corresponder o idioma da resposta ao idioma da consulta.

Faltam traduções​

  • Verifique os idiomas compatíveis – Apenas os 14 códigos acima têm catálogos; rótulos ausentes podem usar o fallback em inglês.

Práticas recomendadas​

  1. Defina <html lang> nas páginas – Isso ajuda na acessibilidade e na detecção do widget.
  2. Teste com data-locale durante o desenvolvimento – Verifique se cada idioma é exibido corretamente.
  3. Faça scraping de todas as versões de idioma – Use sitemap.xml para descoberta e verifique as páginas indexadas.
  4. Monitore a distribuição de idiomas – Consulte o Analytics para ver quais idiomas os visitantes usam com mais frequência.

Preferências de privacidade

Utilizamos ferramentas opcionais de análise e gestão de tags para compreender a utilização do site. Escolha se pretende permitir o Ahrefs Web Analytics, o PostHog e o Google Tag Manager. Ao desativar a análise, esta página será recarregada para que a alteração seja aplicada corretamente. A funcionalidade essencial do site e a monitorização de erros não são controladas por esta escolha. Leia a nossa política de privacidade.