User.com REST API Docs

# Updating Attributes

The client.update method is designed for data enrichment. It sends a background request to update the current user's profile data without interrupting their session history.

# Method signature

userengage("client.update", attributesObject);
  • attributesObject (Object): A key-value pair of the attributes you wish to update.

# Capabilities & scope

# Permitted attributes

Not all system attributes can be modified using this method. For example, you cannot manually overwrite certain technical fields like browser_language or ip_address as these are detected automatically.

For a complete list of standard attributes and their mutability, please refer to this article (opens new window).

# Tracking state preservation

The most important characteristic of client.update is that it does not switch the tracking session.

  • Use for: Changing a user's name, email, or custom settings (e.g., newsletter_opt_in: true) while they stay on the same page.

  • Do not use for: Logging in a user or switching from "Anonymous" to "Identified".

# Limitations

# The user_id limitation

You cannot use client.update to switch between users (e.g., during a Login action). Attempting to update the user_id attribute via this method behaves differently than UE.pageHit().

If you include user_id in the update object, one of two things will happen:

  1. Overwrite (Success): If the user_id you provide does not exist in your User.com app, the system will assign it to the current user, overwriting their previous ID.

  2. Conflict (Error): If the user_id you provide already belongs to another user, the request will fail. The system will not switch tracking to that other user; it will simply reject the update to prevent data corruption.

Requirement: To track logged-in users across devices or switch sessions, you must use UE.pageHit(), UE.resetAuth(), or the initial window.civchat configuration.

# Not for Form Submissions

Because client.update does not switch the tracking session, it is not recommended for tracking form submissions (like "Sign Up" or "Login" forms).

Read More: For proper form handling, please refer to the Tracking form submissions guide.

# Implementation

# Basic usage

userengage("client.update", {
    // Standard Attributes
    first_name: "John",
    last_name: "Doe",
    
    // Custom Attributes
    is_dark_mode: true,
    preferences_updated: "2023-10-27"
});

# Verification

To verify the update was successful, check the Network activity in your browser's Developer Tools.

  1. Success Response: Look for a request to the /api/update-attribute/ endpoint.
    • Status: 200 OK indicates the update was accepted.
    • Payload: The response will confirm the accepted attributes.
  2. ID Conflict Error: If you attempt to assign a user_id that is already taken, the API will return a 400-level error with a specific message.
    {
    "errors": {
        "user_id": [
            "Istnieje już użytkownik z tą wartością pola ID użytkownika."
        ]
    }
}
    (Translation: "A user with this User ID value already exists.")

← Managing Chat Widget state →