Install the widget
Add one script to your site. It loads asynchronously and won't block your page.
Copy your snippet from Agents in the app (Copy snippet, or Email install code to send it to whoever edits your website), or from the Install step in Setup. It looks like this:
<script src="https://app.gtmclarity.ai/widget.js?key=YOUR_WIDGET_KEY" data-widget-key="YOUR_WIDGET_KEY" async></script>
Paste it before </body> on every page where the widget should appear.
Trust your domain first
The widget only runs on domains you have trusted. A new account trusts none, so until you add one the widget is blocked on every site and renders nothing.
Add your site under Settings → Domain & branding → Trusted domains. Tick Include its subdomains if the widget should also run on www. and other subdomains. Changes reach the widget within a minute. Loads on untrusted sites are listed under Blocked sites on the same page, so you can spot a domain you forgot.
Tag managers
Using Google Tag Manager or another tag manager? Create a Custom HTML tag containing the snippet, set it to fire on all pages, and publish. The widget key is in the script URL as well as the attribute, so the widget still loads if the tag manager strips attributes.
Options
Each option is a data-widget-* attribute on the script tag, or the same name as a parameter on the script URL. The attribute wins if both are set.
| Attribute | URL parameter | Required | Description |
|---|---|---|---|
data-widget-key | key | yes | Your widget key |
data-widget-position | position | no | right (default) or left. A side set in the agent's widget settings overrides this. |
data-widget-hidden | hidden | no | true to load without showing the launcher |
Open the widget from your own code
The script exposes window.ConvoWidget with open(), close(), toggle(), show() and hide(). With data-widget-hidden="true", call window.ConvoWidget.show() to bring the launcher back, or open() from your own button.
Track opens and chats in your analytics
The widget adds two events to your page's dataLayer, so Google Tag Manager, or any tool that reads it, can pick them up. There is nothing to connect.
| Event | When it fires |
|---|---|
chat_widget_opened | A visitor opens the chat. Each open counts once. The chat reopening by itself on the visitor's next page does not count. |
chat_widget_first_message | The visitor's first message starts a conversation. Once per conversation. |
Both events carry two fields:
opened_by: what opened the chat.launcher(the launcher, or your ownopen()call),eyecatcher,greeting(the proactive greeting) orinvite(an operator's Start chat).widget_key: the widget that sent it, for a site that runs more than one.
To send them to GA4 with Google Tag Manager:
- Add two Data Layer Variables,
opened_byandwidget_key. - Add a Custom Event trigger for each event name.
- Add a Google Analytics: GA4 Event tag for each trigger, with
opened_byandwidget_keyas event parameters. - Publish, open the widget on your site and send a message. Both events show in GA4's DebugView or Realtime.
These names and fields are stable. Build on them rather than on the widget's page elements or messages, which can change.
Verify
Open a page with the snippet. The Install step in Setup shows Installed once the widget has loaded on your site. If it doesn't:
- check that your site's domain is in Trusted domains;
- check that the snippet was pasted whole, including the closing
async></script>.