---
url: 'https://docs.mychatbot.app/channels/website-widget.md'
description: >-
  Add a chat widget to your website so visitors can talk to your AI sales
  assistant directly on the page — no external messaging app required.
---

# Connecting the Website Widget

Add a chat widget to your website so visitors can talk to your AI sales assistant directly on the page — no external messaging app required.

## At a glance

| You need | Where in the app | Result |
| --- | --- | --- |
| An assistant | **Channels** → open **Website Widget** → **Connect agent to this channel** | The assistant that answers website chats |
| Widget settings | The **Website Widget** settings form | Branding, placement, language, behavior |
| The embed snippet | **Generate the widget code** button | Two blocks of code to paste into your site |
| A place to paste | Your site's `<head>` and `<body>` | Live widget on every page |

**Connect in 4 steps:**

1. Open **Channels** and choose **Website Widget**.
2. Connect your assistant and configure the widget.
3. Click **Generate the widget code** and copy the two code blocks.
4. Paste the first block into `<head>` and the second into `<body>`.

::: tip In the app
Channels live at **[app.mychatbot.app/channels](https://app.mychatbot.app/channels)**. Open the **Website Widget** card, then use **Connect agent to this channel** to pick which assistant replies to visitors.
:::

## Widget configuration options

The settings are grouped the same way you'll see them in the app: **Widget copy & branding**, **Placement & sizing**, **Language & avatar**, **Appearance**, and **Behavior**.

### Widget copy & branding

* **Widget ID**: A name for this widget (Latin letters and hyphens only, no spaces). It's shown in **Active Chats** so you can tell where a message came from.
* **Widget pop-up content**: The bubble message that appears next to the widget button a few seconds after the page loads. Leave it empty to show only the icon with no pop-up.
* **Widget heading text**: The text shown beneath your logo before the contact options.
* **First message agent sends**: The opening line the assistant sends automatically when the chat opens.
* **Your business logo URL**: A public link to your brand or company logo (optional) — or upload an image file directly.
* **Your business website URL**: Used to preview the widget in context.

### Placement & sizing

* **Widget icon margin**: Distance between the page edge and the widget icon (set separately for desktop and mobile).
* **Widget window scale** / **Widget icon scale**: Size of the chat window and the chat button on desktop (recommended window value: 0.8; icon suggestion: 1.2).
* **Widget window scale (mobile)** / **Widget icon scale (mobile)**: The same sizing for mobile, plus a **Fixed to full-screen view** option for phones.
* **Widget icon position**: **Dock to left edge** or **Dock to right edge**.

### Language & avatar

* **Language**: The default language for the widget interface.
* **Avatar**: Choose the assistant avatar shown in the widget, or upload your own image.

### Appearance

* **Custom color**: Pick a brand color that matches your site.
* Decide how the widget button behaves on the page (see **Hide widget icon** under Behavior for custom-button setups).

### Behavior

* **Reply Delay (s)**: Shown next to the **Connect agent to this channel** toggle at the top of the panel. Waits this many seconds before the assistant replies (0–180, default 30) — useful for letting visitors finish a multi-message thought.
* **Disable contact form**: Turn on to let visitors start chatting without entering a phone or email.
* **Hide widget icon**: Hides the default floating button. Turn it on when you want to open the widget from your own custom buttons instead (see [Custom widget control](#custom-widget-control)).
* **Excluded Pages**: Paths where the widget should not appear (e.g. `/cart`), one per line.
* **Hide “Powered by MyChatBot”**: Removes the “Powered by MyChatBot” line from the widget's home screen and contact form. Included in the **Pro**, **Multipro** and **Corporate** plans; on other plans, and on the free trial you start with at sign-up, the switch is shown but locked. If your plan changes to one without it, or your subscription ends, the line comes back on its own, and your choice returns when you move back to a plan that includes it.
* **Show client status**: Let visitors pick a status (for example *Potential Client* or *Regular Customer*) when they fill out the contact form. You can add up to 10 status options and optionally make the choice **Required**.
* **Social Links**: Add buttons for your social profiles — Viber, WhatsApp, Instagram, Telegram, OLX, Facebook, and TikTok.

::: tip In the app
All of the above lives on the **Website Widget** settings form at **[app.mychatbot.app/channels](https://app.mychatbot.app/channels)**. Use **Preview** to open the widget on your business website URL before you deploy.
:::

## Ad-Oriented Widget

**Ad-Oriented Widget Appearance** is an optional mode that swaps the classic bubble for a modern square widget with rotating popup messages — built for ad landing pages where you want to pitch offers before the visitor even opens the chat.

| Setting | What it does |
| --- | --- |
| **Ad-Oriented Widget Appearance** toggle | Enable modern square widget with popup messages. |
| **Widget Title** | Headline shown on the square widget. Required in this mode, with a character limit shown next to the field. |
| **Widget Description** | Supporting text under the title. Also required, with a character limit. |
| **Popup Messages Interval** | How fast popup messages appear one after another (0.5–3 seconds). |
| **Show popup messages when the widget is collapsed** | Keep the popups visible even when the widget is closed. |
| **Disable automatic expansion** | Stops the widget from expanding on its own. |
| **Popup Messages** (up to 7) | Messages that appear one by one at the set interval — older messages on top, newer on bottom. Use them to highlight key offers or engage visitors. |
| **User Template Message** | Paired with each popup message; when a visitor clicks the popup, this template is sent to the chat *on their behalf*, kicking off the conversation. |

Use **Add Message** to add popup/template pairs, and the delete icon to remove one (you'll be asked to confirm).

::: warning First message is replaced in this mode
While the Ad-Oriented widget is enabled, the **First message agent sends** field is hidden — the conversation starts from the visitor's clicked **User Template Message** instead. **Widget Title** and **Widget Description** become required and the widget won't save without them.
:::

## Installing the widget on your website

After configuring the widget, click **Generate the widget code**, then **Copy script** from the pop-up.

* Add the first block to the **end of the `<head>`** section.
* Add the second block to the **end of the `<body>`** section (after all other scripts).

```html
<!-- To the BOTTOM head tag -->
<link rel="stylesheet" href="https://api.mychatbot.app/sw-assets/v1/assets/style.css" />
<script src="https://api.mychatbot.app/sw-assets/v1/widget.js"></script>

<!-- To the BOTTOM of the body tag -->
<div id="my-chat-widget-container"></div>
<script>
	const metadata={/*YOUR METADATA GOES HERE*/};
	const config = {/*YOUR CONFIG GOES HERE*/};
	MyChatBot.mount('#my-chat-widget-container', config);
</script>
```

## Query parameter widget opening

To bind widget opening to a custom link or button, use a special query parameter:

* Add `?open-mcb-widget=1` to any URL on your website.
* When users visit a URL with this parameter, the widget opens automatically.
* This is equivalent to the user clicking the widget button.

**Example use cases:**

* Link from email campaigns: `https://yoursite.com/contact?open-mcb-widget=1`
* Custom "Chat with us" buttons that redirect to the same page with the parameter.
* Opening the widget from other parts of your website interface.

This is useful when you want multiple entry points for visitors to start a conversation with your assistant.

## Custom widget control

To open the chat widget from your own buttons, turn on **Hide widget icon** in the widget settings and add the CSS class `mcb_widget_activator_button` to any button or element on your website. When users click an element with this class, the chat widget opens — letting you integrate chat into your existing design and UI.

::: warning Activator element must exist at page load
The element carrying the `mcb_widget_activator_button` class must already be present on the page when it loads, or the widget cannot bind the click event. If you add the element dynamically after load, the click will not open the widget.
:::

## Identifying logged-in users

If your website has customer accounts, you can tell the widget who is chatting. The assistant then sees that customer's data (for example order history from your own system) in every conversation, and chats are linked to the real customer instead of an anonymous visitor.

There are two ways to pass the identity — pick whichever fits your site:

### Option 1: data attributes

Put attributes on the same container div the widget mounts into:

```html
<div
  id="my-chat-widget-container"
  data-mcb-user-id="42"
  data-mcb-user-name="Olena"
  data-mcb-user-token="<signature from your server>"
></div>
```

| Attribute | Required | What it is |
| --- | --- | --- |
| `data-mcb-user-id` | Yes | Your internal id of the logged-in user |
| `data-mcb-user-name` | No | Display name of the user |
| `data-mcb-user-token` | Yes | Signature of the user id, generated by your server (see [Signing the user id](#signing-the-user-id)) |

You don't have to have the attributes ready before the widget loads: the widget watches the container and picks the values up whenever they appear or change. If your account area loads user data asynchronously, just set the attributes when the data arrives.

### Option 2: the `identify()` call

For single-page apps, or when you want to pass extra data, call `MyChatBot.identify()` from your own JavaScript at any point after the widget script has loaded:

```js
MyChatBot.identify({
  user_id: '42',
  username: 'Olena',
  token: signatureFromYourServer,
  context: {
    plan: 'Premium',
    orders_total: 7,
    last_order: '2026-07-12, #10393, delivered',
  },
})
```

`context` is optional: any data your page fetches from your own backend about the logged-in user. The assistant sees it as part of the client's profile and can use it in replies. Keep it compact — up to 50 fields, and long values are trimmed to 2000 characters.

::: warning Context is a hint, not proof
Only the user id is covered by the signature. The `context` object is supplied by the page, so the logged-in user could technically alter data about themselves before it is sent. Use it to personalize conversations — don't let the assistant grant discounts or take irreversible actions based on it alone.
:::

Both options work together: attributes can provide the id and token while a later `identify()` call adds `context`.

### Signing the user id

The token proves the identity is real — without it, anyone could open your site and claim to be another customer by editing the page in developer tools. The widget ignores identities without a valid token.

Generate the token **on your server** (never in browser JavaScript) as a hex HMAC-SHA256 of the user id, using your widget's **Identity Secret**, and render it into the page for the logged-in user:

```js
// Node.js
const crypto = require('crypto')
const token = crypto.createHmac('sha256', IDENTITY_SECRET).update(String(userId)).digest('hex')
```

```php
// PHP
$token = hash_hmac('sha256', (string) $userId, $identitySecret);
```

::: warning Keep the Identity Secret on your server
The secret must never appear in page source or client-side code. Compute the token server-side and render only the token into the page. To get an Identity Secret for your widget, contact support — it is configured on your widget channel by our team.
:::

## Making changes to the widget appearance

To update your widget configuration:

1. Return to the **Website Widget** settings at **[app.mychatbot.app/channels](https://app.mychatbot.app/channels)**.
2. Make your changes.
3. Click **Update** (no need to re-download the script or reinstall it on your website).
4. Reload the page with your widget to see the changes.

::: tip Update vs. reinstall
You only need the embed snippet once. After that, every change you save with **Update** goes live on the next page reload — the code you pasted stays the same.
:::

## Test it

1. Before deploying, fill in **Your business website URL** and click **Preview** — the widget opens over your own site.
2. After pasting the snippet, reload any page of your site: the widget icon should appear in the corner you docked it to, with the pop-up bubble if **Widget pop-up content** is filled.
3. Send a message from the widget — you should get the **First message agent sends** (or a popup **User Template Message** flow in Ad-Oriented mode) and a live reply from the assistant.
4. Check **Active Chats** in the app: the conversation appears under the **Widget ID** you configured.

## See also

* [Build an agent](/agents/build-an-agent)
* [Webhooks](/channels/webhooks)