User.com REST API Docs

# Customer identification

Effectively identifying users is the bridge between anonymous web traffic and actionable customer data. This guide details how the JavaScript SDK handles user identity, attribute synchronization, and secure session management.

# Anonymous tracking

By default, the SDK tracks every visitor immediately upon load.

  • Mechanism: The SDK generates a unique identifier and stores it in the browser's cookies under the key __ca__chat.
  • Persistence: This cookie allows the SDK to recognize returning visitors across sessions, maintaining their chat history and page view timeline even if they have not logged in.
  • Linking: In the application database, this anonymous identifier corresponds to the userKey attribute.

# Tracking User ID

To identify a specific user (e.g., after they log in to your application), you can pass their credentials to the window.civchat configuration object.

# The user_id priority

The user_id field is the primary key for identification. It takes precedence over all other identification methods.

  • If user_id is present: The SDK ignores all email-based lookup logic described in the sections below.
  • Behavior:
    • If the ID exists in User.com: Tracking immediately switches to that user profile.
    • If the ID does not exist: The ID is assigned to the current anonymous session (the user currently tracked by the __ca__chat cookie).

Best Practice: We highly recommend using a hash of the user's email or your internal database ID as the user_id to ensure uniqueness and security.

# Unified Identification

Unified Identification ensures consistent user tracking across devices by linking sessions using email, user_id, and widget session data. This feature was introduced to make tracking more consistent and avoid creating duplicate email records.

This feature fundamentally alters how the SDK handles email addresses passed via:

  1. The initial window.civchat configuration.
  2. The UE.pageHit() method.
  3. The UE.resetAuth() method.

Note: Unified Identification and "Authorize by email" are advanced features that must be enabled by User.com support. Contact support to activate them.

The following rules apply only when an EMAIL is passed and NO user_id is provided.

# Scenario A: Default (Unified Identification disabled)

By default, the system prioritizes the current session over data integrity.

  • Behavior: Passing an email simply overwrites the email of the current user (cookie owner).
  • Risk: It does not check if that email belongs to another user in the database. This can lead to multiple user records sharing the same email or data merging incorrectly.

# Scenario B: Unified Identification enabled

When enabled, the system attempts to prevent duplicates by checking for existing users. The logic splits further based on the Authorize by email setting.

Method/Context Authorize by Email: ENABLED Authorize by Email: DISABLED
window.civchat
or
UE.pageHit()		 Match: If email matches cookie's current user, session continues normally.

Mismatch: If a user with that email exists, tracking switches to that user. If not, a new user is created and tracking switches to that user. 		Has Email: If current user already has an email, a new user is created and tracking switches to that user (prevent overwrite).

No Email: Provided email is assigned to current user. (No duplicate check).
UE.resetAuth() Match: If a user with the provided email exists, tracking switches to that user.

Mismatch: If not, a new user is created and tracking switches to that user. 		A new user is always created with the provided email, regardless of whether it exists in the app or is already tracked.

# Additional user data

Once you understand how the user is identified, you can enrich their profile by passing attributes.

# Passing attributes

Attributes are passed at the root level of the window.civchat object. These values overwrite existing data in User.com if the attribute already exists (except user_id and/or email as explained above).

window.civchat = {
  apiKey: "YOUR_API_KEY",
  // Core Identification
  user_id: "52bdc3be5145e87076c8",
  email: "johndoe@example.com", // Subject to Unified Identification logic if user_id is missing

  // Standard Attributes
  name: "John Doe",
  gender: 2, // 1=Male, 2=Female, 3=Unknown
  status: 2, // 1=Visitor, 2=User
  phone_number: "+44754123434",
  score: 0,

  // Custom Attributes (Root Level)
  plan_type: "premium",
  newsletter_opt_in: true,

  // Company Data (Nested Object)
  company: {
    company_id: "12345", // Required for linking
    name: "Acme Corp",   // Optional if company exists
    revenue: "$239.9 billion"
  }
};

# Attribute formatting rules

When sending custom data, strict formatting ensures values are stored correctly in the dashboard.

Attribute Type Format Example Notes
Fixed (String) { plan: "pro" } Standard string values.
Fixed (Multi-choice) { tags: ["developer", "admin"] } Pass as an array of strings.
Date { signup_date: "2023-08-03" } Format: YYYY-MM-DD
DateTime { last_login: "2017-07-25T14:14:08.612Z" } Format: ISO 8601.
Boolean { is_vip: true } Stored as boolean.

# Company association

The company object allows you to link the current user to a company entity.

  • Linking: If you provide a company_id that exists in User.com, the user is linked to that company.
  • Creation: If the company_id does not exist, a new company is created with the provided attributes (e.g., name, revenue).

# Reset customer identity

Use UE.resetAuth() to clear the current session or switch users dynamically (e.g., on Logout or Login actions in Single Page Applications).

This method accepts new user data as an argument. Note that if you provide an email address, the Unified Identification logic defined above applies immediately.

// Example: Logout and identifying a new user immediately
UE.resetAuth({
    email: "new.user@example.com",
    first_name: "New User"
});

// Example: Simple logout (resets to anonymous)
UE.resetAuth();

← Tracking Events →