Developer Documentation

Quick Start

After creating a chatbot on SiteBot, you receive a unique namespace. Add one script tag to your HTML and the widget loads automatically.

<script
  src="https://sitebot.online/embed.js"
  data-namespace="YOUR_NAMESPACE"
></script>

Dynamic Mode

In dynamic mode, the only value you set in the embed snippet is data-namespace. Every other config value (title, colors, icon, shape, welcome message) is fetched from the server at load time. Changes you make in the SiteBot dashboard are reflected instantly — no redeploy needed.

How it works

1. embed.js reads the script tag and builds an "explicit" map — any attribute present on the tag is marked as explicitly set.
2. embed.js fetches config from the server: GET /api/chatbot/config?namespace=YOUR_NAMESPACE.
3. For every config key: if the key is NOT in the explicit map, the server value is used. If it IS explicit, the server value is ignored.
4. Since only data-namespace is on the tag, all other keys come from the server.

Step by step

1. Copy your namespace from the SiteBot dashboard (Create Chatbot page).
2. Add the script tag to your HTML, setting only data-namespace.
3. Deploy. The widget loads with your server-configured title, colors, icon, shape, and welcome message.
4. To change any config: edit it in the dashboard. The next page load picks it up — no code changes.

<script
  src="https://sitebot.online/embed.js"
  data-namespace="YOUR_NAMESPACE"
></script>

Static Mode

In static mode, you add data-* attributes directly to the script tag. These values are locked — the server fetch still happens, but any key that is already present on the tag is never overwritten.

Step by step

1. Copy your namespace from the SiteBot dashboard.
2. Add the script tag with data-namespace plus any other attributes you want to lock.
3. Each attribute you add becomes "explicit" — it will always use your value, regardless of dashboard changes.
4. Attributes you omit still come from the server (dynamic fallback).

<script
  src="https://sitebot.online/embed.js"
  data-namespace="YOUR_NAMESPACE"
  data-title="Support Assistant"
  data-welcome="Hi! How can I help you today?"
  data-position="right"
  data-shape="circle"
  data-primary-color="#fa5d19"
  data-header-bg="#1e293b"
  data-bot-bg="#f3f4f6"
  data-user-bg="#fa5d19"
></script>

Mixed mode

You can mix both approaches. Set only the attributes you want to lock; the rest come from the server. For example, lock the title and primary color but let the dashboard control everything else:

<script
  src="https://sitebot.online/embed.js"
  data-namespace="YOUR_NAMESPACE"
  data-title="Always This Title"
  data-primary-color="#fa5d19"
></script>

React Integration

In React, use a useEffect hook to create the script element dynamically. This avoids next/script quirks with data-* attributes.

Dynamic mode

Only set dataset.namespace. All other config comes from the server.

'use client';

import { useEffect } from "react";

export function ChatWidget() {
  useEffect(() => {
    const s = document.createElement("script");
    s.src = "https://sitebot.online/embed.js";
    s.dataset.namespace = "YOUR_NAMESPACE";
    document.body.appendChild(s);
  }, []);

  return null;
}

Static mode

Set any dataset.* property to lock that value. Use camelCase: data-header-bg becomes dataset.headerBg.

'use client';

import { useEffect } from "react";

export function ChatWidget() {
  useEffect(() => {
    const s = document.createElement("script");
    s.src = "https://sitebot.online/embed.js";
    s.dataset.namespace = "YOUR_NAMESPACE";
    s.dataset.title = "Support";
    s.dataset.position = "right";
    s.dataset.shape = "circle";
    s.dataset.primaryColor = "#fa5d19";
    s.dataset.headerBg = "#1e293b";
    document.body.appendChild(s);
  }, []);

  return null;
}

Use in your app: <ChatWidget /> in any page or layout.

Vite Integration

In a Vite project (Vue, React, or vanilla JS), you have two options: add the script tag directly to index.html, or load it dynamically from a component.

Option 1: index.html (simplest)

Vite injects index.html as the entry point. Add the script tag there — same as the plain HTML approach above.

<!-- dynamic mode: only namespace -->
<script
  src="https://sitebot.online/embed.js"
  data-namespace="YOUR_NAMESPACE"
></script>

Option 2: Dynamic from a component

If you need the widget to load conditionally or with runtime values, create the script element in a component:

// React
import { useEffect } from "react";

export function ChatWidget({ namespace }: { namespace: string }) {
  useEffect(() => {
    const s = document.createElement("script");
    s.src = "https://sitebot.online/embed.js";
    s.dataset.namespace = namespace;
    document.body.appendChild(s);
  }, [namespace]);

  return null;
}

// Vue — same idea in onMounted():
// const s = document.createElement("script");
// s.src = "https://sitebot.online/embed.js";
// s.dataset.namespace = props.namespace;
// document.body.appendChild(s);

For static mode, add s.dataset.title = "..." etc. before appending.

Next.js Integration

In Next.js, use a client component with useEffect. Do not use next/script — it does not reliably set data-* attributes on the DOM element.

Step by step

1. Create a client component: add "use client" at the top.
2. In useEffect, create a script element with document.createElement("script").
3. Set s.src and s.dataset.namespace (dynamic) or additional dataset.* (static).
4. Append to document.body.
5. Render the component in your root layout or any page.

Dynamic mode

"use client";

import { useEffect } from "react";

export function ChatWidget() {
  useEffect(() => {
    const s = document.createElement("script");
    s.src = "https://sitebot.online/embed.js";
    s.dataset.namespace = "YOUR_NAMESPACE";
    document.body.appendChild(s);
  }, []);

  return null;
}

Add to your root layout:

import { ChatWidget } from "@/components/ChatWidget";

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <ChatWidget />
      </body>
    </html>
  );
}

Static mode

'use client';

import { useEffect } from "react";

export function ChatWidget() {
  useEffect(() => {
    const s = document.createElement("script");
    s.src = "https://sitebot.online/embed.js";
    s.dataset.namespace = "YOUR_NAMESPACE";
    s.dataset.title = "Support";
    s.dataset.position = "right";
    s.dataset.shape = "circle";
    s.dataset.primaryColor = "#fa5d19";
    s.dataset.headerBg = "#1e293b";
    document.body.appendChild(s);
  }, []);

  return null;
}

Widget Options

All options are set as data- attributes on the script tag. In React/Vue/Next.js, use dataset.* (camelCase). The attribute name maps by removing data- and converting kebab-case to camelCase.

General

Lead Capture

Layout & Typography

Header

Messages

Input

Bubble & Welcome Screen

Theme Colors

All colors accept any valid CSS color value. Use the attribute names from the tables above. In dataset.* (React/Vue/Next.js), use camelCase — e.g. data-primary-color becomes dataset.primaryColor.

JavaScript SDK

For runtime control, use the globally injected window.SiteBot object. This is useful for single-page applications that need to update config without reloading.

window.SiteBot.configure({
  title: "Sales Assistant",
  welcome: "Interested in our enterprise plans?",
  primaryColor: "#fa5d19",
  shape: "circle",
  position: "right",
});

window.SiteBotConfig can also be set before the embed script loads to inject config at page load time.

<script>
  window.SiteBotConfig = {
    title: "Locked Title",
    primaryColor: "#fa5d19",
  };
</script>
<script
  src="https://sitebot.online/embed.js"
  data-namespace="YOUR_NAMESPACE"
></script>