:::note Código-fonte e versões
No checkout atual, o código-fonte do loader alojado é widget.js v16; isso não identifica a versão carregada pelo seu site. Verifique a versão efetivamente disponibilizada antes de confiar no comportamento do código-fonte atual. O SDK npm publicado 0.1.4 partilha instâncias de mount com opções idênticas: execute remove() em cada handle correspondente; só a última remoção inicia o teardown. O sendMessage() headless não tenta novamente automaticamente.
:::
Personalização do widget alojado
Personalize a interface pronta a utilizar carregada por https://chattybox.ai/widget.js. Para exemplos canónicos de instalação em frameworks e plataformas, consulte os Guias de instalação.
Antes de personalizar
Crie o projeto, indexe o conteúdo e verifique respostas representativas em Testar chatbot antes de dedicar tempo à apresentação. Consulte Primeiros passos para ver a sequência completa.
Configure o widget alojado
- Aceda ao painel e selecione o projeto.
- Abra Personalizar → Aparência para editar o aspeto, a marca e as definições de Idioma.
- Confirme o estado de gravação automática relevante; corrija erros de validação ou tente novamente as gravações falhadas antes de testar o widget instalado.
O código de instalação e as chaves públicas são geridos em Instalar. Quando estiver pronto para instalar:
- Abra Instalar → Chaves e domínios para consultar ou criar uma chave pública para o browser e verificar as definições de origem. Se necessário, utilize Editar origens.
- Em Instalar → Instalação no site, selecione uma chave adequada e copie o excerto gerado. Uma chave criada sem restrições funciona em todas as origens; uma chave preparada para um site pode já estar limitada à origem desse site. Confirme a chave selecionada antes de a utilizar em staging ou localhost.
- Opcionalmente, ative restrições exatas de origem como reforço de segurança; estas não autenticam visitantes.
- 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>
As alterações de apresentação guardadas no painel são aplicadas na próxima inicialização do widget; não é necessário substituir o excerto no site. As páginas já abertas não são atualizadas em tempo real: volte a carregá-las para obter as definições guardadas.
No código-fonte atual, se a obtenção da configuração falhar ou a resposta for inválida, o widget fica indisponível e não apresenta uma interface alternativa. Uma resposta válida com enabled: false também impede a apresentação do widget; a API de chat rejeita pedidos com HTTP 403 quando o widget está desativado, incluindo pedidos do SDK. Este caso é diferente de uma falha na obtenção da configuração. Se a configuração for obtida com sucesso, mas o carregamento das traduções falhar, o widget pode ser apresentado com os rótulos em inglês incorporados. Verifique o loader disponibilizado antes de confiar nestes comportamentos do código-fonte atual.
Personalização visual
Na secção Aspeto do widget do editor do painel, pode ajustar as cores suportadas, a posição, o ícone e o texto sem alterar o código do site. Confirme o resultado no widget alojado, uma vez que a pré-visualização e o loader não são idênticos.
Controlos do painel
-
Cor de destaque – Escolha a cor principal da marca. Afeta o botão de abertura, os destaques principais e as mensagens dos utilizadores.
-
Posição do widget – Escolha onde o widget aparece no ecrã.
-
Título do cabeçalho – Defina o título apresentado na parte superior da janela de chat.
-
Mensagem de boas-vindas – Personalize a primeira mensagem que os visitantes veem quando abrem o chat.
-
Mostrar a marca ChattyBox – A identificação da marca é obrigatória no plano Gratuito. Os planos Starter e superiores podem ocultar a identificação no rodapé.
O editor também inclui os controlos Fundo do widget, Cor do texto e Ícone do widget. As opções do ícone são Predefinido, Emoji, URL da imagem e Carregar; a opção Tamanho do ícone só é apresentada quando seleciona URL da imagem ou Carregar, permitindo escolher pequeno, médio ou grande. As imagens carregadas podem ter, no máximo, 512 KiB e devem utilizar um tipo MIME de imagem aceite (PNG, JPEG, WebP, SVG, GIF ou ICO). O código-fonte do loader alojado v16 utiliza iconSize para dimensionar o botão de abertura e o ícone; verifique o loader disponibilizado antes de confiar neste comportamento.
Confirme o estado de gravação automática relevante e, em seguida, volte a carregar a página instalada para verificar as alterações. A pré-visualização do painel é uma simulação, não o widget alojado. Nos projetos bloqueados por config-as-code, o aspeto e o idioma são geridos pela configuração; os projetos com essa capacidade podem continuar a guardar separadamente a preferência de marca.
Valores predefinidos da configuração
Estes são os valores devolvidos por um pedido público de configuração do widget bem-sucedido quando não existe um valor personalizado:
| Campo | Predefinição |
|---|---|
enabled | true, salvo se estiver desativado no projeto |
themeColor | #3b82f6 |
chatBgColor | #0f172a |
textColor | #f8fafc |
position | bottom-right; são suportados os quatro cantos |
iconType, iconSize | default, medium; o loader alojado v16 do código-fonte atual usa o tamanho para o botão de abertura e o ícone |
iconEmoji, iconUrl | Emoji de balão de fala, null |
headerTitle | Chat with us (valor predefinido da API) |
welcomeMessage | Hi! 👋 How can I help you today? (valor predefinido da API) |
showBranding | true; obrigatório nos projetos Free |
localeMode, defaultLocale, allowLocaleOverride | auto, en, true (valores predefinidos) |
Opções avançadas
Configurações do painel e atributos do script
A maior parte do comportamento do widget deve ser gerida no painel, para não ter de voltar a implementar o site para fazer alterações simples.
Use o painel para cores, posição, ícone, título, mensagem de boas-vindas, definições de idioma, gestão de chaves públicas, scraping e análises.
As chaves públicas foram concebidas para utilização em código do browser: identificam o projeto, mas não são credenciais de gestão nem autenticam visitantes. Uma chave criada sem restrições funciona em produção, pré-visualizações, staging e localhost; uma chave preparada para um site pode já estar limitada à origem desse site. As restrições de origem são opcionais e reforçam a proteção; se as ativar, mantenha as origens exatas sincronizadas com os domínios onde o widget está instalado.
Use os atributos de script para definir os valores iniciais de que o widget precisa ao carregar a página:
data-api-keyidentifica a chave pública do widget.data-api-urlinforma o widget para onde enviar pedidos. Em produção, é um URL estávelhttps://...convex.site/chatdo painel.data-localedefine o idioma inicial da interface do widget se o projeto permitir substituições por script. O loader no código-fonte atual também observa alterações posteriores a este atributo.data-coloredata-positionsubstituem a cor de destaque e a posição guardadas, mas apenas após a obtenção bem-sucedida da configuração. Prefira as definições do painel; estes atributos podem ocultar alterações posteriores feitas no painel.data-debug="true"ativa diagnósticos na consola do browser; está desativado por predefinição.
Para cada mensagem nova, o widget alojado do código-fonte atual tenta enviar a origem e o caminho da página HTTP(S) atual para as análises de Gatilhos populares, sem verificar se a página é pública. O contexto inválido ou demasiado longo é omitido; as novas tentativas reutilizam o contexto original. São removidos parâmetros de consulta, fragmentos e credenciais, mas os caminhos podem conter identificadores sensíveis. O widget também respeita prefers-reduced-motion, disponibiliza um campo de mensagem com etiqueta e anúncios em tempo real, e apresenta citações numa secção expansível Fontes, acessível pelo teclado.
O contexto da página é obtido a partir do URL HTTP(S) atual, não de uma verificação de que a página é pública. Não carregue o widget em rotas sensíveis apenas porque os parâmetros de consulta são removidos. O loader também pode enviar erros de inicialização, configuração, tradução e chat para /widget-error através de beacon ou fetch, incluindo detalhes de erro limitados, idioma, versão e origem/caminho da página. Estes relatórios não dependem da ativação do modo de depuração.
O chat utiliza respostas JSON completas, não streaming de tokens. O código-fonte do loader alojado v16 cria uma chave de idempotência por mensagem e agenda, no máximo, 10 tentativas automáticas de transporte para erros de rede, corpos de respostas bem-sucedidas interrompidos, HTTP 429, HTTP 5xx e respostas 409 com um cabeçalho Retry-After legível. Não agenda outra tentativa se o atraso exceder o limite de 30 segundos; este não é um timeout rígido para um pedido já em curso. O CORS do browser pode ocultar Retry-After. Esta política não se aplica ao sendMessage() headless; as novas tentativas dos pedidos GET de inicialização do loader e o fallback de configuração após HTTP 400 do SDK 0.1.4 são comportamentos separados e limitados. Para obter a configuração, o loader v16 tenta primeiro Authorization: Bearer e só volta a tentar com a chave na query string após HTTP 400. O SDK publicado 0.1.4 segue o mesmo fallback apenas para a configuração quando a página disponibiliza window.ChattyboxSDK. O envio de mensagens utiliza o transporte próprio do loader. O estado da conversa permanece na memória dessa instância do widget e perde-se ao recarregar ou reinicializar; as mensagens já guardadas no servidor podem permanecer. As fontes são deduplicadas e limitadas a três entradas apresentadas; as respostas de fallback podem não incluir fontes. Verifique o loader disponibilizado antes de confiar no comportamento do código-fonte atual.
Se o widget não aparecer após a instalação, consulte a resoluçã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
Para ocultar visualmente o widget, aplique o seguinte CSS apenas às páginas selecionadas (se o aplicar globalmente, o widget fica oculto em todas as páginas):
.chattybox-widget {
display: none;
}
Ocultar com CSS não impede a inicialização, os pedidos à API ou o envio de relatórios de erro e não é um controlo de consentimento ou privacidade. O loader não decide se existe consentimento: só insira o script depois de obter o consentimento necessário e impeça a sua reinserção após a revogação ou em rotas excluídas. Para transições de rota do lado do cliente ou revogação do consentimento, o código-fonte atual de widget.js v16 disponibiliza window.ChattyBox.destroy(). Com o SDK 0.1.4, remova todos os handles de mount correspondentes: o último sinaliza o teardown. Verifique se o loader disponibilizado suporta teardown; remover apenas a etiqueta do script não é suficiente. O teardown remove a interface e os estilos pertencentes ao widget e cancela o trabalho pendente, mas não anula pedidos já processados pelo servidor.
Controlos do browser
No código-fonte de widget.js v16, window.ChattyBox existe durante o carregamento, com status: 'loading' e destroy(). Após a inicialização bem-sucedida, verifique window.ChattyBox?.status === 'ready' antes de chamar open(), close(), toggle() ou sendMessage(text). destroy() remove o widget e os estilos pertencentes à instância, interrompe o respetivo trabalho e elimina o objeto global; não anula pedidos já processados pelo servidor. close() fecha apenas o painel de chat; o botão de abertura continua visível. sendMessage(text) devolve uma promise da operação de interface, não uma promise da resposta; os envios são ignorados enquanto outra mensagem estiver pendente. Este objeto global é distinto dos construtores do SDK em window.ChattyboxSDK. Verifique a versão do loader disponibilizado antes de confiar neste comportamento.
Temas claros/escuros controlados pelo site (código-fonte atual)
O fluxo config-as-code do código-fonte atual suporta paletas opcionais em widget.theme.light e widget.theme.dark. Cada uma aceita primaryColor, backgroundColor e textColor como cores hexadecimais de seis dígitos; as cores omitidas herdam os valores base de widget.theme. As configurações existentes com um único tema continuam a funcionar sem alterações. Esta funcionalidade requer o CLI/backend do código-fonte atual e o loader alojado v16; o CLI/config publicado 0.3.1 não aceita estes novos campos. Verifique a versão do loader disponibilizado antes de confiar neste comportamento.
Defina data-theme="light" ou data-theme="dark" no script do loader antes da sua execução para selecionar a paleta inicial. Depois, ligue o seletor do seu site à API do browser:
window.ChattyBox?.setTheme('light');
window.ChattyBox?.setTheme('dark');
window.ChattyBox?.setTheme(null); // Restore the configured base appearance.
O widget atualiza os estilos existentes sem reiniciar mensagens, fontes, texto do rascunho ou um pedido pendente. A seleção do tema não pode desativar o widget nem remover a atribuição. O seu site gere a persistência das preferências e o comportamento do tema do sistema operativo; o widget apenas seleciona a paleta configurada.
Integrações personalizadas
Precisa de uma configuração mais específica do que o widget alojado? Crie a sua própria interface com o SDK JavaScript ou contacte support@chattybox.ai para obter aconselhamento sobre a arquitetura.
Suporte multilingue
O código-fonte local atual de widget.js v16 resolve o idioma da interface de acordo com o modo fixo ou automático do projeto. Observa alterações a <html lang> e ao atributo data-locale do script, atualizando os rótulos sem reiniciar a conversa, o rascunho ou uma nova tentativa pendente. A navegação, por si só, não seleciona outro idioma; atualize um desses atributos quando necessário. As alterações nas definições do painel exigem uma nova inicialização. Verifique a versão do loader disponibilizado antes de confiar nas atualizações dinâmicas do idioma.
Idiomas oficialmente compatíveis
O widget possui catálogos de tradução para 14 idiomas. Todos os catálogos atuais utilizam escrita da esquerda para a direita. Os textos escritos pelo projeto e as respostas geradas por IA não são traduzidos pelos catálogos da interface.
| Idioma | Código |
|---|---|
| Inglês | en |
| Francês | fr |
| Alemão | de |
| Espanhol | es |
| Italiano | it |
| Neerlandês | nl |
| Português | pt |
| Polaco | pl |
| Sueco | sv |
| Indonésio | id |
| Estoniano | et |
| Finlandês | fi |
| Galês | cy |
| Checo | cs |
:::note Idioma da UI e respostas O código-fonte atual do widget envia o idioma da interface resolvido com os pedidos de chat. O backend deteta o idioma da pergunta e tenta recuperar conteúdo e gerar respostas tendo em conta esse idioma. Um sinal reconhecido do idioma da pergunta tem prioridade sobre o idioma da interface nas mensagens de fallback do produto; se a deteção não for conclusiva ou se basear apenas na heurística de inglês baseada em caracteres ASCII, o idioma da interface pode determinar o idioma do fallback. Este não traduz texto de fallback escrito pelo projeto nem altera respostas geradas por IA. O idioma e a qualidade das respostas dependem do conteúdo indexado e do modelo; os catálogos da interface não garantem a qualidade das respostas. :::
Como funciona a deteção de idioma
No código-fonte local de widget.js v16, o widget usa um sistema de deteção em cascata:
- Substituição de script permitida – Um
data-localesuportado tem prioridade seallowLocaleOverridenão forfalse, mesmo no modo fixo. - Modo fixo – Sem uma substituição permitida e suportada, usa
defaultLocalee ignora o idioma da página e do browser. - Modo automático – Experimenta
<html lang>,navigator.language, cada valor denavigator.languages, o antigouserLanguagee, por fim,defaultLocale, escolhendo o primeiro idioma suportado. - Normalização – A comparação não distingue maiúsculas de minúsculas e os locales regionais reconhecidos (por exemplo,
fr-CA) são reduzidos ao idioma base suportado. Os candidatos não suportados são ignorados; se nenhum for suportado, usa inglês. Os valores predefinidos são o modo automático, inglês e substituições por script permitidas.
Os títulos personalizados e as mensagens de boas-vindas escritos pelo projeto são apresentados tal como estão; não são traduzidos automaticamente. Os textos predefinidos do widget no código-fonte atual usam rótulos localizados. Se a configuração tiver sido obtida com sucesso, mas o carregamento das traduções falhar, o widget inicia com os rótulos incorporados em inglês. Se a obtenção da configuração falhar, o widget fica indisponível. Verifique o loader disponibilizado antes de confiar neste comportamento.
Substituição manual do idioma
Para solicitar um idioma específico independentemente das definições do browser, ative Permitir substituição através de script 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
É especialmente útil se tiver um site multilingue em que cada versão tenha o seu próprio URL (por exemplo, /de/, /fr/). Defina data-locale de acordo com o idioma de cada página e verifique a interface apresentada.
:::
Configurações de idioma do painel
O painel da aplicação permite configurar as preferências de idioma do widget por projeto:
- Detetar automaticamente – Utiliza primeiro o idioma da página, depois os idiomas do browser e, por fim, o idioma predefinido configurado, salvo se uma substituição de script permitida tiver prioridade.
- Fixo – Utiliza o idioma de interface selecionado, exceto se Permitir substituição através de script estiver ativo e for fornecido
data-locale. - Permitir substituição através de script – Permite que o atributo
data-localesubstitua esta definição.
Aceda a estas definições no painel → Personalizar → Aparência → secção Idioma. Confirme o estado de gravação automática do idioma e corrija os erros ou tente guardar novamente antes de testar.
Correspondência do idioma do conteúdo
Para uma experiência multilingue útil, indexe conteúdo público nos idiomas dos visitantes e teste as fontes; a deteção e a recuperação não são garantidas. Para isso:
- Faça scraping de todas as versões linguísticas da documentação usando o ficheiro
sitemap.xml. - O scraper tenta detetar o idioma da página; inspecione o conteúdo e as citações.
- A recuperação tenta preferir o idioma da pergunta, mas pode recorrer a outro conteúdo indexado.
Configuração no painel da aplicação: ao configurar o scraping, use o URL do sitemap.xml (por exemplo, https://yourdocs.com/sitemap.xml) para descobrir versões linguísticas e, depois, verifique as páginas indexadas. Os sitemaps não contornam limites de rastreio nem exclusões.
Solução de problemas
O widget continua a ser apresentado em inglês
- Atualização forçada para diagnóstico – Recarregue com Ctrl+F5 ou Cmd+Shift+R e verifique os pedidos do widget e de tradução no painel de rede do browser.
- Verifique
data-locale– Confirme se o atributo está definido corretamente com um código de idioma compatível. - Verifique o modo do projeto e a permissão de substituição – O modo fixo e as substituições desativadas podem ignorar o idioma do browser ou
data-locale. - Verifique o idioma do browser – Confirme se o idioma preferido está configurado corretamente.
- Verifique o
langdo HTML da página – Certifique-se de que a página contém<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 os URLs pretendidos foram realmente indexados; limites de rastreio e exclusões podem omiti-los.
- 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; os rótulos em falta podem recorrer ao inglês.
Práticas recomendadas
- Defina
<html lang>nas páginas – Ajuda na acessibilidade e na deteção do widget. - Teste com
data-localedurante o desenvolvimento – Verifique se cada idioma é apresentado corretamente. - Faça scraping de todas as versões linguísticas – Use
sitemap.xmlpara descoberta e verifique as páginas indexadas. - Reveja perguntas reais – Consulte as conversas e as lacunas de conteúdo específicas de cada idioma; o painel não disponibiliza atualmente um relatório da distribuição de idiomas da interface do widget.