Documentation — SiteBot Integration Guide

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.

Two modes

Dynamic — only data-namespace in the tag. Config is fetched from the server. Dashboard changes take effect instantly. Best for SPAs and frameworks (React, Next.js, Vite, Vue).
Static — add any data-* attribute to the tag. Those values are locked and never overwritten by the server. Best for static HTML sites, WordPress, and hardcoded pages where you control the embed snippet directly.

Select Your Framework

components/ChatWidget.tsx

'use client';

import { useEffect } from "react";

export function ChatWidget() {
  useEffect(() => {
    const s = document.createElement("script");
    s.src = process.env.NEXT_PUBLIC_SITEBOT_SCRIPT_URL || "https://cdn.sitebot.online/embed.js";
    s.dataset.namespace = process.env.NEXT_PUBLIC_SITEBOT_NAMESPACE || "your-namespace";
    document.body.appendChild(s);
  }, []);

  return null;
}

.env file:

.env

NEXT_PUBLIC_SITEBOT_SCRIPT_URL=https://cdn.sitebot.online/embed.js
NEXT_PUBLIC_SITEBOT_NAMESPACE=your-namespace

Environment Variables

For production applications, use environment variables to configure the embed script URL and namespace. This keeps secrets out of your source code and allows per-environment configuration.

Framework Selector

.env Configuration

.env

NEXT_PUBLIC_SITEBOT_SCRIPT_URL=https://cdn.sitebot.online/embed.js
NEXT_PUBLIC_SITEBOT_NAMESPACE=your-namespace

Installation

components/ChatWidget.tsx

'use client';

import { useEffect } from "react";

export function ChatWidget() {
  useEffect(() => {
    const s = document.createElement("script");
    s.src = process.env.NEXT_PUBLIC_SITEBOT_SCRIPT_URL || "https://cdn.sitebot.online/embed.js";
    s.dataset.namespace = process.env.NEXT_PUBLIC_SITEBOT_NAMESPACE || "your-namespace";
    document.body.appendChild(s);
  }, []);

  return null;
}

Best Practice: Always provide fallback values (as shown above) to handle cases where environment variables are not available.

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

embed.js reads the script tag and builds an "explicit" map — any attribute present on the tag is marked as explicitly set.
embed.js fetches config from the server: GET /api/chatbot/config?namespace=YOUR_NAMESPACE.
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.
Since only data-namespace is on the tag, all other keys come from the server.

Step by step

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

index.html — dynamic mode

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

Key rule: If you add data-title="Support" to the tag, the dashboard title is ignored for that attribute. Only data-namespace should be present for full dynamic behavior.

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

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

index.html — static mode

<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:

index.html — mixed mode

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

Framework Integration

Choose your framework below to see environment-variable based installation. All examples support dynamic mode — configure the namespace and script URL via environment variables.

Select Framework

Installation Code

components/ChatWidget.tsx

'use client';

import { useEffect } from "react";

export function ChatWidget() {
  useEffect(() => {
    const s = document.createElement("script");
    s.src = process.env.NEXT_PUBLIC_SITEBOT_SCRIPT_URL || "https://cdn.sitebot.online/embed.js";
    s.dataset.namespace = process.env.NEXT_PUBLIC_SITEBOT_NAMESPACE || "your-namespace";
    document.body.appendChild(s);
  }, []);

  return null;
}

.env File

.env

NEXT_PUBLIC_SITEBOT_SCRIPT_URL=https://cdn.sitebot.online/embed.js
NEXT_PUBLIC_SITEBOT_NAMESPACE=your-namespace

Next.js Note: Use process.env to access environment variables. Do not use next/script — it doesn't reliably set data-* attributes.

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

Attribute	Default	Description
data-namespace	—	Your chatbot namespace (required)(required)
data-title	Chat Assistant	Header title
data-welcome	Hi there! Ask me anything.	Welcome message
data-position	right	left or right
data-shape	circle	circle or square
data-placeholder	Type your message...	Input placeholder text
data-icon	—	Custom icon image URL for the bubble
data-theme	auto	auto, light, or dark
data-quick-prompts	—	Newline-separated list of quick prompt suggestions
data-quick-prompt-bg-color	—	Quick prompt button background color
data-quick-prompt-text-color	—	Quick prompt button text color
data-quick-prompt-border-color	—	Quick prompt button border color
data-escalation	false	Enable human escalation toggle
data-api-url	(auto-derived)	API base URL (auto-derived from script src)
data-width	380	Panel width in px
data-height	500	Panel height in px
data-bubble-size	60	Bubble diameter in px
data-offset-bottom	24	Bubble distance from bottom in px
data-offset-side	24	Bubble distance from side in px

Lead Capture

Attribute	Default	Description
data-lead-title	Please enter your details	Title for the lead capture form
data-lead-name-label	Name	Label for the name field
data-lead-email-label	Email	Label for the email field
data-lead-phone-label	Phone	Label for the phone field
data-lead-submit-label	Submit	Label for the submit button
data-lead-success-msg	Thank you!	Success message after submission

