Customize Web Messenger V2

  • Updated on Mar 26, 2026
  • Published on Mar 26, 2026
  • 14 minute(s) read
Prev Next

This guide explains how you can customize Web Messenger. It covers two main areas:

Web Messenger has two design versions. V2 (updated design) is enabled when "Enable Updated Web Messenger" is turned on in your channel's settings via the admin panel. V1 (legacy design) is the default when this setting is not enabled.

PART 1: SCRIPT EMBED CUSTOMIZATION

These are parameters and techniques you can use directly in your website's HTML and JavaScript code to customize Web Messenger behavior and appearance.

Global parameters

Global parameters can be added to either a JavaScript window object or URL query parameters to change the layout of Web Messenger.

  • isFullScreen: If this parameter is set to true, Web Messenger will start in full screen.

  • mbHideHeader: If this parameter is set to true, Web Messenger's header will be hidden.

  • mbWidget: If this parameter is set to true, the Web Messenger widget will open by default without requiring a click on the button.

  • mbHideIcon: If this parameter is set to true, the floating widget button will be hidden entirely. Useful when you trigger the widget programmatically.

  • mbOnclickDisabled: If this parameter is set to true, click interaction on the widget button will be disabled.

You can add these parameters either to your page URL as query parameters or to the window object before the widget script loads.

  • URL: Add the parameters to your page URL as query parameters. For example: https://app.mindbehind.com/chatbot-test?channelId={your_channel_id}&isFullScreen=true

  • Window object: Add this JavaScript inside a <script> tag on your page, before the Web Messenger SDK script loads:

    window.mbIsFullScreen = true;
window.mbHideIcon = true;

    For the assistant to start without user input, add the following HTML snippet (including the <script> tag) to your page:

    <script>
    function openChat(retryCount, timeoutDuration) {
        setTimeout(function () {
            if (typeof mbShowOnclick === 'function') {
                mbShowOnclick(true);
            } else {
                if (retryCount > 5) {
                    console.error("Could not open chat");
                    return;
                }
                retryCount += 1;
                openChat(retryCount, timeoutDuration * 2);
            }
        }, timeoutDuration)
    }
    openChat(0, 100)
</script>

Window object actions

After the widget is initialized, you can use the following methods on the window object to control Web Messenger programmatically.

  • Open or close the widget

Run this JavaScript in your browser console or inside a <script> tag after the widget has loaded:

// Open the widget
window.mbShowOnclick(true);

// Close the widget
window.mbShowOnclick(false);

  • Send a message programmatically

You can send a message on behalf of the user using startChatWithText. This function opens the widget automatically and sends the message. Run this JavaScript after the widget has loaded:

window.startChatWithText("Hello, I need help!");

This function returns true if the message was sent successfully. It returns false if the message is blocked due to pending GDPR consent or incomplete OTP authentication.

  • Auto-start the widget

To automatically open the widget after initialization, add this JavaScript inside a <script> tag before the SDK script loads:

window.MindbehindSDK = {
    autoStart: true
};

  • Inject an external session

If you want to pass a user session from your system, add this JavaScript inside a <script> tag before the widget initializes:

window.MB_CLIENT = "your-user-session-id";

For token-based authentication, add this JavaScript in the same way:

window.MB_TOKEN = "your-jwt-token-here";

Session priority order is: window.MB_CLIENT (highest) > localStorage.MB_SESSION > sessionStorage.MB_SESSION.

Add language support

You can add a language property to the global window object. Add this JavaScript inside a <script> tag before the SDK script loads:

window.language = "en"

window.language = "ar"

When set to ar, the entire chat interface switches to RTL (right-to-left) layout automatically.

Allow full chat page usage

To allow full chat page usage, place the following HTML in the <head> section of your page. This is a complete HTML example showing the required structure:

<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Web Messenger</title>
    <script>
        window.mbIsFullScreen = true;
    </script>
    <script async src='https://cdn.mindbehind.com/sdk/mindbehind-sdk.js?auto=true&key={YOUR_KEY}&api=tr'></script>
