Installation Guides

Install ChattyBox by loading one public widget script on the pages where visitors should be able to ask questions.

Start from the snippet in your ChattyBox dashboard. It includes the public widget API key and API URL for your project:

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

Replace YOUR_API_KEY with the public widget key from your dashboard. If your dashboard shows a different data-api-url, keep the dashboard value exactly.

What Belongs in the Script

Use script attributes for values that must be available before the widget can start:

Attribute	Required	Use it for
`src`	Yes	Loading the ChattyBox widget JavaScript.
`data-api-key`	Yes	Identifying the public widget key for your project.
`data-api-url`	Yes	Sending widget requests to the ChattyBox API.
`data-locale`	No	Forcing the widget UI language on a specific page.

Use dashboard settings for everything that should be managed without redeploying your site:

Widget colors, position, icon, title, and welcome message.
Default language mode and whether data-locale overrides are allowed.
Public key creation, deletion, and any allowed-origin restrictions configured for your project.
Scraping, re-scraping, test chat, analytics, and content gaps.

Plain HTML

Paste the snippet once near the end of body, just before </body>. This works for static HTML, hand-coded sites, and templates that expose a global footer.

<!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="https://app.chattybox.ai"
      async
    ></script>
  </body>
</html>

Next.js / React App Shell

For a Next.js App Router site, add the widget to app/layout.tsx with next/script so it loads once for the whole app.

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="https://app.chattybox.ai"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

For a React single-page app, add the script once in your top-level app shell or HTML template. Do not inject it from every route component.

import { useEffect } from "react";

export function ChattyBoxWidget() {
  useEffect(() => {
    if (document.querySelector("script[data-chattybox-widget]")) return;

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

    return () => script.remove();
  }, []);

  return null;
}

Docusaurus

For Docusaurus, create or update src/theme/Root.tsx so the widget is available across docs pages.

import React, { useEffect } from "react";

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

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

    return () => script.remove();
  }, []);

  return <>{children}</>;
}

If your Docusaurus site has translated routes, set data-locale from the current page language or rely on the page's <html lang> value.

Generic CMS/Custom HTML

Most CMS platforms have a global custom code, footer, or theme template area. Add the script there so every public page can load the widget.

Use this path for Webflow, Framer, Squarespace, Wix custom code areas, Shopify themes, HubSpot templates, and custom CMS platforms that let you edit global HTML.

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

Before publishing, confirm the CMS does not strip data-api-key, data-api-url, or async from custom scripts.

Google Tag Manager

Use Google Tag Manager when your team already manages third-party scripts through GTM.

Open your GTM container.
Create a new Custom HTML tag.
Paste the ChattyBox snippet.
Use an All Pages trigger, or a narrower trigger for only the pages that should show the widget.
Preview the container, verify the widget loads, then publish.

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

If your site uses consent mode or a tag consent policy, ensure the widget is allowed to load on the pages where visitors need help.

WordPress

ChattyBox does not require a WordPress plugin. Use one of the script locations your WordPress setup already supports:

Theme settings that provide header or footer scripts.
A child theme that controls the footer template.
A header/footer script plugin.
Google Tag Manager if your WordPress site already uses it.

Paste the snippet in a global footer location so it appears on published pages, posts, docs, and knowledge base articles where the chatbot should be available.

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

Avoid adding the widget to wp-admin, checkout, account, or private membership pages unless those pages are intentionally public and supported.

Verification

After installing, run the launch checklist before announcing the chatbot:

Open a public page in an incognito window.
Confirm the widget launcher appears.
Open the widget and ask a real customer question.
Verify the answer includes source citations.
Check the browser console for missing data-api-key, missing data-api-url, or key/origin errors.

What Belongs in the Script​

Plain HTML​

Next.js / React App Shell​

Docusaurus​

Generic CMS/Custom HTML​

Google Tag Manager​

WordPress​

Verification​