Layout & Typography

Attribute	Default	Description
data-border-radius	auto	Panel border radius
data-panel-border-color	—	Panel border color
data-msg-gap	—	Gap between messages
data-msg-font-size	—	Message font size
data-msg-max-width	—	Max width of message bubbles
data-font-family	—	Custom font family
data-custom-css	—	Custom CSS injected into the widget

Header

Attribute	Description
data-header-bg	Header background
data-header-title-color	Header title text color
data-header-status-color	Online status text color
data-header-avatar-bg	Avatar circle background
data-online-text	Online status text
data-online-dot-color	Online indicator dot color
data-close-btn-color	Close button color

Messages

Attribute	Description
data-bot-bg	Bot message background
data-bot-color	Bot message text
data-user-bg	User message background
data-user-color	User message text
data-bg	Chat area background
data-text	General text color
data-text-secondary	Secondary text color
data-typing-bg	Typing indicator background
data-typing-dot-color	Typing indicator dot color

Input

Attribute	Description
data-input-bg	Input field background
data-input-text-color	Input text color
data-input-border-color	Input border color
data-input-placeholder-color	Placeholder text color
data-send-bg	Send button background

Bubble & Welcome Screen

Attribute	Description
data-primary-color	Primary brand color (buttons, accents, bubble default)
data-bubble-color	Bubble icon color
data-welcome-icon-bg	Welcome screen icon background
data-welcome-title-color	Welcome screen title color
data-welcome-text-color	Welcome screen body text color

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.

data-primary-color

Primary brand color

CSS: --fs-primary

data-header-bg

Header background

CSS: --fs-header-bg

data-bot-bg

Bot message background

CSS: --fs-bot-bg

data-user-bg

User message background

CSS: --fs-user-bg

data-input-bg

Input field background

CSS: --fs-input-bg

data-send-bg

Send button background

CSS: --fs-send-bg

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.

app.js

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.

index.html — pre-load config

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

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.

Two modes

Dynamic — only data-namespace in the tag. Config is fetched from the server. Dashboard changes take effect instantly. Best for SPAs and frameworks (React, Next.js, Vite, Vue).
Static — add any data-* attribute to the tag. Those values are locked and never overwritten by the server. Best for static HTML sites, WordPress, and hardcoded pages where you control the embed snippet directly.

Select Your Framework

components/ChatWidget.tsx

'use client';

import { useEffect } from "react";

export function ChatWidget() {
  useEffect(() => {
    const s = document.createElement("script");
    s.src = process.env.NEXT_PUBLIC_SITEBOT_SCRIPT_URL || "https://cdn.sitebot.online/embed.js";
    s.dataset.namespace = process.env.NEXT_PUBLIC_SITEBOT_NAMESPACE || "your-namespace";
    document.body.appendChild(s);
  }, []);

  return null;
}

.env file:

.env

NEXT_PUBLIC_SITEBOT_SCRIPT_URL=https://cdn.sitebot.online/embed.js
NEXT_PUBLIC_SITEBOT_NAMESPACE=your-namespace

Environment Variables

For production applications, use environment variables to configure the embed script URL and namespace. This keeps secrets out of your source code and allows per-environment configuration.

Framework Selector

.env Configuration

.env

NEXT_PUBLIC_SITEBOT_SCRIPT_URL=https://cdn.sitebot.online/embed.js
NEXT_PUBLIC_SITEBOT_NAMESPACE=your-namespace

Installation

components/ChatWidget.tsx

'use client';

import { useEffect } from "react";

export function ChatWidget() {
  useEffect(() => {
    const s = document.createElement("script");
    s.src = process.env.NEXT_PUBLIC_SITEBOT_SCRIPT_URL || "https://cdn.sitebot.online/embed.js";
    s.dataset.namespace = process.env.NEXT_PUBLIC_SITEBOT_NAMESPACE || "your-namespace";
    document.body.appendChild(s);
  }, []);

  return null;
}

Best Practice: Always provide fallback values (as shown above) to handle cases where environment variables are not available.

Dynamic Mode

How it works

embed.js reads the script tag and builds an "explicit" map — any attribute present on the tag is marked as explicitly set.
embed.js fetches config from the server: GET /api/chatbot/config?namespace=YOUR_NAMESPACE.
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.
Since only data-namespace is on the tag, all other keys come from the server.

Step by step

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

index.html — dynamic mode

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

Key rule: If you add data-title="Support" to the tag, the dashboard title is ignored for that attribute. Only data-namespace should be present for full dynamic behavior.

Static Mode

Step by step

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

index.html — static mode

<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:

index.html — mixed mode

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

Framework Integration

Choose your framework below to see environment-variable based installation. All examples support dynamic mode — configure the namespace and script URL via environment variables.

Select Framework

Installation Code

components/ChatWidget.tsx

'use client';

import { useEffect } from "react";