</head>

CSS variables

Web Messenger uses CSS custom properties (variables) to control its visual appearance. You can override these from your website's JavaScript or CSS to match your brand. The default values differ between V1 and V2.

V2 CSS variables

These are CSS custom properties. You can override them in your website's stylesheet (.css file) or inside a <style> tag:

:root {
    /* Typography */
    --mb-mwc-font-stack: "Figtree", sans-serif;
    --mb-mwc-fontSize-xs: 12px;
    --mb-mwc-fontSize-s: 14px;
    --mb-mwc-fontSize-sm: 16px;
    --mb-mwc-fontSize-md: 18px;
    --mb-mwc-fontSize-lg: 22px;
    --mb-mwc-fontSize-xl: 26px;
    --mb-mwc-fontSize-xxl: 32px;
    --mb-mwc-fontWeight-regular: 300;
    --mb-mwc-fontWeight-medium: 500;
    --mb-mwc-fontWeight-semi: 600;
    --mb-mwc-fontWeight-bold: 700;
    --mb-mwc-lineHeight-xs: 18px;
    --mb-mwc-lineHeight-sm: 22px;
    --mb-mwc-lineHeight-md: 28px;

    /* Message colors */
    --mb-mwc-agent-message-background-start-color: #eff2f4;
    --mb-mwc-agent-message-background-end-color: #eff2f4;
    --mb-mwc-agent-message-text-color: #292929;
    --mb-mwc-client-message-background-start-color: #3456E3;
    --mb-mwc-client-message-background-end-color: #3456E3;
    --mb-mwc-client-message-text-color: #fff;

    /* Button theming (V2) */
    --mb-mwc-button-background-start-color: #3456E3;
    --mb-mwc-button-background-end-color: #3456E3;
    --mb-mwc-button-text-color: #fff;
    --mb-mwc-button-hover-background-color: #2a45b8;
    --mb-mwc-button-border-radius: 8px;

    /* UI colors */
    --mb-mwc-primary-color: #3456E3;
    --mb-mwc-text-primary: #292929;
    --mb-mwc-text-secondary: #666;
    --mb-mwc-light-gray-color: #9b9b9b;
    --mb-mwc-dark-gray-color: #4d4d4d;
    --mb-mwc-danger-color: #DC2A2A;
    --mb-mwc-success-color: #58aa18;
    --mb-mwc-warning-color: #f5a623;
    --mb-mwc-radius: 16px;

    /* Borders & neutrals (V2) */
    --mb-mwc-border-color: #DCDFE6;
    --mb-mwc-border-color-hover: #C0C4CC;
    --mb-mwc-border-color-active: #A8ABB2;
    --mb-mwc-neutral-0: #F5F7FA;
    --mb-mwc-neutral-100: #EFF2F4;
    --mb-mwc-neutral-300: #b1b7c4;
}

You can see how each default value functions below:

Typography:

  • --mb-mwc-font-stack sets the default font family for the text inside web chat.

  • --mb-mwc-fontSize-xs sets the smallest font size (12px).

  • --mb-mwc-fontSize-s sets the small font size (14px). (V2 only)

  • --mb-mwc-fontSize-sm sets the font size for standard text and titles (16px).

  • --mb-mwc-fontSize-xl sets the font size of the emojis.

  • --mb-mwc-fontWeight-regular sets the default font weight for the text.

  • --mb-mwc-fontWeight-semi sets the semi-bold font weight (600). (V2 only)

  • --mb-mwc-lineHeight-xs sets the default line height for the text.

  • --mb-mwc-lineHeight-sm sets the line height of exit popup buttons.

Message colors:

  • --mb-mwc-agent-message-background-start-color sets the linear start color of the background for the messages on the left-hand side.

  • --mb-mwc-agent-message-background-end-color sets the linear end color of the background for the messages on the left-hand side.

  • --mb-mwc-agent-message-text-color sets the text color for the messages on the left-hand side.

  • --mb-mwc-client-message-background-start-color sets the linear start color of the background for the messages on the right-hand side.

  • --mb-mwc-client-message-background-end-color sets the linear end color of the background for the messages on the right-hand side.

  • --mb-mwc-client-message-text-color sets the text color for the messages on the right-hand side.

