How to automatically push custom data from the chatbox with the Crisp JS SDK

Learn how to set, update, and clear custom data in Crisp using the JavaScript SDK or REST API.

Custom data is best for key/value context such as account ID, plan, order ID, revenue, lifecycle stage, or internal links. Use it when a simple segment is not detailed enough.

Before you start

Use simple custom data keys that your team can reuse consistently.

Keys should be lowercase. Avoid special characters except underscores (_) and dashes (-). Values sent through the Web SDK should be strings, numbers, or booleans.

Update one key/value

Using the JavaScript SDK

Use the Crisp JavaScript SDK from your front-end code when the data belongs to the current visitor session.

// Replace this key and value with your own custom data.
$crisp.push(["set", "session:data", [[
  ["order_id", "3535353214"]
]]]);

Using the REST API

Use the REST API from your backend when you need to update conversation data or contact data server-side.

Common API routes for custom data:

Conversation data → Update Conversation Metas
Contact data → Update People Data

Add your custom data inside the data object.

{
  "data": {
    "plan_price": "95"
  }
}

To understand the difference between conversation/session data and contact data, read What is custom data and why is it powerful?.

Update multiple key/values

Using the JavaScript SDK

Send several key/value pairs in the same session:data call.

// Replace these keys and values with your own custom data.
$crisp.push(["set", "session:data", [[
  ["order_id", "3535353214"],
  ["last_order_at", "04 January"],
  ["user_id", "XXXX-XXXX"]
]]]);

Using the REST API

Send several keys inside the same data object.

{
  "data": {
    "plan_price": "95",
    "profile_link": "https://mylink.com"
  }
}

Update People Data merges the provided keys with existing contact data. Save People Data replaces the full contact data object, so use it only when you intentionally want to overwrite the stored data.

Clear custom data

Using the JavaScript SDK

To clear a session data key from the current visitor session, set it to an empty value.

// Clear the order_id value from the current session data.
$crisp.push(["set", "session:data", [[
  ["order_id", ""]
]]]);

Using the REST API

With the REST API, choose the route depending on whether you want to merge, update, or replace stored data. For contact data, Update People Data merges keys, while Save People Data replaces the complete data object.

{
  "data": {}
}

Sending an empty data object with a replacement route clears the full data object, not just one key. Use it carefully.

Example: custom data in a conversation

Here is an example of custom data displayed on a Crisp contact profile.

Custom data displayed on a Crisp contact profile

For a customer contacting Crisp through chat, email, WhatsApp, or another channel, useful custom data can include profile, plan, and account information.

Examples of useful custom data keys:

user_id → unique identifier that opens the user profile in your own system
website_id → unique identifier for the workspace or website the user belongs to
plan → current plan name
plan_price → current plan price
is_trialing → whether the customer is still in trial
websites → number of workspaces or inboxes the customer has created

This data can also appear directly in the conversation, helping agents understand the customer before replying.

Custom data displayed inside a Crisp conversation

Want to know why custom data matters? Read What is custom data and why is it powerful?.

Updated on: 03/05/2026

Was this article helpful?

Thank you!