Appearance

Connecting the Website Widget ​

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

At a glance ​

You needWhere in the appResult
An agentChannels → open Website Widget → Connect agent to this channelThe agent that answers website chats
Widget settingsThe Website Widget settings formBranding, placement, language, behavior
The embed snippetGenerate the widget code buttonTwo blocks of code to paste into your site
A place to pasteYour site's <head> and <body>Live widget on every page

Connect in 4 steps:

  1. Open Channels and choose Website Widget.
  2. Connect your agent 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 agent 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 agent 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).
  • Excluded Pages: Paths where the widget should not appear (e.g. /cart), one per line.
  • 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.

SettingWhat it does
Ad-Oriented Widget Appearance toggleEnable modern square widget with popup messages.
Widget TitleHeadline shown on the square widget. Required in this mode, with a character limit shown next to the field.
Widget DescriptionSupporting text under the title. Also required, with a character limit.
Popup Messages IntervalHow fast popup messages appear one after another (0.5–3 seconds).
Show popup messages when the widget is collapsedKeep the popups visible even when the widget is closed.
Disable automatic expansionStops 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 MessagePaired 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).
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 agent.

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 agent 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>
AttributeRequiredWhat it is
data-mcb-user-idYesYour internal id of the logged-in user
data-mcb-user-nameNoDisplay name of the user
data-mcb-user-tokenYesSignature 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:

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

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.
  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 agent.
  4. Check Active Chats in the app: the conversation appears under the Widget ID you configured.

See also ​

Copyright © 2023 MyChatbot