Terminus Chat + Google Analytics

Prerequisites

You need to have access to Terminus Chat Experiences in order to use this guide.  If you do not have access to Terminus Chat, please reach out to your CSM to discuss your packaging. 

Article quick links:

• List of Available Events to Pass
• How to Pass Events from Terminus Chat into Google Analytics
• How to Import Terminus Chat Event Parameters into Google Analytics as Custom Dimensions
• Example Google Analytics Report with Terminus Chat Data

Feature Details

By adding the respective code snippet(s) when deploying the Terminus Chat script on your site, you are able to pass event activity from Terminus Chat into Google Analytics.

 

List of Available Events to Pass

The following events can be passed into Google Analytics.

The descriptions in this list are also listed with the respective code snippets for each event later in this article.

 

onDataCaptured - pushes an event when a visitor provides information via a data ask or data form.

onMeetingBooked - pushes an event when a visitor successfully books a meeting.

onFirstVisitorInteraction - pushes an event when a visitor first interacts with chat. The first interaction means they typed and sent a message, selected an answer option, or provided information via a data ask.

onButtonClick - pushes an event when a site visitor clicks the chat button to open the chat window.

onButtonDisplayed - pushes an event when the Chat button appears on-screen.

onInit - pushes an event when a page utilizing Terminus Chat is rendered / loaded.

onChatRequested - pushes an event when a visitor opens a chat through any Terminus Chat link or button.

onChatAnswered - pushes an event when a chat request is answered by a chat representative or chatbot.

onChatCompleted - pushes an event when a chat officially ends.

onChatMessage - pushes an event when a message is sent from a representative, visitor, system, or a chatbot/playbook.

Chat events will appear in Google Analytics the following day.

 

How to Pass Events from Terminus Chat to Google Analytics

When adding the Terminus Chat code snippet to your site, simply add the code for each of the desired events to the Ramble.init() function. These respective event snippets should reside within the same script as your main Terminus chat code.

Within the code for each event below, the Name, Category, and Label fields are red. We have provided example event names, but you can customize any of the red values to your liking.

Following the Category and Label lines for each event are optional event parameters. To use these parameters in reporting, they should be imported as Custom Dimensions. This is explained in section three of this article.

When adding these code snippets to your site, you can remove the lines for any params values that you would not like to import as a Custom Dimension.

The “visitorUuid” and “chatUuid” parameters are 36-character unique labels for each chat visitor and chat conversation respectively.

 

onDataCaptured

Pushes an event when a visitor provides information via a data ask or data form.

 

    onDataCaptured: function( params ) {

      gtag('event', 'Data Captured', {

        'event_category' : 'Input Category Here',

        'event_label' : 'Input Label Here',

        'visitor_uuid' : params.visitorUuid,

        'chat_uuid' : params.chatUuid,

        'dataType' : params.type,

        'dataValue' : params.value

      });

    },

Available Parameters:

• visitorUuid: string;
• chatUuid: string;
• message: string;
  • The body of the message that was sent.

• type: “name” | “email” | “phone” | “domain” | “company” | “custom”;
  • Captures the type of data ask collected.

• value: string;
  • The value provided by the visitor, i.e. their email address.

*Note: When a visitor provides information within a form, this event will be called for each individual data ask within the form.

 

onMeetingBooked

Pushes an event when a visitor successfully books a meeting.

 

    onMeetingBooked: function( params ) {

      gtag('event', 'Meeting Booked', {

        'event_category' : 'Input Category Here',

        'event_label' : 'Input Label Here',

        'visitor_uuid' : params.visitorUuid,

        'chat_uuid' : params.chatUuid,

        'email' : params.email,

        'start_time_stamp' : params.startTimestamp,

        'end_time_stamp' : params.endTimestamp,

        'description' : params.description

      });

    },

Available Parameters:

• visitorUuid: string;
• chatUuid: string;
• email: string;
  • Email address provided when booking the meeting.⁺

• startTimestamp: string;
  • The start time of the meeting booked as ISO8601 string.⁺

• endTimestamp: string;
  • The end time of the meeting booked as ISO8601 string.⁺

• Description: string;
  • The description provided by the visitor when booking the meeting.⁺

⁺This parameter is not available for meetings booked via the Calendly integration.

*Note: onDataCaptured() callback will be also called for the email collected when a visitor books a meeting.

 