export function ChatWidget() {
  useEffect(() => {
    const s = document.createElement("script");
    s.src = process.env.NEXT_PUBLIC_SITEBOT_SCRIPT_URL || "https://cdn.sitebot.online/embed.js";
    s.dataset.namespace = process.env.NEXT_PUBLIC_SITEBOT_NAMESPACE || "your-namespace";
    document.body.appendChild(s);
  }, []);

  return null;
}

.env File

.env

NEXT_PUBLIC_SITEBOT_SCRIPT_URL=https://cdn.sitebot.online/embed.js
NEXT_PUBLIC_SITEBOT_NAMESPACE=your-namespace

Next.js Note: Use process.env to access environment variables. Do not use next/script — it doesn't reliably set data-* attributes.

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

Attribute	Default	Description
data-namespace	—	Your chatbot namespace (required)(required)
data-title	Chat Assistant	Header title
data-welcome	Hi there! Ask me anything.	Welcome message
data-position	right	left or right
data-shape	circle	circle or square
data-placeholder	Type your message...	Input placeholder text
data-icon	—	Custom icon image URL for the bubble
data-theme	auto	auto, light, or dark
data-quick-prompts	—	Newline-separated list of quick prompt suggestions
data-quick-prompt-bg-color	—	Quick prompt button background color
data-quick-prompt-text-color	—	Quick prompt button text color
data-quick-prompt-border-color	—	Quick prompt button border color
data-escalation	false	Enable human escalation toggle
data-api-url	(auto-derived)	API base URL (auto-derived from script src)
data-width	380	Panel width in px
data-height	500	Panel height in px
data-bubble-size	60	Bubble diameter in px
data-offset-bottom	24	Bubble distance from bottom in px
data-offset-side	24	Bubble distance from side in px

Lead Capture

Attribute	Default	Description
data-lead-title	Please enter your details	Title for the lead capture form
data-lead-name-label	Name	Label for the name field
data-lead-email-label	Email	Label for the email field
data-lead-phone-label	Phone	Label for the phone field
data-lead-submit-label	Submit	Label for the submit button
data-lead-success-msg	Thank you!	Success message after submission

Layout & Typography

Attribute	Default	Description
data-border-radius	auto	Panel border radius
data-panel-border-color	—	Panel border color
data-msg-gap	—	Gap between messages
data-msg-font-size	—	Message font size
data-msg-max-width	—	Max width of message bubbles
data-font-family	—	Custom font family
data-custom-css	—	Custom CSS injected into the widget

Header

Attribute	Description
data-header-bg	Header background
data-header-title-color	Header title text color
data-header-status-color	Online status text color
data-header-avatar-bg	Avatar circle background
data-online-text	Online status text
data-online-dot-color	Online indicator dot color
data-close-btn-color	Close button color

Messages

Attribute	Description
data-bot-bg	Bot message background
data-bot-color	Bot message text
data-user-bg	User message background
data-user-color	User message text
data-bg	Chat area background
data-text	General text color
data-text-secondary	Secondary text color
data-typing-bg	Typing indicator background
data-typing-dot-color	Typing indicator dot color

Input

Attribute	Description
data-input-bg	Input field background
data-input-text-color	Input text color
data-input-border-color	Input border color
data-input-placeholder-color	Placeholder text color
data-send-bg	Send button background

Bubble & Welcome Screen

Attribute	Description
data-primary-color	Primary brand color (buttons, accents, bubble default)
data-bubble-color	Bubble icon color
data-welcome-icon-bg	Welcome screen icon background
data-welcome-title-color	Welcome screen title color
data-welcome-text-color	Welcome screen body text color

Theme Colors

data-primary-color

Primary brand color

CSS: --fs-primary

data-header-bg

Header background

CSS: --fs-header-bg

data-bot-bg

Bot message background

CSS: --fs-bot-bg

data-user-bg

User message background

CSS: --fs-user-bg

data-input-bg

Input field background

CSS: --fs-input-bg

data-send-bg

Send button background

CSS: --fs-send-bg

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.

app.js

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.

index.html — pre-load config

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

Developer Documentation

On this page

Quick Start

Two modes

Select Your Framework

.env file:

Environment Variables

Framework Selector

.env Configuration

Installation

Dynamic Mode

How it works

Step by step

Static Mode

Step by step

Mixed mode

Framework Integration

Select Framework

Installation Code

.env File

Widget Options

General

Lead Capture

Layout & Typography

Header

Messages

Input

Bubble & Welcome Screen

Theme Colors

JavaScript SDK

Developer Documentation

On this page

Quick Start

Two modes

Select Your Framework

.env file:

Environment Variables

Framework Selector

.env Configuration

Installation

Dynamic Mode

How it works

Step by step

Static Mode

Step by step

Mixed mode

Framework Integration

Select Framework

Installation Code

.env File

Widget Options

General

Lead Capture

Layout & Typography

Header

Messages

Input

Bubble & Welcome Screen

Theme Colors

JavaScript SDK