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”

1. In GTM, go to Triggers → New.

2. Name it: Octocom – Chat Open.

3. Choose Trigger type: Custom Event.

4. Event name: UserAction.

5. 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”

1. Go to Tags → New.

2. Name it: GA4 – chat_open (Octocom).

3. Tag type: Google Analytics: GA4 Event.

4. Choose your GA4 Configuration tag.

5. Event name: chat_open.

6. Under Event Parameters, you can pass additional data if desired:

   • chat_category = Octocom Chat Widget

   • chat_action = Open

7. Choose the trigger: Octocom – Chat Open.

8. 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:

1. Step 1 – chat_open

2. Step 2 – chat_message_sent

3. 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:

1. In GA4, go to Configure → Events.

2. Find chat_message_sent.

3. 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.