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

In the app

Channels live at 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 20) — 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.
• Contact form fields: Choose which fields visitors fill in before starting a chat. You can rename, reorder, hide, or mark Name, Email, and Phone as Required, and use Add custom field for extra text fields. When both Email and Phone are shown and neither is required, visitors must provide at least one of them.
• 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).
• 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.

In the app

All of the above lives on the Website Widget settings form at 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.
Expand automatically only on the first visit	Shown while automatic expansion is on: the widget expands by itself on a visitor's first visit only, not on every page load.
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).

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).

<!-- 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.

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:

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

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:

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.

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:

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

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

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, click Generate next to the Identity Secret field in the widget settings, then save the widget.

Making changes to the widget appearance

To update your widget configuration:

1. Return to the Website Widget settings at 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.

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.

Protection from automated traffic

The widget is public: anyone who opens your site can write to it, including bots and automated site checkers. So that this traffic can't use up your balance, MyChatBot counts conversations and messages per visitor address (IP; for IPv6, its /64 network) on each widget, per clock hour (UTC):

When one address, within one clock hour…	What happens
writes in more than 20 conversations or sends more than 120 messages	Until 24 hours after it last went over the limit, every chat it writes in is moved to the Spam tab, where it stays until you restore it. Messages are still saved, but the assistant doesn't reply and no follow-ups are sent. Chats it started before that and doesn't write in again stay where they are; mark them as spam yourself if needed. Contact-form submissions count toward the limits and are still saved; the chat moves to Spam once the address sends a message in it. You get a notification in the app (at most one a day, by UTC, for each widget).
writes in more than 200 conversations or sends more than 1,200 messages	For the rest of that hour, its messages and contact-form submissions are refused and not saved. The visitor's message doesn't appear in the widget. After that hour, the address is held as in the row above.

Real visitors stay well below these limits, and visitors from other addresses are not affected.

If a real customer was caught, for example several people writing from one office network, find their chat in the Spam tab and click Restore to work. The assistant answers their next message; reply yourself to anything they wrote while the chat was in Spam. Restore each chat on its own: new chats from that address still go to Spam until the 24 hours are over.

See also

• Build an agent
• Webhooks