Button theming (available in V2):

With V2, you can customize the appearance of action buttons (quick replies, card buttons, form buttons) using these variables:

  • --mb-mwc-button-background-start-color sets the gradient start color for action buttons.

  • --mb-mwc-button-background-end-color sets the gradient end color for action buttons.

  • --mb-mwc-button-text-color sets the text color for action buttons.

  • --mb-mwc-button-hover-background-color sets the hover background color for action buttons.

  • --mb-mwc-button-border-radius sets the border radius of action buttons.

UI colors:

  • --mb-mwc-primary-color sets the primary accent color used across the interface.

  • --mb-mwc-light-gray-color sets the color for the text box when sending input is invalid.

  • --mb-mwc-dark-gray-color sets the color of dark gray for the messages (used heavily).

  • --mb-mwc-danger-color sets the error color.

  • --mb-mwc-radius sets the default border radius for chat bubbles (16px in V2, was 10px in V1).

Borders & neutrals (available in V2):

V2 introduces additional variables for fine-tuning borders and neutral background colors:

  • --mb-mwc-border-color sets the default border color for input fields and containers.

  • --mb-mwc-border-color-hover sets the border color on the hover state.

  • --mb-mwc-border-color-active sets the border color on active/focus state.

  • --mb-mwc-neutral-0 sets the lightest neutral background color.

  • --mb-mwc-neutral-100 sets the neutral background color used for agent messages.

V1 CSS variables

If you are using the legacy V1 design, the following default values apply. You can override them in your website's stylesheet (.css file) or inside a <style> tag:

:root {
    --mb-mwc-font-stack: "Figtree", sans-serif;
    --mb-mwc-fontSize-xs: 12px;
    --mb-mwc-fontSize-sm: 16px;
    --mb-mwc-fontSize-xl: 26px;
    --mb-mwc-fontWeight-regular: 300;
    --mb-mwc-lineHeight-xs: 18px;
    --mb-mwc-lineHeight-sm: 22px;
    --mb-mwc-light-gray-color: #9b9b9b;
    --mb-mwc-dark-gray-color: #4d4d4d;
    --mb-mwc-agent-message-background-start-color: #fff;
    --mb-mwc-agent-message-background-end-color: #fff;
    --mb-mwc-agent-message-text-color: #4d4d4d;
    --mb-mwc-client-message-background-start-color: #6b4491;
    --mb-mwc-client-message-background-end-color: #ec4e7c;
    --mb-mwc-client-message-text-color: #fff;
    --mb-mwc-danger-color: #DC2A2A;
}

You can see how each default value functions below:

  • --mb-mwc-font-stack sets the default font family for the text inside web chat.

  • --mb-mwc-fontSize-xs sets the default font size for the text.

  • --mb-mwc-fontSize-sm sets the font size for titles.

  • --mb-mwc-fontSize-xl sets the font size of the emojis.

  • --mb-mwc-fontWeight-regular sets the default font weight for the text.

  • --mb-mwc-lineHeight-xs sets the default line height for the text.

  • --mb-mwc-lineHeight-sm sets the line height of exit popup buttons.

  • --mb-mwc-light-gray-color sets the color to light gray for the text box when sending input is invalid.

  • --mb-mwc-dark-gray-color sets the color of dark gray for the messages (used heavily).

  • --mb-mwc-agent-message-background-start-color sets the linear start color of the background for the messages on the left-hand side.

  • --mb-mwc-agent-message-background-end-color sets the linear end color of the background for the messages on the left-hand side.

  • --mb-mwc-agent-message-text-color sets the text color for the messages on the left-hand side.

  • --mb-mwc-client-message-background-start-color sets the linear start color of the background for the messages on the right-hand side.

  • --mb-mwc-client-message-background-end-color sets the linear end color of the background for the messages on the right-hand side.

  • --mb-mwc-client-message-text-color sets the text color for the messages on the right-hand side.

  • --mb-mwc-danger-color sets the error color.

