Guias de instalação

:::note Estado da versão O SDK npm publicado 0.1.4 com widget.js v15 suporta teardown por remove() ou window.ChattyBox.destroy() e cancela trabalho pendente. :::

Instale apenas um loader e mantenha-o numa shell persistente. O SDK publicado 0.1.4 partilha o script apenas entre mounts com opções idênticas e rejeita uma chave, endpoint, URL de script, locale ou definição de depuração diferente enquanto existirem handles. Remova todos os handles do SDK para desmontar; só o último sinaliza à widget.js v15 hospedada para destruir a interface e os estilos próprios e cancelar a inicialização pendente, as tentativas de repetição e o chat em curso. O widget não acompanha as alterações às definições do dashboard: reinicialize-o para obter as definições guardadas. No código-fonte atual, a widget.js v16 hospedada pode atualizar os rótulos do produto quando uma alteração de <html lang> ou data-locale muda a locale resolvida, de acordo com a política de locale do projeto. Confirme a versão do loader implementada antes de depender de atualizações em tempo real; este comportamento é independente da versão publicada do SDK npm. data-locale solicita o idioma na inicialização apenas quando as substituições do script são permitidas. As restrições de origem, quando ativadas, verificam Origin ou a origem de Referer como alternativa; origens em falta ou não permitidas produzem 401 Invalid API key. Não são autenticação.

As tentativas de repetição estão limitadas a 10 em 30 segundos. Após a inicialização da v15, também está disponível window.ChattyBox.destroy(). A limpeza não pode anular um pedido já processado pelo servidor.

A integração hospedada widget.js é o caminho sem build quando pretende que o ChattyBox mantenha a interface e o transporte. Se a aplicação precisar de inicializar a mesma interface a partir de código npm, use mountWidget(). Para controlar a interface, use o SDK headless.

Antes de instalar

Conclua primeiro o fluxo de Primeiros passos: configure e importe a fonte, reveja as páginas indexadas e verifique respostas representativas em Testar chatbot.

Em Instalar, prepare uma instalação para o seu site ou faça a gestão de uma chave de navegador em Chaves e domínios. Verifique as definições de origem da chave: uma chave preparada para o domínio de um site pode já estar limitada a essa origem, enquanto as chaves criadas sem restrições funcionam em origens diferentes. Em Editar origens, pode ativar restrições opcionais ou adicionar as origens de produção, pré-visualização, staging e localhost necessárias. Quando ativadas, as restrições exigem uma correspondência exata do esquema, nome do anfitrião e porta: https://example.com, https://preview.example.com e http://localhost:3000 são entradas distintas. Em Instalação no site, introduza um URL de site HTTP(S). O seletor apresenta chaves não expiradas que não têm restrições ou são permitidas para a origem desse URL. Para uma chave restrita, introduza uma origem permitida; consulte as restrições em Gerir chaves e domínios permitidos. Se o formulário não estiver disponível, conclua primeiro o passo de configuração apresentado no dashboard. Selecione uma chave adequada e copie o snippet gerado, que inclui a chave pública e o URL da API do projeto:

<script
  src="https://chattybox.ai/widget.js"
  data-api-key="YOUR_API_KEY"
  data-api-url="YOUR_WIDGET_API_URL"
  async
></script>

Para plataformas voltadas à documentação, consulte os guias de chatbot de IA para MkDocs, chatbot de IA para VitePress e chatbot de IA para GitBook.

Substitua YOUR_API_KEY pela chave pública do widget no painel. Mantenha o valor de data-api-url exatamente como aparece no painel. Em produção, é uma URL estável https://...convex.site/chat para a API pública do widget.

O que deve estar no script

Use atributos de script para valores que precisam estar disponíveis antes que o widget possa iniciar:

