إنتقل إلى المحتوى الرئيسي

Adding the chat widget to your website

The chat widget lets visitors on your website start a conversation with your workspace — answered by your AI assistant, your agents, or both.

Turn the widget on​

  1. Open Settings → Widget in the admin panel.
  2. Toggle Enable widget on.
  3. (Optional) Set the header name, a welcome message, the accent color, and the default language.
  4. Save.

The widget is off by default, so nothing appears on your site until you enable it.

Copy your install snippet​

On Settings → Widget → Install, you'll find your widget key and a ready-to-paste snippet, for example:

<script async
  src="https://app.example.com/widget.js"
  data-widget-key="YOUR_WIDGET_KEY"
></script>

Copy the snippet exactly as shown in the panel — it already contains your workspace's widget key. If you use Google Tag Manager, pick the Google Tag Manager format instead (see below).

The widget key is a public identifier (like a site ID) — it is safe to put in your page. It only tells the widget which workspace to talk to; it grants no access to your data on its own.

Paste it into your site​

Add the snippet just before the closing </body> tag of every page where you want the widget to appear. It works on any site or platform that lets you insert HTML / a script tag (your CMS, a landing page builder, etc.).

The widget renders inside an isolated Shadow DOM, so your site's CSS can never break it and the widget's styles never leak into your page.

That's it — the chat bubble will appear, and new conversations land in your inbox in real time.

Install with Google Tag Manager​

Google Tag Manager rewrites the script tags you paste into it and removes every data-* attribute — including data-widget-key. With the standard snippet the widget then has no key and silently never appears. Use the Tag Manager format, which carries the key and options in the script address instead:

<script async src="https://app.example.com/widget.js?key=YOUR_WIDGET_KEY"></script>
  1. In Settings → Widget → Install, switch the snippet format to Google Tag Manager and click Copy. Any per-site language, header title or greeting you set is included in the address.
  2. In Google Tag Manager, open your container and go to Tags → New.
  3. Choose the tag type Custom HTML and paste the snippet.
  4. Under Triggering, choose All Pages, then save the tag.
  5. Click Submit, then Publish the container. The widget does not appear on your site until the container is published — saving the tag alone is not enough.

If the widget still doesn't show, open your site with Tag Manager's Preview mode and check that the tag fired, then look at the page source for a widget.js?key= script.

What visitors can and can't do​

  • Visitors chat anonymously — no account or login required. They may optionally share a name and email in the pre-chat form.
  • Each visitor only ever sees their own conversation. They can never see other visitors' chats, your agents' identities, or anything from another workspace.
  • The widget embeds on any site you own and keeps each visitor's session secure with a private, tamper-proof session token.

Rich messaging in the widget​

Visitors can send more than plain text. The widget composer has the same rich controls as your agents' inbox, adapted to its compact size. The message box runs the full width of the chat window, with a round send button at its end; it grows as the visitor types (up to about five lines, then it scrolls). Enter sends and Shift+Enter starts a new line. The action buttons sit in a slim row just above the box:

  • Emoji — the smiley button opens a lightweight, searchable emoji picker with category tabs. The chosen emoji is inserted at the cursor.
  • Files and images — the paperclip button attaches one or more files. Images show an inline preview before sending; other files appear as a chip you can remove. (The widget uses tighter size and count limits than the agent inbox.)
  • Voice messages — the microphone button records a voice note straight from the composer, with an elapsed timer and keep / discard controls. (Browsers that block microphone access simply hide the button.)

Incoming attachments render inline in both directions: an image shows as a picture, an audio or voice message gets an audio player, a video gets a video player, and any other file appears as a download link — so a visitor's photo and an agent's reply with a file both display live in the chat.

Every uploaded file is stored privately, served only through short-lived signed links, and scoped to the visitor's own conversation.

What the widget header says​

The line under the widget's title tells the visitor who is answering:

  • The name of the person handling the chat, once a teammate has taken it.
  • Your AI assistant's name (Settings → Widget), only while the AI actually answers widget chats — AI is in your plan, switched on under Settings → AI with a working key, and the widget's own AI switch is on. If any of these is off, the widget never says "AI Assistant".
  • Your header message, if you set one.
  • Without AI: your team's availability — We're online while at least one agent is available, otherwise We'll get back to you soon.

The Talk to an agent button above the message box follows the same rule: it only appears while the AI is answering. Without AI the visitor is already talking to your team, so there is nothing to hand over.

The shop button​

When you sell through the widget, a shopping-bag button in the composer opens a small counter: what you sell, a basket, Place order and My orders.

Selling in the chat is your choice, and it is off by default. Turn on Show the shop in the widget under Settings → Widget → General. Having priced products in your catalogue — for example products imported from your CRM — does not open a shop on its own. The switch only appears when the Catalogue and Sales features are in your plan.

The button (and with it My orders) appears only when all three are true:

  • Show the shop in the widget is on,
  • the Catalogue and Sales features are in your plan, and
  • at least one catalogue product is active, has a price and currency, and is not hidden from the widget (the item's Visibility switches in Catalogue).

Services and packages are not sold through the widget shop, even when they have a price: they are booked rather than put in a basket.

If nothing is orderable, the widget shows no shop at all — visitors never see an empty "nothing is for sale" panel.

Turning the switch off removes the shop from the widget straight away. It deletes nothing: orders already placed are kept.

AI tools in the widget​

An AI tool profile — for example an Image Studio portrait — can have its own button in the composer: visitors read and accept your consent text, take a photo with their phone's camera or choose one, pick a style, and download the result. It is off by default, profile by profile: turn on Show in the web widget in the profile under Settings → AI → AI tools (see AI tools). You can limit it to some of your sites.

With one profile the button shows that profile's icon and label; with several, a sparkles button opens a list. Nothing is uploaded before the visitor agrees. By default nothing is posted into the chat; turn on Also post the result into the visitor's chat in the profile if you want the result to appear in the visitor's conversation too (your team then sees it in the inbox).

Its look​

Settings → Widget → Appearance → Change the look opens the appearance studio: ready-made templates or your own — launcher, window, header, bubbles, colours, light and dark. A site can wear a template of its own. With a hidden launcher, open the chat from your page with window.cwz.chat.open() or a data-cwz-chat-open button.

Accessibility​

The banner and the chat widget aim for WCAG 2.2 AA: everything works with the keyboard, screen readers hear names, roles and new messages, focus is always visible, both fit a 320-pixel screen, and animations stop for visitors who ask for reduced motion. Every release is tested with axe-core. Our public accessibility statement lists how we test and what is still missing. Styling you add yourself (the widget's custom CSS) is yours to keep accessible.

Tips​

  • Customise the welcome message to set expectations (e.g. "Ask me anything — I usually reply in a few minutes").
  • Match the accent color to your brand.
  • Pair the widget with AI (Settings → AI) so visitors get instant answers even when no agent is online.