Guias de instalação

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 e restrinja suas origens permitidas. Volte a Embed, selecione a chave, conclua a personalização do widget hospedado e copie o snippet gerado. Ele inclui a chave pública e a 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 exclusão de chaves públicas e quaisquer restrições de origem permitida configuradas para o projeto.
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.

WordPress

O ChattyBox não exige um plugin do WordPress. Use um dos locais de script já compatíveis com sua configuração do WordPress:

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 em um local global do rodapé para que ele apareça em páginas, posts, 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.

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.

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​

WordPress​

Verificação​

Privacy choices