Atributo	Obrigatório	Use para
src	Sim	Carregar o JavaScript do widget ChattyBox.
data-api-key	Sim	Identificar a chave pública do widget do projeto.
data-api-url	Sim	Enviar solicitações do widget à API do ChattyBox.
data-locale	Não	Solicitar um idioma da interface na inicialização, apenas quando as substituições do script são permitidas no projeto.
data-chattybox-widget="true"	Não	Permite que loaders dinâmicos e o SDK encontrem um script existente; recomendado ao injetar o script a partir do código da aplicação.
data-debug="true"	Não	Ativar diagnósticos no navegador; desativados por predefinição.
data-color	Não	Substituir a cor de destaque após obter a configuração com sucesso; use uma cor hexadecimal de seis dígitos. Prefira o dashboard.
data-position	Não	Substituir a posição após obter a configuração com sucesso: bottom-right, bottom-left, top-right ou top-left. Prefira o dashboard.

Use as definições do painel para tudo o que deve ser gerido sem voltar a implementar o site:

• Cores, posição, ícone, título e mensagem de boas-vindas do widget.
• Modo de idioma padrão e se substituições por data-locale são permitidas.
• Criação e eliminação de chaves públicas e restrições de origem opcionais por chave. Abra Instalar → Chaves e domínios e escolha Editar origens para ativar uma restrição e adicionar ou remover origens de produção, staging, pré-visualização ou localhost.
• Scraping, novo scraping, chat de teste, Analytics e lacunas de conteúdo.

Se ativar o bloqueio da configuração como código, que é irreversível, as definições compatíveis do assistente, da fonte, do runtime e do widget passam a vir da configuração implementada, não dos formulários do dashboard; as operações manuais de conteúdo também são bloqueadas. As chaves públicas e as origens permitidas continuam a ser definições do projeto, não valores do ficheiro de configuração.

O URL da API pode ser a raiz HTTP da implementação ou terminar em /chat; o loader remove barras finais e um sufixo /chat antes de determinar os endpoints. Não converte um URL Convex .cloud em .site. Não inclua parâmetros de consulta nem fragmentos. O SDK reconhece o atributo de identificação indicado acima, mas não todos os scripts manuais com o mesmo src.

HTML simples

Cole o snippet uma vez perto do final de body, logo antes de </body>. Isso funciona para HTML estático, sites codificados manualmente e templates que expõem um rodapé global.

<!doctype html>
<html lang="en">
  <head>
    <title>Example Site</title>
  </head>
  <body>
    <main>
      <!-- Page content -->
    </main>

    <script
      src="https://chattybox.ai/widget.js"
      data-api-key="YOUR_API_KEY"
      data-api-url="YOUR_WIDGET_API_URL"
      async
    ></script>
  </body>
</html>

Next.js / Shell de aplicação React

Num site Next.js com App Router, adicione o widget a app/layout.tsx usando next/script para que carregue uma vez em toda a aplicação.

import Script from "next/script";
import type { ReactNode } from "react";

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="https://chattybox.ai/widget.js"
          data-api-key="YOUR_API_KEY"
          data-api-url="YOUR_WIDGET_API_URL"
          data-chattybox-widget="true"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

Numa aplicação React de página única, adicione o script uma vez na shell principal da aplicação ou no template HTML. Não o injete em cada componente de rota. O widget alojado flutua sob document.body; não é apresentado dentro do componente que o carrega.

import { useEffect } from "react";

export function ChattyBoxWidget() {
  useEffect(() => {
    if (document.getElementById("chattybox-widget-script")) return;

    const script = document.createElement("script");
    script.id = "chattybox-widget-script";
    script.src = "https://chattybox.ai/widget.js";
    script.async = true;
    script.setAttribute("data-api-key", "YOUR_API_KEY");
    script.setAttribute("data-api-url", "YOUR_WIDGET_API_URL");
    script.setAttribute("data-chattybox-widget", "true");
    document.body.appendChild(script);
  }, []);

  return null;
}

Docusaurus

No Docusaurus, crie ou atualize src/theme/Root.tsx para que o widget fique disponível em todas as páginas de documentação.

import React, { useEffect } from "react";