Change the variables

These variables are set on the root scope and can also be changed dynamically via JavaScript. Run this JavaScript inside a <script> tag or in your browser console:

document.documentElement.style.setProperty({variable_name}, {value})

For example:

document.documentElement.style.setProperty("--mb-mwc-client-message-background-start-color", "#1a73e8")
document.documentElement.style.setProperty("--mb-mwc-client-message-background-end-color", "#1a73e8")

To change button colors (V2):

document.documentElement.style.setProperty("--mb-mwc-button-background-start-color", "#28a745")
document.documentElement.style.setProperty("--mb-mwc-button-background-end-color", "#28a745")
document.documentElement.style.setProperty("--mb-mwc-button-text-color", "#ffffff")

To read the current value of a variable, use this JavaScript:

getComputedStyle(document.documentElement).getPropertyValue({variable_name})

Unique identifiers

Web Messenger uses mwc- prefixed IDs and class names for its elements. You can use these identifiers to target specific parts of the chat interface for custom CSS styling or JavaScript manipulation.

Main containers:

  • #MB_WEBCHAT_WIDGET: Outermost widget container

  • #mwc-microwebchat: Inner chat container

  • html.mb-mwc-v2: V2 design scope (on document root)

  • html.mb-mwc-v1: V1 design scope (on document root)

Header:

  • #mwc-header: Header container

  • #mwc-companyInfo: Brand logo and company name area

  • #mwc-bannerActions: Header action buttons area

  • #mwc-flow-close: Close (end conversation) button

  • #mwc-flow-minimize: Minimize button

  • #mwc-flow-resize: Resize toggle button (V2 only)

Input area:

  • #mwc-inputActions: Input actions container (all icons)

  • .mwc-messageInput: Message input wrapper

  • .mwc-messageInputTextArea: Text input area

  • #fileInput: File upload input

  • .mwc-trademark: Powered by Mindbehind branding in the input area

  • .mwc-conversation-starter: Conversation starter buttons (V2 only)

Messages:

  • .mwc-agentMessage: Agent message bubble

  • .mwc-clientMessage: Client (user) message bubble

  • .mwc-textMessage: Text message content

  • .mwc-mediaMessage: Media message container (image/video/audio)

  • .mwc-imageMessage: Image message

  • .mwc-videoMessage: Video message

  • .mwc-audioMessage: Audio message

  • .mwc-fileMessage: File message

  • .mwc-card-message-container: Card carousel container

  • .mwc-quickReplyMessage: Quick reply container

  • .mwc-formMessage: Form message

  • .mwc-locationMessage: Location message

  • #mwc-listMessage: List message

  • .mwc-rateContainer: Rate/feedback container

  • .mwc-typing-indicator: Typing indicator

Popups and drawers:

  • .mwc-popup-background: Exit popup overlay

  • #mwc-popup-container: Popup content container

  • #mwc-popup-content: Popup content area

  • #mwc-text-header: Popup title text

  • #mwc-text-message: Popup body text

  • #mwc-buttons-container: Popup buttons container

  • #mwc-bottom-drawer-wrapper: Bottom drawer container (V2 only)

  • #mwc-bottom-drawer-content: Bottom drawer content (V2 only)

  • #mwc-bottom-drawer-header: Bottom drawer header (V2 only)

  • #mwc-bottom-drawer-close-icon: Bottom drawer close button (V2 only)

Other:

  • .mwc-poweredByContainer: Powered by label

  • .mwc-connectionErrorIcon: Connection error icon

  • #mwc-location-picker: Location picker container

  • #mwc-current-location-btn: Current location button (V2 only)

  • #mwc-authentication-single-form: Authentication form (V2 only)

Change or remove elements

