Skip to main content

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.

AttributeURL parameterRequiredDescription
data-widget-keykeyyesYour widget key
data-widget-positionpositionnoright (default) or left. A side set in the agent's widget settings overrides this.
data-widget-hiddenhiddennotrue 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.

EventWhen it fires
chat_widget_openedA 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_messageThe 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 own open() call), eyecatcher, greeting (the proactive greeting) or invite (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:

  1. Add two Data Layer Variables, opened_by and widget_key.
  2. Add a Custom Event trigger for each event name.
  3. Add a Google Analytics: GA4 Event tag for each trigger, with opened_by and widget_key as event parameters.
  4. 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>.