export default function Root({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    if (document.getElementById("chattybox-widget-script")) return;

    const script = document.createElement("script");
    script.id = "chattybox-widget-script";
    script.src = "https://chattybox.ai/widget.js";
    script.async = true;
    script.setAttribute("data-api-key", "YOUR_API_KEY");
    script.setAttribute("data-api-url", "YOUR_WIDGET_API_URL");
    script.setAttribute("data-chattybox-widget", "true");
    document.body.appendChild(script);
  }, []);

  return <>{children}</>;
}

Se o site Docusaurus tiver rotas traduzidas, defina data-locale antes do carregamento, quando as substituições do script forem permitidas, ou utilize o modo automático com o valor da página em <html lang>. No modo fixo, aplica-se a locale predefinida do projeto, exceto se existir uma substituição autorizada. No código-fonte atual, a widget.js v16 hospedada pode atualizar os rótulos do produto quando <html lang> ou data-locale altera a locale resolvida. Confirme a versão do loader implementada antes de depender de atualizações durante a execução. Este comportamento não pertence ao SDK npm publicado 0.1.4. Os títulos e as mensagens de boas-vindas personalizados, bem como as respostas geradas, não são traduzidos automaticamente.

Mantenha o loader na shell persistente da aplicação durante a navegação normal. O widget não acompanha as alterações às definições do dashboard: reinicialize-o para obter as definições guardadas. Não o recrie a cada mudança de rota do lado do cliente; quando precisar de o desmontar intencionalmente, utilize a API de destruição do widget alojado ou remova todos os handles de mount se tiver usado o SDK.

Interface personalizada

O widget alojado é opcional. Se quiser controlo total sobre a apresentação, o estado das mensagens e o design de interação, use o SDK JavaScript com a mesma chave pública de API e o mesmo URL da API do widget.

CMS genérico/HTML personalizado

A maioria das plataformas CMS tem uma área global de código personalizado, rodapé ou template de tema. Adicione o script ali para que todas as páginas públicas possam carregar o widget.

Use este caminho para Webflow, Framer, Squarespace, áreas de código personalizado do Wix, temas do Shopify, templates do HubSpot e plataformas CMS personalizadas que permitem editar HTML global.

<script
  src="https://chattybox.ai/widget.js"
  data-api-key="YOUR_API_KEY"
  data-api-url="YOUR_WIDGET_API_URL"
  async
></script>

Antes de publicar, confirme que o CMS não remove data-api-key, data-api-url ou async dos scripts personalizados.

Google Tag Manager

Use o Google Tag Manager quando a sua equipa já gere scripts de terceiros pelo GTM.

1. Abra o contentor do GTM.
2. Crie uma nova tag Custom HTML.
3. Cole o snippet do ChattyBox.
4. Use um acionador All Pages ou um acionador mais específico apenas para as páginas que devem apresentar o widget.
5. Pré-visualize o contentor, verifique se o widget carrega e publique.

<script
  src="https://chattybox.ai/widget.js"
  data-api-key="YOUR_API_KEY"
  data-api-url="YOUR_WIDGET_API_URL"
  async
></script>

Se o site usar o modo de consentimento ou uma política de consentimento de tags, certifique-se de que o widget possa carregar nas páginas em que os visitantes precisam de ajuda.

Em SPA, um acionador GTM mais restrito impede o carregamento inicial nas rotas excluídas, mas não remove um widget já carregado noutra rota. Não acione o loader repetidamente quando o histórico mudar.

Content Security Policy

Para o loader alojado predefinido, permita https://chattybox.ai em script-src e a origem da API do widget em connect-src. O widget injeta uma folha de estilos e atributos de estilo inline; atualmente, não disponibiliza uma opção nonce, pelo que uma política que proíba estilos inline bloqueará partes da interface. Se a política o permitir, autorize 'unsafe-inline' para estes estilos ou utilize uma interface personalizada compatível com a política. O carregamento da fonte Inter quando o launcher é aberto também requer https://fonts.googleapis.com em style-src e https://fonts.gstatic.com em font-src. Permita em img-src as origens das imagens dos ícones configurados. Reveja os requisitos de consentimento e segurança antes de flexibilizar a CSP.

