User.com REST API Docs

# SDK methods reference

The User.com Web SDK provides two primary interfaces for interacting with the platform: a configuration object for initialization and runtime methods for dynamic operations.

# Overview

# Configuration Object (window.civchat)

This object is defined before the SDK script loads and configures the initial state, user identification, and event callbacks.

# Runtime API (UE / userengage)

After the SDK loads, these global objects become available for programmatic control:

  • UE: Object containing state management methods
  • userengage: Function for triggering events and widget actions

# Configuration (window.civchat)

# Properties

Property Type Required Description
apiKey String Yes Your application API key from Settings > Workspace Settings > API & Integrations > Setup & Integrations.

Common User Attributes: The following standard attributes can be set during initialization:

Property Type Description
user_id String Unique user identifier for precise tracking. Takes precedence over email-based identification.
email String User email address. Subject to Unified Identification logic when user_id is not provided.
first_name String User's first name.
last_name String User's last name.
phone_number String User's phone number.

Custom Attributes: Any additional properties are treated as custom user attributes. For a complete list of available attributes and company association, see Customer Identification.

# Callbacks

Callback Arguments Description
onLoad None Triggered when the widget script and resources finish loading.
onPayloadReceived message (String) Triggered when receiving payloads from automation "Send Code" modules.
onMessage message (Object) Triggered on incoming chat messages. Object contains content and isAdmin properties.
onOpen None Triggered when the widget expands/opens.
onClose None Triggered when the widget minimizes/closes.

For detailed callback implementation, see Widget Callbacks.

# Runtime Methods

# Widget Control

Methods to programmatically control the chat widget's visibility and state.

# userengage('widget.hide')

Completely hides the widget launcher button.

userengage('widget.hide');

# userengage('widget.show')

Shows the widget launcher button (after it was hidden).

userengage('widget.show');

# userengage('widget.open')

Expands/opens the chat window.

userengage('widget.open');

# userengage('widget.close')

Closes/minimizes the chat window.

userengage('widget.close');

# UE.destroy()

Completely removes the widget instance from the DOM.

UE.destroy();

For detailed widget state management, see Managing Chat Widget State.

# User Identification

Methods to manage user sessions and identification.

# UE.pageHit(data)

Updates the current session and identifies the user. Used for page navigation in SPAs or form submissions.

Example 1: Identifying a user (e.g. Form Submission)

UE.pageHit({
  email: "user@example.com",
  first_name: "John",
  event: {
    event_name: "form_submitted",
    form_id: "newsletter_footer"
  }
});

Example 2: Tracking a route change (SPA Navigation) In Single Page Applications, call this without arguments on route change to track a "Page Visit".

// Call after route change
UE.pageHit();

Parameters:

  • data (Object, optional): User attributes and optional event data. If omitted, tracks a standard page view with current URL/Title.

# UE.resetAuth(data)

Clears the current session or switches to a different user.

UE.resetAuth({
  email: "new.user@example.com"
});

Parameters:

  • data (Object, optional): New user data to identify with. If omitted, resets to anonymous.

# userengage('client.update', data)

Updates user attributes without switching the tracking session.

userengage('client.update', {
  first_name: "Jane",
  newsletter_opt_in: true
});

Parameters:

  • data (Object): Key-value pairs of attributes to update.

For comprehensive user identification strategies, see Customer Identification. For attribute updates, see Updating User Attributes.

# Event Tracking

Methods to send behavioral data to User.com.

# userengage('event.name', data)

Tracks custom behavioral events.

userengage('event.button_click', {
  button_id: "cta_main",
  page_section: "hero"
});

Parameters:

  • eventName (String): Must start with event.
  • data (Object, optional): Event attributes.

# userengage('product_event', data)

Tracks e-commerce product interactions.

userengage('product_event', {
  product_id: "SKU-123",
  event_type: "view",
  custom_data: {
    price: 29.99
  }
});

Parameters:

  • data (Object): Must include product_id and event_type.

For detailed event tracking implementation, see Tracking Events. For product events, see Tracking Product Events. For form submissions, see Tracking form submissions.

← Getting started →