Setting Up the Web Chat Widget

Overview

The web chat widget is a lightweight, embeddable chat window that your website visitors can use to start conversations with your support team (and AI).

Setup steps

1. Go to Projects → your project → Channels
2. Create a new Web Chat channel
3. Set the colours and wording under Appearance, and the pre-chat form under Home screen & chat flow
4. Optional: to keep the widget on your own website only, add its address under URLs & domains → Allowed Origins
5. Copy the embed code snippet
6. Paste it into your website's HTML, just before the closing </body> tag

If Allowed Origins is empty, the widget works on any website you paste it into. Add an address and it becomes a strict list: the widget then works only on the addresses listed, so nobody else can put your chat on their pages. Enter the full address including https://, and press Add — typing alone does not add it. Add www and non-www separately if your site answers on both, or the widget will not load on the one you left out.

Embed code

The embed code looks like this:

<script async src="https://chatonio.com/widget/loader.js" data-channel-id="YOUR-CHANNEL-ID"></script>

You never have to fill in YOUR-CHANNEL-ID yourself. The snippet on the channel page already carries your channel's id — copy it as it is.

Running the widget inside your own app

If your mobile or desktop app shows your website inside a built-in browser (a WebView), you can tell Chatonio so. Visitors then appear under your app’s name in Live visitors, on the conversation’s visitor panel and in the Apps tab of Insights, instead of as an ordinary browser. Add data-app (and, optionally, data-app-version) to the embed snippet on the pages your app opens:

<script async src="https://chatonio.com/widget/loader.js" data-channel-id="YOUR-CHANNEL-ID" data-app="Acme iOS" data-app-version="2.4.1"></script>

Add these attributes only when the page is actually running inside your app — for example, have your app add a marker to its user agent or to the address it opens, and include the attributes when you see it. Once a visitor has been identified as being in your app, their later pages keep that label even if one of them leaves the attributes out.

Well-known in-app browsers need nothing from you: Chatonio recognises Instagram, Facebook, Messenger, TikTok, Telegram, WeChat, VK, the Google and Yandex apps and others automatically, and shows any other built-in browser as Other app.

Customization

You can customize the widget's appearance from the channel settings:

• Widget Color — the launcher and chat header colour
• Greeting Message — shown when the widget opens
• Pre-Chat Form — collect visitor name and/or email before chatting
• Launcher corner and Chat window corner — which corner the button sits in, and separately which corner the chat window opens in

Each section of the channel settings page shows its everyday settings first and keeps the rest behind an Advanced settings link. Click it to reach things like the corner and screen offsets, light/dark colour mode, the notification sound, the Chatonio badge, and the page rules that decide where the widget is allowed to appear. When an Advanced link shows a number, that many settings inside it differ from their defaults — so nothing you have configured is ever hidden without a hint.

The widget is fully responsive and works on mobile devices.

Appearance

How the widget looks is set per channel, on the Web channel settings page: Project settings → Channels → your Web channel. Two sections there control it. Appearance is expanded when the page loads and holds the colours and the wording of the chat window. Launcher is collapsed until you click it, and holds everything about the button in the corner. One Save changes button at the bottom of the page commits the whole form.

Choosing a launcher

Open the Launcher section. There are two separate choices: the shape of the button, and what sits inside it.

Launcher style is the shape:

• AI Orb — an animated sphere in your brand colour.
• Bubble — the round button most sites use.
• Pill — a rounded button with a text label next to the icon.
• Square — a rounded square.
• Avatar — a circle showing your AI avatar image, with a small presence dot.
• Side tab — a tab flush against the left or right edge of the window.
• Your logo — a circle showing an image you upload for this channel.
• No launcher — no button at all. See "No launcher" is not the same as hiding the widget on a page below.

What's inside is the icon or image: Chat, Sparkle, Headset, Dots, AI avatar, Project logo or Custom image. The last three need an image to exist first and stay greyed out until it does. The AI avatar is uploaded on the project Members page and the project logo under Workspace → Appearance; the custom launcher image has its own upload box in the Launcher section, which appears once you pick the Your logo frame or the Custom image face. It saves as soon as you choose the file rather than waiting for Save changes. Use a PNG or JPG up to 2 MB; square images work best. Anything larger than 256 pixels on its longest side is scaled down to fit, and smaller images are left as they are.

