Skip to main content
Whenever a visitor performs an action inside the widget, an event is triggered. These events are sent directly from the widget and can be listened to by any tool running on your website. Examples of actions that trigger events include:
  • Opening, loading and closing the widget.
  • Sending, receiving messages for both the AI Agent, end user and Human Agent.
  • Outbound Clicks.
No configuration is needed—the chatbot automatically sends events to the data layer.

​
Available events

Event nameTriggerEvent Parameters
widget_loadedFires when the widget has finished loading on the page.widget_platform
widget_id
timestamp
widget_openedFires when a user opens the widget.widget_platform
timestamp
widget_closedFires when a user closes the widget.widget_platform
timestamp
widget_whatsapp_clickedFires when a click on the sitelink containing the WhatsApp icon is being registered.widget_platform
timestamp
link_url
link_type
link_text
widget_facebook_clickedFires when a click on the sitelink containing the Facebook icon is being registered.widget_platform
timestamp
link_url
link_type
link_text
widget_instagram_clickedFires when a click on the sitelink containing the Instagram icon is being registered.widget_platform
timestamp
link_url
link_type
link_text
widget_chat_clickedFires when a click on the sitelink containing the chat icon is being registered.widget_platform
timestamp
link_url
link_type
link_text
widget_email_clickedFires when a click on the sitelink containing the email icon is being registered.widget_platform
timestamp
link_url
link_type
link_text
widget_phone_clickedFires when a click on the sitelink containing the phone icon is being registered.widget_platform
timestamp
link_url
link_type
link_text
widget_custom_link_clickedFires when a click on a sitelink containing a custom link icon is being registered.widget_platform
timestamp
link_url
link_type
link_text
widget_conversation_startedWebsite visitor sends first messagewidget_platform
timestamp
widget_message_sentWebsite visitor sends a messagewidget_platform
widet_conversation_id
timestamp
total_messages
widget_agent_message_sentAI agent sends messagewidget_platform
widet_conversation_id
timestamp
total_messages
widget_handoff_requestedWebsite visitor requests human handoverwidget_platform
widet_conversation_id
timestamp
total_messages
widget_user_joinedHuman agent joins conversationwidget_platform
widet_conversation_id
timestamp
total_messages
widget_user_leftHuman agent leaves conversationwidget_platform
widet_conversation_id
timestamp
total_messages
widget_handover_agentConversation is assigned back to the AI Agentwidget_platform
widet_conversation_id
timestamp
total_messages
widget_user_typingHuman agent typingwidget_platform
widet_conversation_id
timestamp
total_messages
widget_message_user_sentHuman agent sends messagewidget_platform
widet_conversation_id
timestamp
total_messages
widget_start_conversation_clickedConversation startedwidget_platform
widet_conversation_id
timestamp
total_messages
widget_conversation_archivedConversation archivedwidget_platform
widet_conversation_id
timestamp
total_messages
widget_conversation_deletedConversation deletedwidget_platform
widet_conversation_id
timestamp
total_messages
widget_gdpr_acceptedWebsite visitor accepts GDPRwidget_platform
timestamp
widget_gdpr_declinedWebsite visitor declines GDPRwidget_platform
timestamp
widget_feedback_submittedWebsite visitor gives feedback to a messagewidget_platform
widet_conversation_id
timestamp
agent_name

​
Tracking Events in GA4 from the Widget with Google Tag Manager

1

Install the widget

Install the website widget code using this guide
2

Go to Google Tag Manager

Log in to Google Tag Manager.
3

Check that events reach the dataLayer

The widget pushes events into the browser’s dataLayer.To verify this:
  1. Open your website with GTM Preview Mode enabled.
    Prevew Url Entry Pn
  2. Interact with the widget (fire an event).
  3. In the left panel, you should see event names appear under the “Events” section.
If you see them, you’re ready to track them.
4

Create a GTM Trigger for a Widget Event

You can set up triggers in two ways, depending on your tracking needs:Option 1: Individual Triggers (One trigger per Event).
  1. In GTM, go to Triggers → New.
  2. Choose Custom Event.
  3. Enter the event name, for example: widget_conversation_started.
  4. Set This trigger fires on: All Custom Events.
  5. Save.
**Option 2: **RegEx Trigger (Catch multiple Events in one trigger).
  1. In GTM, go to Triggers → New.
  2. Choose Custom Event.
  3. Select Use regex matching.
  4. Enter a pattern to match multiple events:
    1. ^widget_.* catches all widget events;
    2. ^widget_.*_clicked$ catches all click events only;
    3. ^widget_(opened|closed|loaded)$ catches specific event groups.
  5. Set This trigger fires on: All Custom Events.
  6. Save.
5

Create a GA4 Event Tag

To send the captured widget event to Google Analytics:
  1. Go to Tags → New.
  2. Choose Google Analytics: GA4 Event.
  3. Select your GA4 Configuration Tag.
  4. Under Event Name, use the same event name from the widget, for example:
chat_widget_whatsapp_clicked
6

Connect events

Attach the Custom Event Trigger you created earlier and click save.
7

Verify events

After publishing, test your events using DebugView:
  1. Go to GA4 → Admin (gear icon, bottom left) → Data Display → DebugView;
  2. Trigger widget events on your site, using PreviewMode in GTM;
  3. Events should appear as blue hits in real-time.
Gtm Debug View Pn
The page_view is a normal hit, while the chat_widget_.* events are Key Events

​
Create Key Events (optional)

  1. Go to GA4 → Admin → Data Display → Events
  2. Click Create Key Event
Gtm Key Event Setup Pn
  1. Add the widget event, with the exact event name, to convert it from a regular hit (blue ball) to a key event (green ball) in DebugView.
Events will also appear under Reports → Engagement → Events over time.

​
Use events across multiple platforms

The widget events aren’t limited to GA4. The Custom Event triggers, made in point 5 can be used to fire all other conversion and event tags:
  1. Google ads
Gtm Fb Pn
  1. Facebook ads
Gtm Fb Pn
  1. LinkedIn ads
Gtm Ga4 Pn
  1. Any other tag-based platform
This allows you to track widget interactions as conversions across your entire marketing stack from a single implementation.

​
How to use the Event Parameters

Each Widget Event has dedicated, built in Event Parameters, add them  to all you analytics platform tags, like GA4, Matomo or HubSpot.
Gtm Event Paramaters Pn
Conversion based tags (E.g. Google Ads, LinkedIn Ads, Microsoft UET Ads) do not benefit nor optimize using this information.
Before you can add them to your tags, you have to make the datalayer Variables:
  • In GTM, go to Variables → New.
  • ChooseData Layer Variable .
  • Enter the datalayer variable name, for example: widget_id.
    • Find these in the datalayer → same as event testing in GTM preview:
      Gtm Preview Ep Pn
    • It should look like this:
      Gtm Example Vc Pn
    • Save.
    • Make all the other variables you need to measure, for example:
      Gtm Example Ep Pn
    • Add the individual Datalayer Variables to your Analytics tag, for example GA4:
      Gtm Analytics Tag Pn