Widget Tracking Analytics (GTM / GA4 / Meta)

Use this guide to connect Chat Widget Tracking events to your analytics stack.

Scope

Chat Widget Tracking applies only to conversations from the embedded web chat widget.

It does not apply to SMS, email, voice, or websocket-only dashboard flows.

Browser event contract

For each tracking outcome, the widget dispatches two CustomEvents on window:

1. Stable event name: autochat.widget_tracking.v1
2. Canonical alias event name: <event_type> (for example autochat.lead_qualified.v1)

event.detail shape:

{
  scope: 'chat_widget_tracking';
  event_id: string;
  event_type: string;
  occurred_at: string;
  conversation_id: string;
  session_id?: string | null;
  trigger_source: string;
  data: Record<string, unknown>; // redacted payload only
  dispatch_version: 1;
}

Privacy model

Transported data is redacted-only in v1.

Tenant organizations remain responsible for their own legal/privacy policies and any downstream analytics processing.

Quick listener test

<script>
  window.addEventListener('autochat.widget_tracking.v1', (event) => {
    console.log('Widget tracking event', event.detail);
  });
</script>

If no logs appear, review troubleshooting at the bottom of this page and in Live Chat Troubleshooting.

GTM setup

1) Trigger

Create a Custom Event trigger with event name:

• autochat.widget_tracking.v1

2) Variables (Data Layer Variable type)

Map from event detail:

• event.detail.event_type
• event.detail.event_id
• event.detail.trigger_source
• event.detail.conversation_id

3) Tag routing options

1. Single tag keyed by event_type parameter.
2. One tag per canonical alias event type.

GA4 mapping recipe

Recommended GA4 event name:

• chat_widget_tracking

Recommended params:

• autochat_event_type = event.detail.event_type
• autochat_event_id = event.detail.event_id
• autochat_trigger_source = event.detail.trigger_source
• autochat_scope = event.detail.scope

Optional: include selected redacted values from event.detail.data.

Meta Pixel mapping recipe

Recommended options:

1. Send a custom event:
   • fbq('trackCustom', 'AutochatWidgetTracking', { ... })
2. Map selected canonical types to standard events when policy allows.

Example bridge:

<script>
  window.addEventListener('autochat.widget_tracking.v1', (event) => {
    const d = event.detail || {};
    if (!window.fbq) return;
    window.fbq('trackCustom', 'AutochatWidgetTracking', {
      autochat_event_type: d.event_type,
      autochat_event_id: d.event_id,
      autochat_trigger_source: d.trigger_source,
    });
  });
</script>

Tracking code templates in app

Open Settings → Chat Widget → Tracking (/settings/widget?tab=tracking) for copyable host-page templates:

• Guided Snippet Builder (provider/event selection + preview + copy)
• stable listener (autochat.widget_tracking.v1)
• canonical alias listener (autochat.goal_met.v1 example)
• GA4 gtag bridge (event_id included)
• Meta fbq bridge (event_id included)
• optional dataLayer push template

Rollout behavior:

• Guided Snippet Builder is available to all tenants. The Grain flag widget_tracking_snippet_builder_enabled defaults to true (fail-open) and can be set to false to disable if needed.
• Static templates remain available regardless of builder gate state.
• If snippet preset metadata is unavailable, UI uses built-in deterministic defaults and displays a fallback notice.

Canonical event types

• autochat.contact_info_obtained.v1
• autochat.lead_qualified.v1
• autochat.escalation_triggered.v1
• autochat.followup_scheduled.v1
• autochat.followup_inferred.v1 (allowlisted; may not be emitted yet)
• autochat.appointment_scheduled.v1
• autochat.goal_met.v1

Debug checklist

1. Confirm widget endpoint responses include a tracking block.
2. Confirm browser receives autochat.widget_tracking.v1 events.
3. Confirm GTM trigger fires on autochat.widget_tracking.v1.
4. Confirm mapped GA4/Meta tags fire in preview/debug tools.
5. If duplicates appear, verify event IDs in your downstream tool.
6. If missing events, confirm mapping emit_browser=true in Widget Tracking settings.

Operational health

Use Settings → Chat Widget → Tracking → Widget Tracking Health to monitor:

• emission volume
• webhook attempts/failures
• per-event-type delivery quality
• recent redacted failures