Pular para o conteúdo principal
ChattyBox Logo

Configuração e personalização do widget

Adicione ao seu site um widget de chat com IA em menos de 5 minutos.

Configuração rápida​

Colocar o chatbot online é simples. Basta copiar um pequeno trecho de código do painel.

Passo 1: obter o código de incorporação​

  1. Abra o painel e selecione o seu projeto.
  2. Aceda ao separador Incorporar.
  3. Escolha a chave API que pretende usar ou crie uma nova.
  4. Copie o trecho de código gerado.

Passo 2: adicionar ao seu site​

Cole o trecho imediatamente antes da etiqueta de fecho </body> em cada página onde pretende mostrar o widget.

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

:::tip Sugestão É tudo. Não precisa de configurar cores ou opções no código; tudo é gerido no painel. :::

Personalização visual​

O ChattyBox inclui um editor visual integrado. Pode ajustar o aspeto do widget à sua marca sem alterar código.

Controlos do painel​

  1. Cor de destaque - Escolha a cor principal da marca para o lançador, destaques e mensagens do utilizador.
  2. Posição - Escolha onde o widget aparece no ecrã.
  3. Título do cabeçalho - Defina o título no topo da janela de chat.
  4. Mensagem de boas-vindas - Personalize a primeira mensagem vista pelos visitantes.
observação

As alterações feitas no painel são aplicadas de imediato. Não precisa de atualizar o código de incorporação no site.

Opções avançadas​

Definições do painel versus atributos do script​

A maior parte do comportamento do widget deve ser gerida no painel, para evitar republicar o site por alterações simples.

Use o painel para cores, posição, ícone, título, mensagem de boas-vindas, idioma predefinido, chaves públicas, scraping e análises.

Se o projeto usa restrições de origem para chaves públicas, mantenha-as alinhadas com os domínios onde o widget está instalado.

Use atributos do script apenas para valores necessários ao carregamento da página:

  • data-api-key identifica a chave pública do widget.
  • data-api-url indica para onde o widget envia pedidos.
  • data-locale pode forçar um idioma específico da interface nessa página.

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

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

Ocultar o widget em páginas específicas​

Pode ocultar o widget em páginas selecionadas com CSS:

.chattybox-widget {
  display: none;
}

Integrações personalizadas​

Precisa de uma configuração mais ajustada do que o widget padrão?

Contacte-nos em [email protected] e ajudaremos a escolher a melhor integração para o seu caso.

Suporte multilingue​

O widget ChattyBox adapta-se automaticamente às preferências linguísticas dos visitantes e oferece uma experiência localizada.

Idiomas oficialmente suportados​

A interface do widget, incluindo botões, rótulos e mensagens do sistema, é oficialmente suportada em 14 idiomas:

IdiomaCódigoInterface do widgetQualidade das respostas de IA
InglêsenSuporte completoExcelente
FrancêsfrSuporte completoAlta
AlemãodeSuporte completoAlta
EspanholesSuporte completoAlta
ItalianoitSuporte completoAlta
NeerlandêsnlSuporte completoAlta
PortuguêsptSuporte completoAlta
PolacoplSuporte completoAlta
SuecosvSuporte completoAlta
IndonésioidSuporte completoMédia
EstónioetSuporte completoMédia
FinlandêsfiSuporte completoMédia
GalêscySuporte completoMédia
ChecocsSuporte completoMédia

:::note Suporte linguístico alargado Embora a interface suporte oficialmente 14 idiomas, a IA subjacente consegue compreender e responder em mais de 100 idiomas. Não garantimos, porém, a mesma qualidade para idiomas fora da lista oficial. :::

Como funciona a deteção de idioma​

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

  1. Atributo data-locale - Prioridade máxima. Defina-o no código para forçar um idioma.
  2. Atributo <html lang> da página - O widget verifica o idioma declarado pela página.
  3. Idioma do navegador (navigator.language) - Usa as preferências do visitante.
  4. Recurso predefinido - Inglês se nenhum idioma for detetado.

Substituição manual de idioma​

Para forçar o idioma do widget independentemente do navegador, adicione data-locale:

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

:::tip Caso de uso Isto é útil quando um site multilingue tem URLs separadas por idioma, como /de/ ou /fr/. Defina data-locale de acordo com a língua da página para manter uma experiência consistente. :::

Definições de idioma no painel​

O painel da aplicação permite configurar preferências de idioma do widget por projeto:

  • Deteção automática (recomendado) - Corresponde automaticamente ao idioma do navegador do visitante.
  • Idioma fixo - Obriga o widget a usar sempre um idioma específico.
  • Permitir substituição por script - Ativa ou desativa a substituição via data-locale.

Encontra estas opções no painel → Projeto → Incorporar → Idioma do widget.

Correspondência com o idioma do conteúdo​

Para a melhor experiência multilingue, o chatbot deve responder no mesmo idioma da pergunta do utilizador. Para isso:

  1. Faça scraping de todas as versões linguísticas da documentação com sitemap.xml.
  2. O scraper etiqueta automaticamente o conteúdo com o idioma correto.
  3. O sistema RAG recupera a versão linguística adequada à consulta.

Configuração no painel: ao configurar o scraping, use o URL sitemap.xml, por exemplo https://yourdocs.com/sitemap.xml, para descobrir e indexar automaticamente todas as versões linguísticas.

Resolução de problemas​

O widget continua em inglês​

  • Limpe a cache do navegador - O ficheiro widget.js pode estar em cache. Faça uma atualização forçada (Ctrl+F5 / Cmd+Shift+R).
  • Verifique data-locale - Confirme que o atributo usa um código de idioma suportado.
  • Verifique o idioma do navegador - Confirme que a preferência está correta.
  • Verifique o HTML lang - A página deve usar <html lang="pt-PT"> ou o código apropriado.

As fontes estão no idioma errado​

  • Repita o scraping do conteúdo - Garanta que todas as versões linguísticas foram indexadas.
  • Use sitemap.xml - Assim o scraper encontra URLs como /de/ e /fr/.
  • Verifique o idioma da pergunta - A IA tenta alinhar a resposta com a língua da consulta.

Traduções em falta​

  • Verifique os idiomas suportados - Só os 14 idiomas acima têm traduções de interface garantidas.

Boas práticas​

  1. Defina <html lang> nas páginas - Ajuda a acessibilidade e a deteção do widget.
  2. Teste com data-locale durante o desenvolvimento - Confirme que cada idioma aparece corretamente.
  3. Faça scraping de todas as versões linguísticas - Use sitemap.xml para indexação multilingue completa.
  4. Monitorize a distribuição de idiomas - Veja nas análises quais línguas os visitantes usam mais.