Picking Avatar or Your logo also pre-selects the matching image for you — provided that image already exists, and only while What's inside is still on Chat. A face you chose yourself is never overwritten, and a frame whose image is missing stays on the chat icon until you upload one.

Size offers Small, Medium (the default) and Large — 46, 54 and 66 pixels. Everything stacked above the button moves with it, including the collapsed message teaser and the chat window.

Options that appear for one style

With AI Orb selected, an Orb style row appears with three treatments: Aurora ring (a light ring orbiting just outside a glossy sphere), Liquid core (two soft shapes drifting inside the glass at different speeds) and Glass marble (a blurred swirl behind heavy glass with a hard specular edge). Only Aurora ring draws the orbiting outer ring. All of the motion runs continuously, and all of it is switched off for visitors whose device asks for reduced motion. The widget is also hidden when a page is printed.

With Side tab selected, a Tab placement row appears: Top, Middle (the default) or Bottom. The tab sits flush against the edge of the window, so the horizontal offset has nothing to act on and is ignored — the page shows a note to that effect. The vertical offset applies to the Top and Bottom placements as the distance from that edge. Middle is centred and ignores both offsets for the tab itself — on that placement they position the chat window and the message teaser instead. On screens 480 pixels wide and under, the side tab becomes a round button back in the corner and its label is hidden.

Launcher text appears for Pill and Side tab only, and shows only while the chat is closed. When a label is set it becomes the button's accessible name in place of "Open chat". Per-language versions of the label are edited in the Languages & translations section, not here.

Position

Under Advanced settings in the Launcher section: Launcher corner (Bottom right or Bottom left), Horizontal Offset (px) and Vertical Offset (px). These move the button and anything stacked on it. The chat window has its own Chat window corner and offsets under Advanced settings in the Appearance section; left as they are, the window follows the launcher.

Except for No launcher, which never draws a button at all, every style collapses back to a plain circle with a close icon while the chat is open, and shows the unread badge on the closed button — counting up to 9+.

The AI Orb is the default for new channels only

Web channels created since the orb shipped start on AI Orb. Existing channels were not touched. A channel set up before then still resolves to Bubble — or to Pill if it has launcher text, so a pill you configured earlier stays a pill. No live widget changed appearance on the day this shipped, and none will until someone selects a different style on this page.

"No launcher" is not the same as hiding the widget on a page

These two settings look similar and behave very differently.

