Pular para o conteúdo principal

:::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​

  1. Aceda ao painel e selecione o projeto.
  2. Abra Personalizar → Aparência para editar o aspeto, a marca e as definições de Idioma.
  3. 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:

  1. 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.
  2. 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.
  3. Opcionalmente, ative restrições exatas de origem como reforço de segurança; estas não autenticam visitantes.
  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 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​

  1. Cor de destaque – Escolha a cor principal da marca. Afeta o botão de abertura, os destaques principais e as mensagens dos utilizadores.

  2. Posição do widget – Escolha onde o widget aparece no ecrã.

  3. Título do cabeçalho – Defina o título apresentado na parte superior da janela de chat.

  4. Mensagem de boas-vindas – Personalize a primeira mensagem que os visitantes veem quando abrem o chat.

  5. 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.

observação

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:

CampoPredefinição
enabledtrue, salvo se estiver desativado no projeto
themeColor#3b82f6
chatBgColor#0f172a
textColor#f8fafc
positionbottom-right; são suportados os quatro cantos
iconType, iconSizedefault, medium; o loader alojado v16 do código-fonte atual usa o tamanho para o botão de abertura e o ícone
iconEmoji, iconUrlEmoji de balão de fala, null
headerTitleChat with us (valor predefinido da API)
welcomeMessageHi! 👋 How can I help you today? (valor predefinido da API)
showBrandingtrue; obrigatório nos projetos Free
localeMode, defaultLocale, allowLocaleOverrideauto, 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-key identifica a chave pública do widget.
  • data-api-url informa o widget para onde enviar pedidos. Em produção, é um URL estável https://...convex.site/chat do painel.
  • data-locale define 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-color e data-position substituem 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.

IdiomaCódigo
Inglêsen
Francêsfr
Alemãode
Espanholes
Italianoit
Neerlandêsnl
Portuguêspt
Polacopl
Suecosv
Indonésioid
Estonianoet
Finlandêsfi
Galêscy
Checocs

:::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:

  1. Substituição de script permitida – Um data-locale suportado tem prioridade se allowLocaleOverride não for false, mesmo no modo fixo.
  2. Modo fixo – Sem uma substituição permitida e suportada, usa defaultLocale e ignora o idioma da página e do browser.
  3. Modo automático – Experimenta <html lang>, navigator.language, cada valor de navigator.languages, o antigo userLanguage e, por fim, defaultLocale, escolhendo o primeiro idioma suportado.
  4. 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-locale substitua 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:

  1. Faça scraping de todas as versões linguísticas da documentação usando o ficheiro sitemap.xml.
  2. O scraper tenta detetar 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 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 lang do 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​

  1. Defina <html lang> nas páginas – Ajuda na acessibilidade e na deteção do widget.
  2. Teste com data-locale durante o desenvolvimento – Verifique se cada idioma é apresentado corretamente.
  3. Faça scraping de todas as versões linguísticas – Use sitemap.xml para descoberta e verifique as páginas indexadas.
  4. 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.