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 um único loader numa shell persistente. No SDK publicado 0.1.4, mounts idênticos partilham o script; remove() é idempotente e só o último handle sinaliza a widget.js v15 para remover UI, estilos, links de fontes, script e API global e cancelar o trabalho pendente. Opções diferentes são recusadas enquanto houver handles. data-locale só solicita idioma na inicialização quando overrides de script são permitidos; fixed/auto determinam a restante política.

A integração hospedada widget.js é o caminho sem build quando você quer que o ChattyBox mantenha a interface e o transporte. Se o aplicativo deve 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 faça scraping da fonte, revise as páginas indexadas e verifique respostas representativas no Test Chat.

Depois, crie uma chave segura para o navegador em Public Keys. Por predefinição, funciona em origens de produção, preview/staging e localhost. Para um reforço opcional de segurança, escolha Edit origins, ative Restrict this key to specific origins e adicione as origens permitidas exatas. Quando ativada, a correspondência inclui esquema, nome do anfitrião e porta: https://example.com, https://preview.example.com e http://localhost:3000 são entradas separadas. Volte ao Embed, selecione a chave, conclua a personalização do widget hospedado e copie o snippet gerado. Ele inclui a chave pública e o URL da API do seu 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	Forçar o idioma da interface do widget em uma página específica.

Use as configurações do painel para tudo o que deve ser gerenciado sem reimplantar 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 Public Keys > Edit origins 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 você ativar o bloqueio de configuração como código, o assistente, a fonte, o runtime e as configurações compatíveis do widget virão da configuração implantada, e não dos formulários do painel. Chaves públicas e origens permitidas continuam sendo credenciais de configuração do projeto, não valores do arquivo de configuração.

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 aplicativo React

Em um site Next.js com App Router, adicione o widget a app/layout.tsx usando next/script para que ele carregue uma vez em todo o aplicativo.

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"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

Em um aplicativo React de página única, adicione o script uma vez na shell de aplicativo de nível superior ou no template HTML. Não o injete em cada componente de rota.

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 com base no idioma da página atual ou use o valor de <html lang> da página.

Mantenha o loader na shell persistente do aplicativo. Não o recrie nem o remova durante mudanças normais de rota no cliente.

Interface personalizada

O widget hospedado é opcional. Se quiser controle total sobre renderização, estado das mensagens e design de interação, use o SDK JavaScript com a mesma chave pública de API e a mesma 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 sua equipe já gerencia scripts de terceiros pelo GTM.

Abra o contêiner do GTM.
Crie uma nova tag Custom HTML.
Cole o snippet do ChattyBox.
Use um acionador All Pages ou um acionador mais específico apenas para as páginas que devem exibir o widget.
Visualize o contêiner, 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.

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 hospedado em pedidos públicos do frontend sem editar o tema. Intencionalmente, não é carregado em wp-admin, feeds, pedidos REST ou pedidos AJAX.

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 de API pública do widget da aba Embed do projeto e ative o chatbot. O endpoint de produção é configurado automaticamente. Consulte o guia do módulo de chatbot Drupal para exclusões de rotas e a alternativa manual.

Verificação

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

Abra uma página pública em uma janela anônima.
Confirme que o launcher do widget aparece.
Abra o widget e faça uma pergunta real de cliente.
Verifique se a resposta inclui citações de fontes.
Verifique o console do navegador em busca de data-api-key ausente, data-api-url ausente ou erros de chave/origem. Verifique as origens apenas se tiver ativado explicitamente uma restrição para a chave.

Antes de instalar​

O que deve estar no script​

HTML simples​

Next.js / Shell de aplicativo React​

Docusaurus​

Interface personalizada​

CMS genérico/HTML personalizado​

Google Tag Manager​

Guia do plugin WordPress​

Módulo Drupal​

Verificação​

Preferências de privacidade