• Launcher style: No launcher — the widget still loads and connects normally. Only the corner button is absent. Proactive greetings and previews of new messages still appear above the corner and still open the chat when clicked. Something on your page opens it the rest of the time; see the next section.
• Excluding a page under URLs & domains (in that section's Advanced settings) — the widget never loads on that page at all. Nothing on the page can open it, and your own button will do nothing.

If a page ends up with no launcher and no trigger of any kind, the widget writes a single message to the browser console after about three seconds naming both possible fixes. If your own button does nothing, the console usually says which of the two cases you are in. Silence from the console with no response at all points elsewhere — most often a channel that is not currently active.

In the operator's own Test Widget preview, No launcher is shown as a bubble so the preview does not look broken.

Opening the chat from your own button

Three ways, all of which work with any launcher style and are most useful with No launcher:

• Add data-chatonio to any element. On its own it opens the chat; you can also set it to open, close or toggle.
• Link to #chatonio, or to #chatonio-open, #chatonio-close, #chatonio-toggle.
• Call chatonio('open'), chatonio('close') or chatonio('toggle') from your own code.

<button data-chatonio>Chat with us</button>
<a href="#chatonio">Chat with us</a>

Before calling chatonio(...) from your own JavaScript, add this line above the embed snippet, because the widget script loads asynchronously and the function does not exist until it has run:

<script>window.chatonio = window.chatonio || function(){ (chatonio.q = chatonio.q || []).push(arguments) }</script>

A click or a call made before the widget has finished loading is held and replayed once it is ready, so a button clicked immediately still works; if several arrive first, the most recent one wins. Triggers are matched on the page as a whole, so a button rendered later by a menu, a CMS block or a single-page app needs no extra setup. Ordinary link behaviour is left alone: Cmd-click or Ctrl-click on <a href="#chatonio"> still opens a browser tab. If a proactive greeting is waiting, opening the chat this way engages it rather than discarding it.

Starting the conversation with a message

A button can also bring a message with it, so a visitor who clicks "Get a quote" lands in the chat already asking about a quote. Add data-chatonio-message to the element. What happens next depends on the value of data-chatonio:

• Fill in the message — data-chatonio on its own, or open. The chat opens with your text already in the message box. The visitor can change it, and nothing is sent until they press Send.
• Send the message — data-chatonio="send". The chat opens and the message is sent straight away, as if the visitor had typed it, and the assistant starts answering.

<button data-chatonio data-chatonio-message="I'd like a quote for 50 seats">Get a quote</button>
<button data-chatonio="send" data-chatonio-message="Do you integrate with Telegram?">Ask about Telegram</button>

The same works from your own code: chatonio('open', 'your text') fills the message in, and chatonio('send', 'your text') sends it.

Good to know:

• The pre-chat form still comes first. If your channel asks for a name, email or other details before chatting, a visitor who hasn't given them yet sees the form first, with the message that is about to be sent shown above it. The message goes out as soon as they submit the form. Visitors who already filled the form in are not asked again.
• Clicking twice doesn't send twice. If the visitor's last message already says the same thing, the button just opens the chat.
• Your team can tell. In the inbox, a message sent by a button is marked Sent by a button on your site, so nobody mistakes it for something the visitor typed. To tell your buttons apart, give each one a label: data-chatonio-ref="pricing-page", or chatonio('send', 'your text', { ref: 'pricing-page' }). The label appears next to the mark; visitors never see it.
• If the visitor's previous conversation has ended, a send button starts a new one.
• A message can be up to 4,096 characters. A send button without a message simply opens the chat.

Use send for clear one-click questions, and the fill-in version when the visitor will probably want to add something, such as an order number. A short reminder of all this sits on your web chat channel's page, under Open the chat from your own buttons.

Light and dark mode

Color mode is in the Appearance section, under Advanced settings. It has three values: Light, Dark and Match the website.

Every channel defaults to Light — both channels created before this shipped and channels created since. No visitor sees a different widget until you change this setting, and the light palette is unchanged from before the feature. The widget now also tells the browser which scheme it is using, so native scrollbars, form fields and autofill inside the chat match the mode instead of being left to the visitor's device.

How "Match the website" decides

It reads your page first, and falls back to the visitor's system setting only when the page says nothing at all. In order:

• A theme declared on <html> or <body>: data-theme, data-color-mode, data-bs-theme or data-color-scheme set to dark or light, or a dark, dark-mode or theme-dark class (and the light equivalents). This is honoured in both directions, so a page that declares light stays light even when the visitor's device is set to dark.
• A CSS color-scheme declaration. color-scheme: dark and color-scheme: only dark both decide; color-scheme: light dark is not a decision and falls through to the next step.
• The page background — the first non-transparent background found on <body>, then <html>. A dark background means dark.
• Only if none of the above applies: the visitor's system setting.

Because almost every real page paints a solid background, the third step usually decides and the system setting is never reached. A white page opens a light widget even for a visitor whose device is in dark mode; that is intended, since a dark widget on a light page reads as broken. Values are matched narrowly, so data-theme="midnight" or data-theme="corporate-dark" is not recognised as a signal and falls through.

The mode is re-checked live. A theme switcher on your own site flips the widget with it, and a change to the visitor's system preference is picked up, with no page reload. If your page wraps light content in a dark shell, the background check can read dark; declare data-theme on <html> to settle it.

The brand colour in dark mode

Brand color (dark) appears in the same Advanced settings block once Color mode is set to Dark or Match the website. Left blank, the widget derives one from your Widget Color: a colour that is genuinely deep is lightened while keeping its hue, and a colour that is already mid-range or bright is used unchanged. A bright blue or green brand therefore looks identical in both modes — that is the expected result, not a fault. If you set a value it has to be a hex colour; anything else is ignored and the derived colour is used. This colour also drives the two shades of the AI Orb, which are recalculated whenever the mode flips.

Overriding the mode from your own site

Two escape hatches, both of which take precedence over the channel setting.

Add data-theme to the embed script. It accepts light, dark or auto:

<script async src="https://chatonio.com/widget/loader.js"
        data-channel-id="YOUR-CHANNEL-ID"
        data-theme="dark"></script>

The attribute is read once when the widget loads, so changing it later has no effect, and if a page carries more than one embed snippet only the last one is read.

Or call chatonio('theme', 'dark') — also 'light' or 'auto' — which repaints straight away. With the initialiser line above in place, a call made before the widget mounts is honoured on the first paint, so there is no flash of the wrong theme. An unrecognised value is ignored with a console message and does not clear an override you set earlier; calling with 'auto' is the only way back to page detection for the rest of that page view.

Under Match the website you can also steer the widget purely from your own markup, by declaring one of the attributes or classes listed above on <html> or <body>. That is what lets a site's own theme switcher drive the widget with no JavaScript integration.

Popups and the captcha panel

On-site popups follow the same colour mode, and so does the captcha panel when one is shown. Any colour you set on a popup campaign is kept in both modes, so a fully designed campaign looks the same in dark mode and only the parts you left unset change. On a page where the widget is excluded by your domain or URL rules, popups still run but always render in light, because the mode is decided by the widget that never loads there.

Speaking your visitors' language

The widget adapts to each visitor automatically. When someone opens the chat, Chatonio shows it in your page's language — it reads the page's standard <html lang> attribute, so a visitor browsing the Russian version of your site sees a Russian widget even if their browser is set to another language. The title, subtitle, greeting, offline message and launcher text you set, your AI assistant's display name, and your help center (knowledge base and FAQ) articles all appear in that language whenever a version exists. If the page doesn't declare a language, the widget falls back to the visitor's browser language.

The widget's own buttons and labels ship in English, Russian and Ukrainian, but everything you and your AI write can be offered in as many languages as you translate. The language a visitor sees before typing follows the page (with the browser as a fallback); once they start writing, the AI simply replies in whatever language they actually use — its first reply follows the page language too.

Adding your own translations

On the Web channel settings page, open the Languages & translations section and find the Text translations block. Pick a language from Add language — a tab appears for it, holding the five visitor-facing strings: Title, Subtitle, Greeting Message, Offline Message and Launcher text. Leave a field empty and it falls back to your channel's default-language wording. Add as many languages as you like; each gets its own tab. To make your knowledge base and FAQ appear in another language, add translations to those articles as usual — the widget picks them up automatically.

Forcing a specific language

If your site doesn't set the standard <html lang> attribute — or you want a specific embed to always use one language — add a data-lang attribute to the embed snippet. Its value takes priority over automatic detection:

<script async src="https://chatonio.com/widget/loader.js" data-channel-id="YOUR-CHANNEL-ID" data-lang="ru"></script>

Custom pre-chat fields

The pre-chat form is not limited to name and email. In the Web channel settings, open Home screen & chat flow and look under Pre-Chat Form for Custom fields, where you can add your own fields — short text, email, phone, a longer message, a dropdown, or a checkbox — and mark any of them as required. Whatever visitors enter is saved with their contact and shown to your operators in the info panel next to the chat. Where each answer goes, and how (and when) it can be used for marketing emails, is explained in Collecting names, emails and other details in web chat.

Reaching out first

The same widget can also greet visitors on its own. In the Marketing area you can set up proactive messages — an automatic chat greeting that appears after a visitor has spent time on your site, opens a specific page, or is about to leave — as well as on-site popups and banners. A proactive greeting opens straight into a real conversation your AI handles, so nobody is left waiting. Proactive messages are available on the Advanced, Pro and Ultimate plans, popups on Pro and Ultimate. See Proactive chat messages.