Personalização do widget hospedado

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 opcionalmente força um idioma específico da interface do widget para a página.

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 se adapta automaticamente às preferências de idioma dos visitantes, oferecendo uma experiência localizada para usuários em todo o mundo.

Idiomas oficialmente compatíveis

A interface do widget (botões, rótulos e mensagens do sistema) é oficialmente compatível com 14 idiomas:

Idioma	Código	Interface do widget	Qualidade das respostas de IA
Inglês	en	Suporte completo	Excelente
Francês	fr	Suporte completo	Alta
Alemão	de	Suporte completo	Alta
Espanhol	es	Suporte completo	Alta
Italiano	it	Suporte completo	Alta
Holandês	nl	Suporte completo	Alta
Português	pt	Suporte completo	Alta
Polonês	pl	Suporte completo	Alta
Sueco	sv	Suporte completo	Alta
Indonésio	id	Suporte completo	Média
Estoniano	et	Suporte completo	Média
Finlandês	fi	Suporte completo	Média
Galês	cy	Suporte completo	Média
Tcheco	cs	Suporte completo	Média

:::note Suporte estendido a idiomas Embora ofereçamos suporte oficial a 14 idiomas para a interface do widget, a IA subjacente consegue entender e responder em mais de 100 idiomas. No entanto, não podemos garantir respostas de alta qualidade para idiomas fora da lista oficial. :::

Como funciona a detecção de idioma

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

1. Atributo data-locale – Tem a maior prioridade. Defina-o no código de incorporação para forçar um idioma específico.
2. Atributo <html lang> da página – O widget verifica o idioma declarado da página.
3. Idioma do navegador (navigator.language) – Usa as preferências do navegador do visitante.
4. Fallback padrão – Inglês quando nenhum idioma é detectado.

Substituição manual do idioma

Para forçar a exibição do widget em um idioma específico, independentemente das configurações do navegador, adicione o atributo data-locale:

<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 para manter uma experiência consistente. :::

Configurações de idioma do painel

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

• Auto-detect (recomendado) – Corresponde automaticamente ao idioma do navegador do visitante.
• Fixed Language – Força o widget a sempre ser exibido em um idioma específico.
• 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 obter a melhor experiência multilíngue, o chatbot deve responder no mesmo idioma da pergunta do usuário. Para isso:

1. Faça scraping de todas as versões de idioma da documentação usando o arquivo sitemap.xml.
2. O scraper marcará automaticamente o conteúdo com seu idioma.
3. O sistema RAG recuperará a versão de idioma adequada com base na consulta.

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 e indexar automaticamente todas as versões de idioma do conteúdo.

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 – Isso garante que o scraper encontre todas as URLs /de/, /fr/ etc.
• 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 idiomas listados acima têm traduções de UI garantidas.

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 uma indexação multilíngue abrangente.
4. Monitore a distribuição de idiomas – Consulte o Analytics para ver quais idiomas os visitantes usam com mais frequência.