Using the unique identifiers listed above, you can hide, restyle, or modify individual elements of Web Messenger. Run this JavaScript inside a <script> tag after the widget has loaded, or in your browser console:

document.getElementById("mwc-inputActions").style.display = "none";  // Hides the input actions area completely
document.getElementById("mwc-header").style.display = "none";  // Hides the header
document.getElementById("mwc-flow-resize").style.display = "none";  // Hides the resize button (V2)
document.getElementById("mwc-flow-minimize").style.display = "none";  // Hides the minimize button
document.querySelector(".mwc-poweredByContainer").style.display = "none";  // Hides the powered by label

For V1 design, the following icon IDs are available in the input footer area:

[
    "mwc-inputActions",
    "iconsContainer",
    "quickReplyIcon",
    "forwardConvIcon",
    "attachIcon",
    "infoIcon",
    "locationIcon",
    "tagIcon",
    "holdIcon",
    "noteIcon",
    "emojiIcon",
    "emojiPicker"
]

These are the IDs of each icon in the footer. You can hide them separately or fully.

You can take a look at some of the examples below. Run this JavaScript inside a <script> tag after the widget has loaded:

document.getElementById("mwc-inputActions").style.display = "none";  // This command hides the footer area completely.
document.getElementById("iconsContainer").style.display = "none";  // This command hides all the icons and leaves their place empty.
document.getElementById("emojiPicker").style.display = "none";  // This command hides the emoji picker pop-up.
document.getElementById("quickReplyIcon").style.display = "none";  // This command hides only the quickReplyIcon (same for all the rest).

You can also apply custom CSS using the design version scope. Add these CSS rules to your website's stylesheet (.css file) or inside a <style> tag. This lets you write styles that only apply to one design version:

/* Custom styles for V2 only */
html.mb-mwc-v2 #mwc-header {
    background-color: #1a1a2e;
}

html.mb-mwc-v2 .mwc-agentMessage {
    border-radius: 8px;
}

/* Custom styles for V1 only */
html.mb-mwc-v1 #mwc-header {
    background-color: #662d91;
}

Part 2: V2 CONFIGURATION SETTINGS

The following settings are available with the V2 design. They are configured from the admin panel under your Web Messenger channel's settings and automatically applied to the widget. Some of these can also be overridden via CSS variables (noted where applicable).

Conversation starters

Display prompt buttons before the conversation begins to guide users toward common topics or actions. Users see these buttons in the initial chat view and can click one to start a conversation with that message.

Configure in the admin panel with the Conversation Starter Prompts setting. You can also set a custom label for the start button using the Start Conversation Button Text setting.

AI disclaimer

Show a disclaimer text below the chat input to inform users that they are interacting with an AI assistant. This text appears persistently at the bottom of the chat interface.

Configure in the admin panel with the AI Disclaimer Text setting.

Button theming

Customize the appearance of all action buttons in the chat, including quick reply buttons, card action buttons, and form submit buttons.

Configure in the admin panel:

  • Button start color: Gradient start color for buttons. Default: #3456E3

  • Button end color: Gradient end color for buttons. Default: #3456E3

  • Button text color: Text color for buttons (auto-calculated if not set). Default: Auto-contrast

  • Button border radius: Corner roundness of buttons. Default: 8px

Tip: These can also be overridden from your website's code using the --mb-mwc-button-* CSS variables described in the CSS variables section above.

Font customization

Set a custom font family for the entire chat interface to match your website's typography.

Configure in the admin panel with the Font Family setting. The value should be a valid CSS font-family string.

Tip: This can also be overridden from your website's code using the --mb-mwc-font-stack CSS variable.

Widget positioning

Control where the Web Messenger widget button appears on the page.

Configure in the admin panel:

  • Widget position: Widget placement on the page. Default: bottom-right

  • Side space: Horizontal distance from the edge (px). Default: 20

  • Bottom space: Vertical distance from the bottom (px). Default: 20

Authentication

V2 introduces a combined authentication overlay that handles user verification before the conversation starts. The form can include OTP (phone verification), name/email fields, and GDPR consent, all in a single view.

