> ## Documentation Index
> Fetch the complete documentation index at: https://watermelon.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Event listeners
> When using the Chat Widget with a tag management platform like Google Tag Manager, auto event listeners can capture events fired during chatbot interactions.
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 name | Trigger | **Event Parameters** |
| ------------------------------------ | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| widget\_loaded | Fires when the widget has finished loading on the page. | widget\_platform
widget\_id
timestamp |
| widget\_opened | Fires when a user opens the widget. | widget\_platform
timestamp |
| widget\_closed | Fires when a user closes the widget. | widget\_platform
timestamp |
| widget\_whatsapp\_clicked | Fires when a click on the sitelink containing the **WhatsApp** icon is being registered. | widget\_platform
timestamp
link\_url
link\_type
link\_text |
| widget\_facebook\_clicked | Fires when a click on the sitelink containing the **Facebook** icon is being registered. | widget\_platform
timestamp
link\_url
link\_type
link\_text |
| widget\_instagram\_clicked | Fires when a click on the sitelink containing the **Instagram** icon is being registered. | widget\_platform
timestamp
link\_url
link\_type
link\_text |
| widget\_chat\_clicked | Fires when a click on the sitelink containing the **chat** icon is being registered. | widget\_platform
timestamp
link\_url
link\_type
link\_text |
| widget\_email\_clicked | Fires when a click on the sitelink containing the **email** icon is being registered. | widget\_platform
timestamp
link\_url
link\_type
link\_text |
| widget\_phone\_clicked | Fires 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\_clicked | Fires 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\_started | Website visitor sends first message | widget\_platform
timestamp |
| widget\_message\_sent | Website visitor sends a message | widget\_platform
widet\_conversation\_id
timestamp
total\_messages |
| widget\_agent\_message\_sent | AI agent sends message | widget\_platform
widet\_conversation\_id
timestamp
total\_messages |
| widget\_handoff\_requested | Website visitor requests human handover | widget\_platform
widet\_conversation\_id
timestamp
total\_messages |
| widget\_user\_joined | Human agent joins conversation | widget\_platform
widet\_conversation\_id
timestamp
total\_messages |
| widget\_user\_left | Human agent leaves conversation | widget\_platform
widet\_conversation\_id
timestamp
total\_messages |
| widget\_handover\_agent | Conversation is assigned back to the AI Agent | widget\_platform
widet\_conversation\_id
timestamp
total\_messages |
| widget\_user\_typing | Human agent typing | widget\_platform
widet\_conversation\_id
timestamp
total\_messages |
| widget\_message\_user\_sent | Human agent sends message | widget\_platform
widet\_conversation\_id
timestamp
total\_messages |
| widget\_start\_conversation\_clicked | Conversation started | widget\_platform
widet\_conversation\_id
timestamp
total\_messages |
| widget\_conversation\_archived | Conversation archived | widget\_platform
widet\_conversation\_id
timestamp
total\_messages |
| widget\_conversation\_deleted | Conversation deleted | widget\_platform
widet\_conversation\_id
timestamp
total\_messages |
| widget\_gdpr\_accepted | Website visitor accepts GDPR | widget\_platform
timestamp |
| widget\_gdpr\_declined | Website visitor declines GDPR | widget\_platform
timestamp |
| widget\_feedback\_submitted | Website visitor gives feedback to a message | widget\_platform
widet\_conversation\_id
timestamp
agent\_name |
## **Tracking Events in GA4 from the Widget with Google Tag Manager**
Install the website widget code [using this guide](/help-center/developer-resources/install-widget)
Log in to Google Tag Manager.
The widget pushes events into the browser’s dataLayer.
**To verify this:**
1. Open your website with **GTM Preview Mode** enabled.
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.
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.
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
```
Attach the **Custom Event Trigger** you created earlier and click **save**.
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.
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**
3. 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
2. Facebook ads
3. LinkedIn ads
4. 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.
*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.**
* Choose**Data Layer Variable** .
* Enter the datalayer variable name, for example: **widget\_id.**
* Find these in the datalayer → same as event testing in GTM preview:
* It should look like this:
* Save.
* Make all the other variables you need to measure, for example:
* Add the individual Datalayer Variables to your Analytics tag, for example GA4:
