Google Analytics 4 (GA4)
This guide explains how the Octocom chat widget sends events to Google Tag Manager (GTM) and how you can use them in Google Analytics 4 (GA4) for reporting, funnels, and conversions.
1. How the integration works
When a visitor interacts with the Octocom chat widget, the widget pushes events into window.dataLayer. GTM listens for these events and can:
Forward them to GA4 as events
Trigger other marketing tags (Facebook Pixel, LinkedIn, remarketing, etc.)
All Octocom chat events share a common structure:
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
event: "UserAction",
eventCategory: "Octocom Chat Widget",
eventAction: "Open" // or "Close" / "Send Message"
});2. Prerequisites
Before you start:
A GA4 property is created.
A GTM container is installed on your website.
The Octocom chat widget is installed and active.
Once these are in place, the events below will be available in your dataLayer automatically.
3. Events sent by the chat widget
All events use:
event: UserAction
eventCategory: Octocom Chat Widget
eventAction: one of:
Open
Close
Send Message
eventAction
Description
When it fires
Open
Chat window opened
User clicks the launcher or chat is opened programmatically
Close
Chat window closed
User clicks the close button on the chat window
Send Message
A message is sent via the chat widget
Any user message (first message and all subsequent messages)
3.2 Chat Open
Fired when a visitor opens the chat widget.
dataLayer.push({
event: "UserAction",
eventCategory: "Octocom Chat Widget",
eventAction: "Open"
});Triggers when:
The user clicks the chat launcher button
The chat opens automatically with a pre-filled message
3.3 Chat Close
Fired when a visitor closes the chat widget.
dataLayer.push({
event: "UserAction",
eventCategory: "Octocom Chat Widget",
eventAction: "Close"
});Triggers when:
The user clicks the close button on the chat window
3.4 Send Message
Fired when a visitor sends a message in the chat.
dataLayer.push({
event: "UserAction",
eventCategory: "Octocom Chat Widget",
eventAction: "Send Message"
});Triggers when:
The user sends any message (first and subsequent messages)
4. Configure tracking in Google Tag Manager
4.1 Create a Custom Event trigger
You’ll typically create one trigger per interaction type (Open, Close, Send Message). Example: Trigger for “Chat Open”
In GTM, go to Triggers → New.
Name it: Octocom – Chat Open.
Choose Trigger type: Custom Event.
Event name: UserAction.
Under This trigger fires on, select Some Custom Events and add conditions:
eventCategory equals Octocom Chat Widget
eventAction equals Open
Repeat this pattern for:
Octocom – Chat Close (eventAction = Close)
Octocom – Send Message (eventAction = Send Message)
4.2 Create GA4 Event tags
You can either use one GA4 tag with a variable-based event name, or one tag per event. Below is the “one tag per event” approach. Example: GA4 tag for “chat_open”
Go to Tags → New.
Name it: GA4 – chat_open (Octocom).
Tag type: Google Analytics: GA4 Event.
Choose your GA4 Configuration tag.
Event name: chat_open.
Under Event Parameters, you can pass additional data if desired:
chat_category = Octocom Chat Widget
chat_action = Open
Choose the trigger: Octocom – Chat Open.
Save.
Repeat for:
GA4 – chat_close (Octocom) → event name chat_close, trigger Octocom – Chat Close
GA4 – chat_message_sent (Octocom) → event name chat_message_sent, trigger Octocom – Send Message
5. Using events in GA4
5.1 Track chat engagement
Use chat_open to measure overall engagement.
Example metric: Chat Engagement Rate
= (Chat Opens / Page Views) × 100
Useful views:
Reports → Engagement → Events to see how often chat_open occurs.
Breakdown by page or device.
5.2 Conversation funnel
You can build a simple funnel:
Step 1 – chat_open
Step 2 – chat_message_sent
Step 3 – Your main conversion (purchase, lead submission, etc.)
Insights:
Drop-off between chat_open and chat_message_sent
Percentage of chat users who reach your main conversion
Use Explore → Funnel exploration to visualize this.
5.3 Mark conversions
If you treat “Send Message” as a micro-conversion:
In GA4, go to Configure → Events.
Find chat_message_sent.
Toggle Mark as conversion.
You can also analyze how often your primary conversions happen after users interact with the chat, to attribute downstream conversions to chat-engaged sessions.
5.4 Build custom reports
Examples:
Chat opens by page URL
See which pages drive the most chat interactions.
Messages sent by traffic source
Understand how engaged different channels (e.g. Google Ads, social, email) are with chat.
Chat close rate
Compute chat_close / chat_open to see close behavior.
Use Explore → Free form and add eventName, pageLocation, sessionSourceMedium, etc. as dimensions.
6. Using events for other tags in GTM
You can reuse the same triggers to fire additional tags.
Examples:
Facebook Pixel / Meta
Fire a Lead or custom event when Send Message fires.
LinkedIn Insight Tag
Create a custom conversion when users engage with the chat.
Remarketing tags
Build audiences of users who opened the chat but didn’t send a message.
In each case, choose the relevant trigger:
Octocom – Chat Open
Octocom – Chat Close
Octocom – Send Message
7. Enhanced event tracking (optional)
You can capture extra context by creating GTM Variables and sending them as GA4 parameters (or to other tags), for example:
Page URL where chat was opened (e.g., page_location)
Time of day (via a custom JavaScript variable)
Session duration before chat open (custom logic if needed)
These can be attached as parameters to the GA4 events or used for more granular audience building.
8. Technical notes
Events are pushed automatically to window.dataLayer by the Octocom chat widget.
Requires a working GTM container on the page to consume these events.
A debug mode is available: events are logged to the browser console using internal logging utilities (helpful for verifying event firing during setup).
No additional coding on your side is required for the basic events described in this guide.
Last updated