Website Widget (Live Chat SDK)
View as Markdown
The **Website** channel (`/{slug}/channels/website`) lets you create and embed one or more live chat widgets (**Live Chat SDK**) on your websites, connect them to AI Bots, and handle visitor conversations inside your workspace.
:::note[Required permissions]
- **View widgets**: **`nick:read:all`** (navigation item is visible with `nick:read:all`, `nick:connect`, or `nick:operate`).
- **Create widget / Upload widget avatar**: **`nick:connect`**.
- **Update configuration / Pause-Resume / Rotate HMAC Secret**: **`nick:operate`**.
- **Delete widget**: **`nick:delete`**.
:::
## Create a New Website Widget
1. Go to **Channels → Website** (`/{slug}/channels/website`) and click **Add Channel** (opens `/{slug}/channels/website/new`).
2. Enter the channel name (up to 100 characters), configure the initial appearance, and pick an AI Bot.
3. Save to create the widget. OmnyBot generates a unique **`siteKey`** and **`hmacSecret`** and redirects you to the widget workspace (`/{slug}/channels/website/{widgetId}`).
## Four Configuration Tabs
### 1. Widget (Appearance & Content)
Customize the widget alongside an **Interactive Live Preview**:
- **Theme & Layout**: Primary color (hex), color mode (`light`, `dark`, `system`), font family (`System`, `Inter`, `Roboto`, `Be Vietnam Pro`, `Plus Jakarta Sans`, `Nunito`, `Montserrat`, `Open Sans`), border radius (`sharp`, `rounded`, `pill`), and window size (`compact` 350×480, `default` 390×560, `large` 430×640).
- **Placement & Behavior**: Corner position (`bottom-right` or `bottom-left`), X/Y offsets (`0–200px`), launcher button size (`36–96px`), and optional auto-open delay (`1–300` seconds).
- **Messaging Content**: Header title (up to 80 chars), status subtitle (up to 120 chars), avatar upload (max **2 MB**), welcome message (up to 500 chars), input placeholder (up to 80 chars), and up to **4 Quick Replies** (max 60 chars each).
- **Pre-chat Form**: Optionally require visitors to submit **Name** and **Phone** (plus optional **Email**) before starting a chat.
### 2. Conversations
- Switch the widget status between **`CONNECTED`** (active) and **`PAUSED`**.
- Assign an **AI Bot** and toggle AI auto-reply on or off for this widget.
### 3. Install
Embed the SDK script tag right before the closing `</body>` tag on your site:
```html
<script
src="https://<your-omnybot-domain>/sdk/v1/widget.iife.js"
data-site-key="<SITE_KEY>"
async
></script>
```
The Install tab provides ready-to-copy snippets for 7 platforms: **HTML Snippet**, **React / Next.js**, **Angular**, **Vue**, **WordPress**, **Google Tag Manager (GTM)**, and **Shopify**, in two modes:
- **Anonymous visitors**: Basic `<script>` embed only.
- **Logged-in users**: Calls `window.OmnyBot("identify", { externalId, name, phone, email, hmac })` to sync authenticated customer identity from your app.
### 4. Security
- **Allowed Domains (`allowedDomains`)**: Whitelist up to **20 domains** (supports wildcards such as `*.example.com`). Leave empty to allow any valid `http/https` origin.
- **Allow `localhost`**: Enable to test the widget on local development origins (`localhost`, `127.0.0.1`, `[::1]`).
- **Require HMAC (`requireHmac`)**: When enabled, all `identify()` calls must include a server-generated HMAC signature computed with your **`hmacSecret`**.
- **Rotate Secret**: Generates a new `hmacSecret` and immediately invalidates active visitor JWT sessions.
:::caution[Deleting a widget]
Deleting a widget (`nick:delete`) removes the Website channel and its associated conversations. If you only want to hide chat temporarily, set the widget status to **`PAUSED`** instead.
:::
## Public SDK Limits
To prevent abuse and keep widgets responsive, the Public SDK enforces these defaults:
- **Visitor messages**: Up to **2,000 characters** and up to **5 attachments** per message.
- **Visitor file uploads (images / PDF)**: Max **5 MB** per file.
- **Rate Limits**:
- Session initialization: **15 requests / 5 minutes** per IP.
- Sending messages: **25 requests / minute** per IP and **10 requests / minute** per visitor.
- File uploads: **10 requests / minute** per IP and **3 requests / minute** per visitor.
## Related Guides
- [Channels Overview](/channels/overview/)
The Website channel (/{slug}/channels/website) lets you create and embed one or more live chat widgets (Live Chat SDK) on your websites, connect them to AI Bots, and handle visitor conversations inside your workspace.
Create a New Website Widget
Section titled “Create a New Website Widget”- Go to Channels → Website (
/{slug}/channels/website) and click Add Channel (opens/{slug}/channels/website/new). - Enter the channel name (up to 100 characters), configure the initial appearance, and pick an AI Bot.
- Save to create the widget. OmnyBot generates a unique
siteKeyandhmacSecretand redirects you to the widget workspace (/{slug}/channels/website/{widgetId}).
Four Configuration Tabs
Section titled “Four Configuration Tabs”1. Widget (Appearance & Content)
Section titled “1. Widget (Appearance & Content)”Customize the widget alongside an Interactive Live Preview:
- Theme & Layout: Primary color (hex), color mode (
light,dark,system), font family (System,Inter,Roboto,Be Vietnam Pro,Plus Jakarta Sans,Nunito,Montserrat,Open Sans), border radius (sharp,rounded,pill), and window size (compact350×480,default390×560,large430×640). - Placement & Behavior: Corner position (
bottom-rightorbottom-left), X/Y offsets (0–200px), launcher button size (36–96px), and optional auto-open delay (1–300seconds). - Messaging Content: Header title (up to 80 chars), status subtitle (up to 120 chars), avatar upload (max 2 MB), welcome message (up to 500 chars), input placeholder (up to 80 chars), and up to 4 Quick Replies (max 60 chars each).
- Pre-chat Form: Optionally require visitors to submit Name and Phone (plus optional Email) before starting a chat.
2. Conversations
Section titled “2. Conversations”- Switch the widget status between
CONNECTED(active) andPAUSED. - Assign an AI Bot and toggle AI auto-reply on or off for this widget.
3. Install
Section titled “3. Install”Embed the SDK script tag right before the closing </body> tag on your site:
<script src="https://<your-omnybot-domain>/sdk/v1/widget.iife.js" data-site-key="<SITE_KEY>" async></script>The Install tab provides ready-to-copy snippets for 7 platforms: HTML Snippet, React / Next.js, Angular, Vue, WordPress, Google Tag Manager (GTM), and Shopify, in two modes:
- Anonymous visitors: Basic
<script>embed only. - Logged-in users: Calls
window.OmnyBot("identify", { externalId, name, phone, email, hmac })to sync authenticated customer identity from your app.
4. Security
Section titled “4. Security”- Allowed Domains (
allowedDomains): Whitelist up to 20 domains (supports wildcards such as*.example.com). Leave empty to allow any validhttp/httpsorigin. - Allow
localhost: Enable to test the widget on local development origins (localhost,127.0.0.1,[::1]). - Require HMAC (
requireHmac): When enabled, allidentify()calls must include a server-generated HMAC signature computed with yourhmacSecret. - Rotate Secret: Generates a new
hmacSecretand immediately invalidates active visitor JWT sessions.
Public SDK Limits
Section titled “Public SDK Limits”To prevent abuse and keep widgets responsive, the Public SDK enforces these defaults:
- Visitor messages: Up to 2,000 characters and up to 5 attachments per message.
- Visitor file uploads (images / PDF): Max 5 MB per file.
- Rate Limits:
- Session initialization: 15 requests / 5 minutes per IP.
- Sending messages: 25 requests / minute per IP and 10 requests / minute per visitor.
- File uploads: 10 requests / minute per IP and 3 requests / minute per visitor.