Configure in the admin panel:

  • Authentication type: None (anonymous), OTP (SMS verification), or Token (external JWT)

  • Require name: Whether the user must provide their name

  • Require email: Whether the user must provide their email

  • Require KVKK/GDPR: Whether the user must accept data consent before chatting

  • Default country: Default phone country code for OTP

Resize mode

V2 adds a resize button in the header that allows users to toggle between normal chat width and a larger (720px) expanded view on desktop devices. This is enabled automatically in V2 and requires no configuration.

Connection status

V2 displays a connection status indicator in the header. When the user loses internet connectivity, a visual indicator and a reconnection pop-up inform the user about the connection state. This is enabled automatically in V2 and requires no configuration.

Callout message

The callout message is a notification balloon that appears near the widget button to attract user attention. V2 features a redesigned callout with an updated visual style and improved positioning.

Configure in the admin panel:

  • Enable callout: Turn the callout balloon on/off

  • Callout text: The message text to display

  • Callout delay: Seconds to wait before showing the callout

  • Enable typing animation: Show a typing animation before the callout appears

  • Callout colors: Start/end background gradient and text color

V1 AND V2 cHANGELOG

Below is a summary of key differences between V1 (legacy) and V2 (updated) designs.

Visual changes

Feature

V1

V2

Client message colors

Gradient (#6b4491 to #ec4e7c)

Solid blue (#3456E3)

Agent message background

White (#fff)

Light gray (#eff2f4)

Agent message text

#4d4d4d

#292929 (darker)

Primary color

Purple (#662d91)

Blue (#3456E3)

Border radius

10px

16px (rounder)

Header style

Gradient background (client colors)

Clean white/transparent

Widget button

Classic icon

Redesigned icon with updated styling

Callout balloon

Classic style

Redesigned with a new visual style and improved positioning

Typing indicator

Basic animation

Enhanced typing animation

What you can do with V2

  • Conversation starters: Display prompt buttons before the conversation begins to guide users.

  • AI disclaimer: Show a disclaimer text below the chat input to inform users about AI usage.

  • Button theming: Customize colors, hover states, and border radius of all action buttons.

  • Font customization: Set a custom font family for the entire chat interface.

  • Widget positioning: Place the widget button at different positions on the page with custom spacing.

  • Resize button: Users can toggle between normal and large (720px) chat width on desktop.

  • Bottom drawer: A modal sheet component for presenting actions and content.

  • Authentication form: A combined OTP + KVKK consent overlay for user verification.

  • Connection status: A connection indicator in the header shows whether the chat is online.

  • Connection pop-up: A reconnection pop-up appears when the internet connection is lost.

New CSS variables in V2

  • Button theming: --mb-mwc-button-background-start-color,  --mb-mwc-button-background-end-color, --mb-mwc-button-text-color, --mb-mwc-button-hover-background-color, --mb-mwc-button-border-radius

  • Typography: --mb-mwc-fontSize-s (14px),--mb-mwc-fontWeight-semi (600)  

  • Borders: --mb-mwc-border-color, --mb-mwc-border-color-hover, --mb-mwc-border-color-active

  • Neutrals: --mb-mwc-neutral-0, --mb-mwc-neutral-100, --mb-mwc-neutral-300

  • Layout: --mb-mwc-corner-action-icon-size (24px), --mb-mwc-icon-size (40px), --mb-mwc-input-max-line-count(5)  

New unique identifiers in V2

  • #mwc-flow-resize: Header resize button

  • #mwc-bottom-drawer-wrapper: Bottom drawer container

  • #mwc-bottom-drawer-content: Bottom drawer content

  • #mwc-bottom-drawer-header: Bottom drawer header

  • #mwc-bottom-drawer-close-icon: Bottom drawer close button

  • #mwc-authentication-single-form: Authentication form container

  • #mwc-current-location-btn: Current location button

  • .mwc-conversation-starter: Conversation starter container

© 2026 Insider One. All rights reserved.
Privacy Policy