JavaScript SDK

The TrueEngage JavaScript SDK gives you programmatic control over the TrueEngage widget.

Once the widget is embedded on your website, a global trueengage object becomes available and can be used to listen for events, retrieve data, and customize widget behavior.

Getting Started

After embedding the TrueEngage widget script on your website, the SDK is automatically initialized and exposed globally as:

window.trueengage

You can use this object to:

Listen to widget and interaction events
Retrieve visitor and widget data
Manage cookie consent
Customize attributes shown to agents

Events API

The Events API allows you to register callback functions that are triggered when specific widget or interaction events occur.

Registering an Event Listener

trueengage.on(eventName, callback);

Available Events

trueengage:app_initialized

This event is triggered when the TrueEngage application has fully initialized and is ready to be used.

It is the earliest safe point at which you can interact with the trueengage object and retrieve data such as the visitorId.

Unlike widget interaction events, this event is dispatched at the document level.

When to Use This Event

When you need to access the other SDK methods as soon as it becomes available
When initializing integrations with analytics or CRM systems
When setting up logic that must run before any user interaction occurs

Example

document.addEventListener('trueengage:app_initialized', _ => {
  console.info("TrueEngage app initialized");

  const visitorId = trueengage.get("visitorId");
  console.info("Visitor ID:", visitorId);
});

Note: This event is triggered only once, when the TrueEngage application is fully ready.

widget_opened

Triggered when the widget window is opened by the visitor.

trueengage.on("widget_opened", () => {
  console.info("Widget window has been opened");
});

chat_started

Triggered when a chat interaction is started.

Callback parameters:

messageId (string)

The ID of the initial chat message. This ID can be used to attach additional data via the Visitor Data API.
visitorId (string)

A GUID representing the unique visitor ID.

trueengage.on("chat_started", (messageId, visitorId) => {
  console.info("Message ID:", messageId);
  console.info("Visitor ID:", visitorId);
});

communication_ended

Triggered when an interaction (audio or video) ends.

Note: This event may fire more than once at the end of an interaction.

Callback parameter:

eventDetails (object)

communication_channel (string) - audio or video

trueengage.on("communication_ended", (eventDetails) => {
  console.info("Channel:", eventDetails.communication_channel);
});

Data API

The Data API allows you to retrieve information stored within the widget, such as visitor identifiers and remote display names.

Retrieving Data

trueengage.get(propertyName);

Available Properties

visitorId

Returns the unique visitor identifier.

trueengage.get("visitorId");
// Example: "fc9ba53a-f862-416e-a852-44206d793df8"

audioRemoteName

Returns the name displayed for the audio call in Genesys Cloud.

trueengage.get("audioRemoteName");
// Example: "TrueEngage WebRTC" or a custom value

videoRemoteName

Returns the name displayed for the video call in Genesys Cloud.

trueengage.get("videoRemoteName");
// Example: "Video" or a custom value

Cookie Consent API

The Cookie Consent API allows you to explicitly set user consent for different cookie categories.

This is useful when integrating TrueEngage with your own consent management platform (CMP).

Supported Cookie Categories

preferences — User preferences (e.g., language)
statistics — Analytics and usage tracking
marketing — Marketing and advertising cookies

Method: setCookieConsent

Syntax

trueengage.setCookieConsent(category, consent);

Parameters

category (string)

One of: preferences, statistics, marketing
consent (boolean)
- true — Consent granted
- false — Consent denied

Example

trueengage.setCookieConsent('preferences', true);
trueengage.setCookieConsent('statistics', false);
trueengage.setCookieConsent('marketing', true);

Form API

The Form API allows you to programmatically populate form fields displayed in the TrueEngage Form channel.

This is useful when you already know visitor details (for example, from login data or CRM) and want to prefill the form automatically.

Method: setFormFields

Availability: Form channel only

The setFormFields method fills form fields with the provided values.

It can be called anytime after the widget is initialized.

The method accepts a single parameter — an object where:

Keys are form field labels (field identifiers)
Values are the values to populate in the form

Syntax

trueengage.setFormFields(fields);

Parameters

fields (object)

An object containing form field labels as keys and the corresponding values to populate.

Example structure:

{
  first_name: "John",
  last_name: "Doe",
  email: "john.doe@example.org"
}

Recommended Usage

To ensure the form is populated as soon as the widget is ready, use the

trueengage:app_initialized event.

Example

document.addEventListener('trueengage:app_initialized', _ => {

  const fields = {
    first_name: "John",
    last_name: "Doe",
    email: "john.doe@example.org"
  };

  trueengage.setFormFields(fields);

});

Notes & Best Practices

Field keys must match the form field labels configured in the TrueEngage Form channel.
Fields not included in the object will remain unchanged.
Calling setFormFields multiple times will overwrite previously populated values.
This method does not submit the form — it only fills the fields.

Custom Remote Name API

You can override the default audio and video remote names displayed to agents in Genesys Cloud.

This is useful for showing custom labels, departments, or interaction types.

Method: setAudioRemoteName

Sets a custom name for audio interactions.

Syntax

trueengage.setAudioRemoteName(name);

Example

trueengage.setAudioRemoteName('Customer Support Audio');

Method: setVideoRemoteName

Sets a custom name for video interactions.

Syntax

trueengage.setVideoRemoteName(name);

Example

trueengage.setVideoRemoteName('Support Video Call');

Summary

The TrueEngage JavaScript SDK enables you to:

React to widget and interaction lifecycle events
Retrieve visitor and widget-related data
Control cookie consent programmatically
Customize audio and video identifiers shown to agents

This SDK provides a flexible way to tightly integrate TrueEngage with your website and business logic.