Guia do plugin WordPress

Para uma instalação WordPress sem código, use o plugin WordPress do ChattyBox. O plugin é distribuído a partir do GitHub, não do Diretório de Plugins do WordPress.org, pelo que deve transferir o ZIP fixo do plugin WordPress 0.2.0 e utilizar Plugins > Add New > Upload Plugin, em vez de procurar no diretório. Siga o guia do plugin WordPress para o configurar, excluir rotas e verificar. O endpoint de produção da API é configurado automaticamente.

O plugin carrega o widget alojado em pedidos públicos do frontend sem editar o tema. Intencionalmente, não é carregado em wp-admin, feeds, pedidos REST ou pedidos AJAX.

Isto não é um controlo de privacidade ou de acesso para todas as páginas do frontend. Quando necessário, implemente e teste exclusões para páginas de checkout, conta, protegidas por palavra-passe ou reservadas a membros através do filtro do plugin, ou utilize uma instalação manual com o âmbito adequado. A definição do URL do loader no plugin não altera o endpoint de produção da API integrado; utilize o snippet manual para outra implementação da API.

Se preferir uma instalação manual por script, use uma das localizações de scripts que a sua configuração WordPress já suporta:

• Configurações do tema que fornecem scripts de cabeçalho ou rodapé.
• Um tema filho que controla o template do rodapé.
• Um plugin de scripts de cabeçalho/rodapé.
• Google Tag Manager, se o site WordPress já o utiliza.

Cole o snippet numa localização global do rodapé para que apareça nas páginas, publicações, documentos e artigos da base de conhecimento publicados onde o chatbot deve estar disponível.

<script
  src="https://chattybox.ai/widget.js"
  data-api-key="YOUR_API_KEY"
  data-api-url="YOUR_WIDGET_API_URL"
  async
></script>

Evite adicionar o widget a páginas wp-admin, checkout, conta ou associação privada, a menos que sejam intencionalmente públicas e compatíveis.

Módulo Drupal

Para Drupal 10 ou 11, o Composer é o caminho de instalação recomendado. Como o módulo ainda não está listado no Drupal.org nem no Packagist, o Composer precisa do repositório VCS público do GitHub. Adicione-o ao composer.json raiz do projeto Drupal que o utiliza:

{
  "repositories": {
    "chattybox-drupal": {
      "type": "vcs",
      "url": "https://github.com/OpenStaticFish/chattybox-drupal.git"
    }
  }
}

Depois, instale o módulo marcado e ative-o:

composer require openstaticfish/chattybox-drupal:^0.1
drush en chattybox

Abra Configuration > Web services > ChattyBox, cole a chave pública da API do widget do snippet em Instalar → Instalação no site e ative o chatbot. A versão do módulo auditada localmente usa um endpoint da API codificado no módulo. Compare-o com o snippet e utilize a integração manual para uma implementação diferente da API. Consulte o guia do módulo de chatbot Drupal para exclusões de rotas, cache e consentimento.

O módulo começa desativado e ignora pedidos administrativos e pedidos que não sejam HTML, mas não todo o conteúdo privado do frontend. Alterar o URL do script não altera o endpoint de produção da API integrado. Utilize um snippet manual do widget se precisar de outra implementação da API.

Verificação

Depois de instalar, execute a checklist de lançamento antes de anunciar o chatbot:

• Abra uma página pública numa janela anónima.
• Confirme que o launcher do widget aparece.
• Abra o widget e faça uma pergunta real de cliente.
• Verifique se uma resposta suportada inclui citações relevantes das fontes e, em seguida, faça uma pergunta sem suporte no conteúdo para testar a resposta alternativa (que pode não ter fontes).
• Verifique a consola do navegador para detetar a falta de data-api-key ou data-api-url, ou erros de chave ou origem. Verifique se a chave tem restrições de origem ativas e, nesse caso, se a origem pretendida é permitida.