Widget Embed

Add the widget loader to the host site where you want GTM Clarity chat to appear.

Install the script

Copy the snippet from the dashboard onboarding Install step. It includes your widget key.

<script src="https://app.gtmclarity.ai/widget.js" data-widget-key="wk_..." async></script>

The loader is idempotent per page load. If the script runs again on the same page, it no-ops.

Configure the loader

The script supports these attributes:

Example with the launcher on the left:

<script
  src="https://app.gtmclarity.ai/widget.js"
  data-widget-key="wk_..."
  data-widget-position="left"
  async
></script>

Example hidden on initial load:

<script
  src="https://app.gtmclarity.ai/widget.js"
  data-widget-key="wk_..."
  data-widget-hidden="true"
  async
></script>

How the loader resolves URLs

The loader resolves its API origin from its own script src, so it works on custom domains. It injects a launcher button and an iframe that points at /embed/<widgetKey>.

The launcher color comes from GET /api/widget-config?widgetKey=..., which is CORS-open. When brandColor is returned, the launcher repaints. If that fetch fails or no color is available, the launcher silently falls back to the default green #3a7d5c.

Use the JavaScript API

After the loader runs, it exposes:

window.ConvoWidget = {
  open,
  close,
  toggle,
  show,
  hide,
};

You can suppress the launcher until your own UI is ready, then show and open the widget:

<button type="button" onclick="window.ConvoWidget.show(); window.ConvoWidget.open();">
  Chat with us
</button>

Handle SPAs

The loader binds once per page load. Client-side route changes keep the widget alive, so no re-initialization is needed. If your framework hard-remounts the document, the script re-runs safely.

Configure CSP

If the host site sets a Content-Security-Policy, allow GTM Clarity in these directives:

Content-Security-Policy:
  script-src https://app.gtmclarity.ai;
  frame-src https://app.gtmclarity.ai;
  connect-src https://app.gtmclarity.ai;

connect-src is required for the widget-config fetch.