Web Chat Widget
The Web Chat channel puts a chat window on your website. Visitors click the chat button in a corner of the page and write to you. Their conversations land in the MonoChat inbox like those of any other channel, where your team, your flows and your AI agents answer them.
Connect the channel
- Go to Settings › Chat › Channels and click Connect.
- Select Web Chat.
- Fill in the settings below and save. Each field explains what it is for, and the right side of the form shows a preview of the window that changes as you edit. Switch the preview between the closed chat button, the opened window and a sample conversation.
- Copy the snippet the channel shows and add it to your website (see Install the snippet).
You can connect several Web Chat channels, for example one per website.
Settings
| Setting | What it does |
|---|---|
| Channel name | The channel's name in MonoChat. The window shows it as its heading when the widget title is empty. |
| Widget title | The heading of the chat window. |
| Subtitle | A line under the title, for example how soon you usually reply. Clear the field to hide the line. |
| Logo | An image shown next to the title: a PNG, JPEG, GIF, SVG or WebP file. |
| Colour | The colour of the chat button, the header and the visitor's messages. Text on it turns black or white so it stays readable. |
| Position | The bottom right or the bottom left of the page. |
| Attachments | Lets visitors send images, videos, audio and documents of up to 10 MB. |
| Emoji button | Shows a button with common emoji next to the message box. On by default. |
| Hide the launcher | Hides the chat button, so you open the window from your own button with the JavaScript API. |
| Mobile view | How the window opens on phones: Full screen, or Compact, a sheet over the lower three quarters of the page. |
| Allowed domains | The sites the window may appear on: an exact host (www.example.com) or all subdomains (*.example.com), with an optional port (localhost:3000). Left empty, any site may show it. |
Languages
The window's buttons and labels follow the visitor's browser language, and are in English when MonoChat does not have that language.
The widget title, the subtitle, the form introduction and the consent text have a version for each language of your workspace, set in Settings › CRM › Languages (see Language Settings). Click the field to write each version. The window shows the version in the visitor's browser language, or the one in your default language when that language has none.
To show the window in one language whatever the browser, call MonoChat('setLocale', 'tr-TR') from the JavaScript API.
Pre-chat form
When the form is off, visitors start writing right away. To ask them for an email address or a phone number, use a flow (see Flows and the widget).
When the form is on, the window asks for these before the first message:
| Field | Options |
|---|---|
| Name | Off, optional or required |
| Off, optional or required | |
| Phone | Off, optional or required |
You can also write the text shown above the fields, and add a consent checkbox with your own text and a link to your privacy policy. When the checkbox is on, visitors must tick it to start the chat. The name, email address and phone number are saved to the customer's profile.
Install the snippet
The channel shows a snippet with its widget address and its channel key already filled in, right after you connect it and under the preview when you edit the channel. Paste it before the closing </body> tag of every page that should show the chat:
<script>
window.MonoChat = window.MonoChat || function () { (MonoChat.q = MonoChat.q || []).push(arguments) }
</script>
<script async src="https://<widget address from the channel>/static/loader.js?key=<channel key>"></script>
The window loads after your page, so it does not slow the page down.
If your site still has the snippet of an older WebChat channel, remove it and paste the snippet of the new Web Chat channel in its place.
Full-page mode
To give the chat a whole page of its own, such as a support page, add &mode=fullpage to the second tag of the snippet:
<script async src="https://<widget address from the channel>/static/loader.js?key=<channel key>&mode=fullpage"></script>
The window then fills the page and stays open, without its header or the chat button, and close and toggle do nothing. It loads with the page instead of after it, and the Mobile view setting does not apply.
Google Tag Manager
- In your container, add a Custom HTML tag and paste the snippet into it as it is.
- Choose the All Pages trigger, or one that fires only on the pages that should show the chat.
- Click Submit, then Publish.
If your page's own scripts call MonoChat, they may run before the tag. Keep the first <script> of the snippet on the page too, so that their calls wait for the window.
Website builders and online stores
If you cannot edit your site's code, paste the snippet as it is into the field your platform offers for code on every page, at the end of the page or in the footer:
| Platform | Where the snippet goes |
|---|---|
| WordPress | Install the WPCode plugin and paste the snippet into its Footer box. On WordPress.com, whether you can add code depends on your plan. |
| Shopify | Online Store › Edit code: open theme.liquid and paste the snippet just before </body>. |
| Wix | Settings › Custom Code › Add Custom Code: choose all pages and Body – end. The site must be published and have a connected domain. |
| Squarespace | The Footer field of Code Injection, on the Core, Plus and Advanced plans. |
| Webflow | Site settings › Custom code › Footer code, then publish the site. |
| ikas | Sales Channel › Extensions › Scripts › Add Script: paste the snippet as the script content, save, and make sure the script is turned on. |
JavaScript API
The snippet defines a MonoChat function on your page. Call it from your own scripts, links and buttons to control the window. Calls made before the window has loaded wait until it is ready, so you can make them right after the snippet.
Commands
| Call | What it does |
|---|---|
MonoChat('open') | Opens the window. |
MonoChat('close') | Closes the window. |
MonoChat('toggle') | Opens the window when it is closed, closes it when it is open. |
MonoChat('hideLauncher') | Hides the chat button. The window still opens with open and toggle. |
MonoChat('showLauncher') | Shows the chat button again. |
MonoChat('setUser', { name, email, phone }) | Passes what you already know about the visitor. See Signed-in visitors. |
MonoChat('setLocale', 'tr-TR') | Shows the window in this language, whatever the browser language. See Languages. |
MonoChat('on', event, callback) | Calls callback each time event happens. See Events. |
Events
| Event | When | callback receives |
|---|---|---|
ready | The window has loaded. | Nothing |
open | The window opens, from the chat button or a call. | Nothing |
close | The window closes. | Nothing |
unread | The number of unread replies changes: a reply arrives while the window is closed, or the visitor opens it. | The number of unread replies |
Register your callbacks right after the snippet, so you do not miss ready.
Signed-in visitors
When the visitor is signed in to your site, pass their details with setUser. Every field is optional, and the window reads only name, email and phone.
- The pre-chat form is filled in with them. It is skipped when it has everything it asks for, unless the consent checkbox is on: visitors always tick it themselves.
- They are saved to the customer's profile in MonoChat, so your team sees who is writing.
- When the email address or the phone number is not valid, none of them is saved.
Examples
Open the window from your own button and hide the chat button:
<button onclick="MonoChat('open')">Chat with us</button>
<script>
MonoChat('hideLauncher')
</script>
Pass a signed-in user and show the window in the language of the page:
<script>
MonoChat('setUser', { name: 'Jane Doe', email: 'jane@example.com', phone: '+1 555 010 0000' })
MonoChat('setLocale', document.documentElement.lang)
</script>
Show the number of unread replies on your own button:
<button onclick="MonoChat('open')">Support <span id="chat-unread"></span></button>
<script>
MonoChat('hideLauncher')
MonoChat('on', 'unread', function (count) {
document.getElementById('chat-unread').textContent = count || ''
})
</script>
Send an event to your analytics when a visitor opens the window:
<script>
MonoChat('on', 'open', function () {
gtag('event', 'chat_opened')
})
</script>
Conversations
Each visitor is a customer in MonoChat, and their conversation is kept in their browser: a visitor who comes back on the same browser sees the last 200 messages, for 90 days after the last message. Another browser or device starts a new conversation. Your team's replies and typing appear in the window as they happen.
The emoji button next to the message box offers common emoji. Visitors can also type any emoji from their keyboard.
Messages a visitor sends show ticks, as on WhatsApp: one grey tick when the message is sent, two grey ticks when it has reached MonoChat, and two blue ticks once someone on your team has opened the conversation. In MonoChat, your replies show as delivered when the visitor's window receives them and as read when the visitor opens the window.
When the window is closed, a new reply shows the number of unread messages on the chat button and plays a short sound. Browsers play the sound only after the visitor has clicked or typed somewhere on the page.
Message types
The window shows messages as the MonoChat chat screen does: the agent's name above their replies, a line with the date where a new day starts, and the time inside each bubble, with the ticks on the visitor's messages.
Besides text, emoji and files, your replies can use the types below. Send them from the Send Message flow node, short messages, apps and functions (see Message Types).
| Type | How the window shows it |
|---|---|
| Image, video, audio, sticker | Inside the bubble. |
| Document | A card with the file type and name that downloads the file. |
| Quick replies | Buttons under the last message. A click sends the button's title as the visitor's reply. |
| Button | A message with an optional header (a text, an image, a video or a document), a footer and buttons that send a reply, open a web address or call a phone number. |
| CTA Url | A message with one button that opens a web address. |
| List | The rows inside the bubble, grouped by section. A click on a row sends it as the visitor's reply. |
| Carousel | Cards the visitor scrolls sideways, each with an image or a video, a title, a subtitle and buttons. |
| Location | A pin with the place's name and address that opens the place in Google Maps. |
| Location request | A Send location button. The browser asks the visitor for permission, then their location reaches MonoChat as a location message. |
| Contacts | Each contact's name and company, with links that call their phone numbers and write to their email addresses. |
Quick replies, reply buttons, list rows and the location request work only on the last message, so visitors cannot answer an old question.
Button icons
Buttons that open a web address can show an icon: choose it in the Icon field of a CTA Url message or a Web URL button. The field appears only when you build the message for Web Chat: other channels do not show icons. The icons are Link, Website, WhatsApp, Instagram, Messenger, Facebook, Telegram, TikTok, Phone, Email and Location; a button without an icon shows the link icon.
Flows and the widget
Welcome messages, business hours, offline replies, asking for an email address or a phone number and proactive messages are set up with flows, not with channel settings.
The Customer Action Received event starts a flow from the window:
- Chat widget opened for the first time: the visitor opens the window and has no open conversation. MonoChat starts the conversation, or reopens their closed one, so the flow can write to the visitor before they do. Opening the window again while the conversation is open does not trigger it again.
- Chat widget opened: the visitor opens the window, every time, the first time included. A visitor without an open conversation gets one, as above.
- Chat widget closed: the visitor closes the window during an open conversation.
When the pre-chat form is on, the window counts as opened once the visitor has filled it in.
Viewing a page with the widget triggers none of them. A visitor who has not written becomes a customer in MonoChat only when a flow listens for the action.
In full-page mode the window opens with the page, so loading the page counts as opening the window. Each channel counts at most 60 window openings a minute; openings beyond that start no flow.
To greet visitors, start a flow with Customer Action Received set to Chat widget opened for the first time and add a Send Message node with your welcome message. Build it with the message builder, with reply buttons, a list or links with icons.
Powered by MonoChat
The window shows a small Powered by line with the MonoChat logo. It is not a channel setting: it can only be hidden for a whole MonoChat installation.