onFirstVisitorInteraction

Pushes an event when a visitor first interacts with chat. The first interaction means they typed and sent a message, selected an answer option, or provided information via a data ask. This is only called once per chat.

 

onFirstVisitorInteraction: function( params ) {

      gtag('event', 'First Interaction', {

        'event_category' : 'Input Category Here',

        'event_label' : 'Input Label Here',

        'visitor_uuid' : params.visitorUuid,

        'chat_uuid' : params.chatUuid,

        'message' : params.message

      });

    },

Available Parameters:

• visitorUuid: string;
• chatUuid: string;
• message: string;
  • The body of the message that was sent.

onButtonClick

Pushes an event when a site visitor clicks the chat button to open the chat window. This event will pass “true” when a visitor clicks on the chat button.

 

    onButtonClick: function( params ) {

      gtag('event', 'Button Clicked', {

        'event_category' : 'Input Category Here',

        'event_label' : 'Input Label Here'

      });

    },

 

onButtonDisplayed 

Pushes an event when the Chat button appears on-screen. This passes the Button HTML element.

 

  onButtonDisplayed: function( buttonEl ) {

      gtag('event', 'Button Displayed', {

        'event_category' : 'Input Category Here',

        'event_label' : 'Input Label Here'

      });

 

    },

 

onInit 

Pushes an event when a page utilizing Terminus Chat is rendered / loaded.

 

   onInit: function( params ) {

      gtag('event', 'Button Initialized', {

        'event_category' : 'Input Category Here',

        'event_label' : 'Input Label Here',

        'visitor_uuid' : params.visitorUuid,

        'connection_type' : params.connectionType,

        'chat_uuid' : params.chatUuid

      });

    },

Available Parameters:

• visitorUuid: string;
• chatUuid: string;
• connectionType: "new" | "restored";
  • “New” - when visitor does not have an active chat (most times)
  • “Restored” - when visitor has an active chat (e.g. refreshed a page while a chat is active or navigated to a new page with the same chat code)

*Note: For this event, chatUuid will only populate for connectionType “restored”.

 

onChatRequested

Pushes an event when a visitor opens a chat through any Terminus Chat link or button.

 

    onChatRequested: function( params ) {

      gtag('event', 'Chat Requested', {

        'event_category' : 'Input Category Here',

        'event_label' : 'Input Label Here',

        'visitor_uuid' : params.visitorUuid,

        'chat_uuid' : params.chatUuid

      });

    },

Available Parameters:

• visitorUuid: string;
• chatUuid: string;

 

onChatAnswered

Pushes an event when a chat request is answered by a chat representative or chatbot.

 

    onChatAnswered: function( params ){

      gtag('event', 'Chat Answered', {

        'event_category' : 'Input Category Here',

        'event_label' : 'Input Label Here',

        'visitor_uuid' : params.visitorUuid,

        'chat_uuid' : params.chatUuid,

        'answererType' : params.answererType,

        'answererName' : params.answererName,

'answererRealName' : params.answererRealName

      });

    },

Available Parameters:

• visitorUuid: string;
• chatUuid: string;
• answererType: “agent” | “bot”;
  • “Agent” = when a chat representative joins the chat.
  • “Bot” = when a chatbot joins the chat.

• answererName: string;
  • Display name of the bot/chat representative who answers.

• answererRealName: string;
  • Playbook name (if answered by playbook)

onChatCompleted 
Pushes an event when a chat ends.
A chat ends whenever one of the following occurs:

• Visitor ends conversation
• Representative ends conversation
• Playbook ends conversation
• Conversation automatically ends due to six minutes of inactivity from visitor and representative 

    onChatCompleted: function( params ){

      gtag('event', 'Chat Completed', {

        'event_category' : 'Input Category Here',

        'event_label' : 'Input Label Here',

        'visitor_uuid' : params.visitorUuid,

        'chat_uuid' : params.chatUuid

      });

    },

Available Parameters:

• visitorUuid: string;
• chatUuid: string;

 

onChatMessage
Pushes an event when a message is sent from a representative, visitor, system, or a chatbot/playbook.

 

onChatMessage: function( params ) {

      gtag('event', 'Message Sent', {

        'event_category' : 'Input Category Here',

        'event_label' : 'Input Label Here',

        'visitor_uuid' : params.visitorUuid,

        'chat_uuid' : params.chatUuid,

        'message' : params.message,

        'messageType' : params.messageType

      });

    },

