The User.com JavaScript SDK allows you to interact and exchange data with the User.com application directly from your website’s frontend. Using the global UE object, the userengage function, and the window.civchat configuration, you can initialize the chat widget, manage user and company data, send custom events, track navigation, and control widget behavior.
You can use this SDK to:
UE.pageHit()window.civchatuserengageThis guide covers JavaScript integration only.For backend/server-side usage, refer to the REST API documentation. For mobile apps, refer to the Mobile SDK documentation.
To begin tracking anonymous users and enabling widget functionalities, include the following script before the closing <body> tag of your page:
This setup initializes the widget. Users will be tracked anonymously since no user attributes are included.
After the script loads, you gain access to the userengage namespace and UE methods.
You can pass user (and company) attributes by extending the window.civchat object. Example:
Note: These values can be dynamically set using GTM variables or JavaScript.
If a user_id is included:
{ fixed_attr: "value" } or { fixed_attr: ["value"] }{ fixed_attr: ["value1", "value2"] }{ datetime_attr: "2016-08-03T12:00:00+00:00" }{ date_attr: "2016-08-03" }
You can control how the chat widget appears on page load by specifying a state value inside the window.civchat object:
Supported state values:
"simple" – displays only the widget icon"standard" – displays the widget icon with a greeting message"hidden" – completely hides the widgetThis setting overrides the default state configured under Settings → Chat Widget Settings in the User.com app. Use it when you need programmatic control over the widget's visibility or behavior on specific pages.
Triggered after the widget loads.
Handles messages from the automation Send Code module.
The onMessage callback is triggered for every incoming chat message. The message object passed to this function contains details about the message, including its content and origin.
The isAdmin property within the message object indicates the source of the message:
isAdmin is set to true, the message originated from the backend side (e.g., an agent or automation).isAdmin is false, the message was sent from the front-end widget by the user.This distinction allows you to handle messages differently based on their origin.
Sample message object:
In this example, since isAdmin is true, the message was sent from the backend side.
Triggered when the widget is opened (expanded by the user or programmatically).
Triggered when the widget is closed by the user or programmatically.
The UE.pageHit() method sends a virtual page view to our servers, simulating navigation on single-page applications (SPAs). This method updates the user's session with any attributes passed and records a page view based on the current browser URL (retrieved automatically—no need to include it manually in the payload).
Calling UE.pageHit() will:
window.location.href as the URLevent object passed in the call
You can also send custom events:
With unified identification enabled UE.pageHit has ability to switch tracking in browser to the different user. In such case it may be important to send event together with UE.pageHit and not by a separate userengage function call. You can read more about it here.
The UE.resetAuth() method resets the __ca__chat cookie and global tracking context. It immediately ends the current user's session and starts tracking a new user. This function is commonly used when a user logs out of your application, as it ensures the next visitor session begins anonymously or with a fresh identity.
Calling this method will:
You must include the apiKey in the payload every time you use this method.
You can also pass new user details:
When Authorize by email is enabled (must be activated by our support), UE.resetAuth() will check if a user with the provided email already exists:
When Authorize by email is disabled (default):
To learn more about these scenarios and how they relate to tracking behavior, refer to the Unified Identification section below.
Removes the widget instance from the DOM. After the current widget instance has been destroyed, you cannot refer to the UE methods. This method takes no arguments.
The userengage function provides a versatile interface to interact with the User.com platform, allowing you to send custom events, product-related events, update user attributes, and control the chat widget's state.
You can track user interactions by sending custom events along with associated attributes:
Note: It's not required to predefine events or their attributes before sending them. However, if you send attributes without defining them in advance, they will be automatically created with a String data type. Additionally, attributes are optional when sending events. To maintain clean and accurate data structure, it's recommended to predefine attributes with the correct data types in your User.com app. You can read more about events here.
To monitor user interactions with products, such as adding items to a cart you can use product events:
Required fields: product_id and event_type.
Optional fields: name, description, and any other relevant product attributes.
Event types include: add to cart, purchase, liking, add to observation, order, reservation, return, view, click, detail, add, remove, checkout, checkout option, refund, promo click.
Important: Product attribute are updated with the latest values sent. This means historical values aren't stored, and each new event updates the product's profile with the latest information.
To learn more about product events, click here.
To update user attributes without triggering a page view, use the client.update method:
Note: Not all attributes can be updated using this method. Ensure the attributes you intend to update are permitted. You can learn more about it here.
Control the chat widget's visibility and state using the following command:
These methods allow for dynamic control over the chat widget's behavior based on user interactions or specific conditions on your website. You can set up one of the following states:
Unified Identification in ensures consistent user tracking by linking sessions across devices and cookies using email, user_id, and widget session data. This feature affects both UE.pageHit() and UE.resetAuth() methods and must be enabled by User.com support.
The primary goal is to prevent duplicate users from being created based on email, ensuring accurate identification and continuity across user sessions. By default, Unified Identification is disabled—so passing an email in pageHit() will overwrite the current user's email without checking if the same email is already assigned to another user, and resetAuth() will always create a new user.
When Unified Identification is enabled, the platform intelligently manages identity using cookie state and user attributes. It works in tandem with an additional setting—Authorize by email, which is also activated by User.com support. Importantly, these mechanisms apply only when an email is passed and no user_id is included in the request.
The behavior differs based on the state of Authorize by email:
pageHit():resetAuth():pageHit():resetAuth():In both methods, if a match occurs (cookie/email), user attributes can be updated and events triggered as expected. To ensure reliable identity handling and prevent email duplication, it is strongly recommended to enable both Unified Identification and Authorize by email.
To request activation of these features, please contact our support through the chat.
