B Blengi docs
/

Embed the widget

Events for GA4 & Tag Manager

The chat can report what visitors do inside it to the analytics you already run — Google Tag Manager, a direct GA4 tag, or anything else listening for browser events. Turn it on per agent under Advanced › Tracking events of the AI employee; it is off until you do.

How the events arrive

The widget runs inside your page, not in an iframe, so it hands events straight to whatever your site already loads. Three destinations, each independent — a broken one cannot stop the others, and none of them can break the chat:

  • window.dataLayer — Google Tag Manager. This is the one most sites want: build the GA4 event, the conversion and the funnel in GTM without touching code.
  • window.gtag — a direct GA4 tag with no tag manager in between.
  • A DOM event on window, always, with the same name. Use it for Plausible, Matomo, or your own listener: window.addEventListener('blengi_chat_started', e => console.log(e.detail)).

The events

Each name is prefixed with the value you set (default blengi_) so one GTM trigger can select all of them.

EventFires when
chat_openedThe chat panel opens, however it was opened.
chat_startedThe visitor's first message of a conversation — the moment a passer-by became a conversation.
message_sentEvery visitor message, including the first. Use it for conversation depth.
cta_clickedA call-to-action button in the chat is clicked.
product_clickedA product card's link is followed.
lead_form_openedThe lead form appears, from any of its triggers.
lead_form_submittedThe lead was accepted by the server — not merely that Send was pressed.
human_takeover_requestedThe visitor asked for a person. Fires on the request, whether or not anyone picks up: what a funnel wants to show is how often the AI ran out of road.

Parameters

Every event carries agent_id, agent_name, page_url and page_path — the page read at the moment the event fires, so a single-page app that navigates under the widget still reports the right one. On top of that:

  • chat_started, message_sent, human_takeover_requested — conversation_id.
  • message_sent — message_length, a character count. Never the message.
  • cta_clicked — cta_label, cta_type, cta_url.
  • product_clicked — product_title, product_url.
  • lead_form_submitted — fields_submitted, a count of the fields filled in.

What is never sent

No personal data leaves the page
No message text, no lead-form answers, no name, email or phone number — only that an event happened and what type it was. This is not a setting you can loosen. Google's own terms forbid personal data in GA4, and a customer who pastes our snippet must not be the one who breaks that rule.

Consent

Consent is deliberately not our decision. We push into the page's own tag layer, and your existing cookie banner — Google Consent Mode, or whatever your site runs — decides whether anything is sent onward, exactly as it does for every other tag on the page. Holding a second, competing consent state inside the chat would be one you could neither see nor audit, and it would disagree with your banner sooner or later.

Setting it up in Tag Manager

  1. Switch on Advanced › Tracking events for the agent, and note the prefix.
  2. In GTM, create a Custom Event trigger. To catch everything at once, set the event name to blengi_.* and tick use regex matching.
  3. Add a GA4 Event tag on that trigger, with the event name set to {{Event}}.
  4. For each parameter you want in GA4, add a Data Layer Variable (agent_name, cta_type, and so on) and map it in the tag's event-parameter list.
  5. Preview, open the chat on your site, and confirm the events appear. Then mark the ones that matter — usually lead_form_submitted — as conversions in GA4.

The same steps are on the Tracking events page itself, filled in with the AI employee's own prefix (card #679).

A quick check without GTM: open the browser console on your site and run window.addEventListener('blengi_chat_opened', e => console.log(e.detail)), then open the chat.

Nothing shows up in GA4?

Work through these in order — the first one is by far the most common.

  1. No trigger for the events in your container. Switching tracking on hands every event to Tag Manager; Tag Manager forwards nothing it has no trigger and GA4 tag for. This was the whole problem on a live customer site: their container forwarded two event names of its own to GA4 and dropped every chat event. Add the trigger and tag above, then publish — a saved but unpublished workspace changes nothing on the site.
  2. Testing with an automated browser. GA4 filters known bot traffic, and many containers block their tags for automated browsers outright. Test by hand, in Tag Manager's Preview (the events appear in its event list) or GA4's DebugView.
  3. Consent. The events go through your own consent setup, exactly like the rest of your site's tags: with analytics consent refused, GA4 sends at most cookieless pings (Consent Mode) or nothing at all.
  4. GA4's processing delay. Standard reports can take a day; Realtime and DebugView show events within a minute.

A site whose GA4 tag is placed directly in the page (gtag.js, no tag manager) receives the events without any of this: the widget calls gtag('event', …) itself. When GA4 runs inside Tag Manager — including through a server-side container — a gtag command from the page is not forwarded either; only a trigger and GA4 tag in the container are.