Available Parameters:

• visitorUuid: string;
• chatUuid: string;
• message: string;
  • The body of the message that was sent.

• messageType: "agent" | "visitor" | "system" | "bot";
  • “Agent” = message sent by a chat representative.
  • “Visitor” = message sent by the chat visitor.
  • “System” = message sent by the Terminus system (i.e. data provided message)
  • “Bot” = message sent from a playbook.

 

How to Import Terminus Chat Event Parameters into Google Analytics as Custom Dimensions

Import chat event parameters as Custom Dimensions to build custom chat reports in Google Analytics.

Step 1

In Google Analytics, navigate to Configure.

 

Step 2

From the Configure section, navigate to Custom definitions.

 

Step 3

On the Custom dimensions tab, click the blue “Create custom dimensions” button.

Step 4

Complete the following fields:

• Dimension name: Input a name of your choice.
• Scope: Event
• Description: Input a description of your choice.
• Event parameter: Select the parameter you’re importing from the dropdown.

Example:

Step 5

Click Save to create the new custom dimension.

 

 

 

Your new Custom dimension should then appear in the list:

 

 

Example Google Analytics Report with Terminus Chat Events / Custom Dimensions Data

This section walks you through creating an example report in Google Analytics. This example report displays the volume of each data ask type collected via chat over the past 30 days.

As a prerequisite to building this report, pass the OnDataCaptured event with the dataType parameter and import the dataType parameter as a custom dimension.

Step 1

Navigate to the Explore section in Google Analytics.

Step 2

Click to create a new Free form Exploration.

Step 3

Under Variables, name your new Exploration. The example name below is “Count of Data Captured by Type”.

Step 4

Choose the timeframe that you would like to include in your report. In this example, we are reporting on the last 30 days.

Step 5

Ensure that the custom dimension you created for the dataType parameter is listed. You may need to click the plus sign to add the custom dimension.

Step 6

Under Tab Settings, select Table as the visualization type.

Step 7

Continuing to work down the Tab Settings panel, choose the dataType Custom Dimension that you created as the Rows.

Step 8

Choose Event count as the Values.

Once these steps are complete, you will be able to view a table like the following:

 

 

 

   

 

 

Using G4 In Google Analytics

 

To pass the relevant event data to Google Analytics, you will need to include the Google Analytics tracking code on your website and send the event data using the gtag() function ON EACH PIECE OF DATA YOU WANT TO PASS. Here is an example of how you could modify the code you provided to include the Google Analytics tracking code:

 

Note that the gtag() function is highlighted for each data point you want to pass. 

 

**This additional gtag piece is required because of the way custom HTML tags pass data into Google Analytics. 

In order to see these events in Google Analytics 4, you will need to set up corresponding event parameters and mappings in your GA4 configuration.

 

Event parameters are the specific pieces of information you want to track with your events. They consist of a parameter name and a parameter value. For example, in the code you provided, the onMeetingBooked function tracks several parameters, including visitor_uuid, chat_uuid, email, start_time_stamp, end_time_stamp, and description. Each of these should be set up as an event parameter in your GA4 configuration.

 

Once you have set up your event parameters, you will need to create an event mapping that maps each parameter to its corresponding field in GA4. This will tell Google Analytics where to place each piece of information in your reports.

 

To set up event parameters and mappings in GA4, you can follow these steps:

1. Go to your GA4 property in the Google Analytics interface.
2. Navigate to the "Events" section, and click on "Manage Event Parameters".
3. Click the "Create" button to create a new event parameter.
4. Enter a name for the parameter (e.g. "visitor_uuid"), and choose a data type (e.g. "Text").
5. Repeat steps 3-4 for each parameter you want to track.
6. Navigate to the "Event Mapping" section, and click on "Create Mapping".
7. Choose the event name that corresponds to your Ramble event (e.g. "Meeting Booked").
8. Map each event parameter to its corresponding field in GA4. For example, you might map the "visitor_uuid" parameter to the "User ID" field, and the "email" parameter to the "User Email" field.
9. Save your event mapping, and repeat steps 6-8 for each Ramble event you want to track.

 

Once you have set up your event parameters and mappings, your Ramble events should be visible in your GA4 reports. You can view them by navigating to the "Events" section of your GA4 property, and selecting the event you want to view.