---
title: JavaScript SDK
description: Learn how to use the TrueEngage JavaScript SDK to control the widget, listen to lifecycle events, retrieve visitor data, manage cookie consent, customize audio and video labels, and prefill Form channel fields programmatically.
---
[ ](https://kb.trueengage.com/?hsLang=en)
[Home](https://trueengage.com/?hsLang=en) [Docs](https://kb.trueengage.com/genesys-cloud?hsLang=en) [Pricing](https://trueengage.com/genesys-cloud/pricing?hsLang=en)
[Sign In](https://management.trueengage.com/login) [Install from AppFoundry](https://appfoundry.genesys.com/filter/genesyscloud/listing/d3d5011e-668b-411c-bc8d-512e3023b359) [Book a Demo](https://trueengage.com/genesys-cloud/demo?hsLang=en)
[Home](https://trueengage.com/?hsLang=en) [Docs](https://kb.trueengage.com/genesys-cloud?hsLang=en) [Pricing](https://trueengage.com/genesys-cloud/pricing?hsLang=en)
[Sign In](https://management.trueengage.com/login) [Install from AppFoundry](https://appfoundry.genesys.com/filter/genesyscloud/listing/d3d5011e-668b-411c-bc8d-512e3023b359) [Book a Demo](https://trueengage.com/genesys-cloud/demo?hsLang=en)
[Skip to content](https://kb.trueengage.com/genesys-cloud/javascript-sdk#main-content)
- [Tickets](https://support.trueengage.com/tickets-view)
- [Sign out](https://support.trueengage.com/_hcms/mem/logout)
Open main navigation
Close main navigation
- [Tickets](https://support.trueengage.com/tickets-view)
- [Sign out](https://support.trueengage.com/_hcms/mem/logout)
How can we help you?
- There are no suggestions because the search field is empty.
1. [Knowledge Base](https://kb.trueengage.com/genesys-cloud?hsLang=en)
2. [Integrations & API's](https://kb.trueengage.com/genesys-cloud/integrations-apis?hsLang=en)
# 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');
```
---
#### Callback API
The Callback API allows you to control how callback requests are routed within TrueEngage.
You can dynamically change the queue assigned to callbacks, which is useful for routing requests based on user context, business logic, or availability.
### Methods
#### setQueue
Sets the queue to which callback requests will be routed.
**Syntax**
```
trueengage.callback.setQueue(queueId);
```
**Parameters**
- `queueId` (string)
The unique identifier (GUID) of the target queue.
**Example**
```
trueengage.callback.setQueue("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx");
```
**When to use**
- When routing callbacks to a specific department
- When dynamically assigning queues based on user attributes
- When integrating with external systems (e.g. CRM, segmentation logic)
---
#### setScheduleQueue
Sets the queue used for **scheduled callbacks**.
**Syntax**
```
trueengage.callback.setScheduleQueue(queueId);
```
**Parameters**
- `queueId` (string)
The unique identifier (GUID) of the target queue for scheduled callbacks.
**Example**
```
trueengage.callback.setScheduleQueue("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx");
```
**When to use**
- When scheduled callbacks should be handled by a different team than immediate callbacks
- When separating real-time and planned interactions
---
### Recommended Usage
To ensure the correct queue is set as soon as the widget is ready, use the `trueengage:app_initialized` event:
```
document.addEventListener('trueengage:app_initialized', _ => {
```
---
### Notes & Best Practices
- Queue IDs must be valid and configured in the backend (e.g. Genesys Cloud).
- Calling these methods multiple times will overwrite previously set values.
- Make sure the queue is set **before the user requests a callback**.
- [Getting Started](https://kb.trueengage.com/genesys-cloud/getting-started?hsLang=en)
- [Installation & Setup](https://kb.trueengage.com/genesys-cloud/installation-setup?hsLang=en)
- [User Guide](https://kb.trueengage.com/genesys-cloud/user-guide?hsLang=en#main-content)
- [Contact Channels](https://kb.trueengage.com/genesys-cloud/user-guide?hsLang=en#contact-channels)
- [Features](https://kb.trueengage.com/genesys-cloud/features?hsLang=en)
- [FAQs](https://kb.trueengage.com/genesys-cloud/faqs?hsLang=en)
- [Troubleshooting](https://kb.trueengage.com/genesys-cloud/troubleshooting?hsLang=en)
- [Administration & Billing](https://kb.trueengage.com/genesys-cloud/administration-billing?hsLang=en)
- [Integrations & API's](https://kb.trueengage.com/genesys-cloud/integrations-apis?hsLang=en)
- [Architecture & Security](https://kb.trueengage.com/genesys-cloud/architecture-security?hsLang=en)
- [Legal](https://kb.trueengage.com/genesys-cloud/legal?hsLang=en)
- [Interaction Routing & Availability](https://kb.trueengage.com/genesys-cloud/interaction-routing-availability?hsLang=en)
[%20copy.png?width=440&height=36&name=logo%20(3)%20copy.png "logo (3) copy")](https://www.trueengage.com?hsLang=en)
[mailto:email@email.com](mailto:email@email.com)