Send custom user attributes to Intercom

Intercom lets you create and track custom data attributes about your users and leads, based on criteria that’s specific to your business. 

You can use this data to filter and create customer segments, and to send targeted messages and campaigns. You can also use it as ‘qualification data’ to qualify leads and trial users. 

What’s a data attribute?

A data attribute tracks facts about your customers — like the plan someone is on, or when they signed up — as opposed to an event, which tracks recurring customer actions. 

Here’s an example: if your product is a project management tool, you could track data about the number of files each user has. Then, if you want to message users who haven’t started adding files to the tool and might need some help onboarding, you could set up a message targeted to users with "files less than 1".

The most common data attributes set up on Intercom are about customer development, such as:

• Price plan

• Value of purchases

• Number of teammates added

• Number of songs played

• Date subscription ends

Note: There’s a limit of 250 custom data attributes per workspace, but you can archive unused attributes to free up space. 

How do I create custom data attributes?

To create a new attribute in Intercom, go to Settings > Your workspace data > People data and click "+ Create attribute":

Then, give your new attribute a name, a description and select the type of data it will store:

Click save and the attribute will be added to your attributes list. It won't be populated for any of your customers yet, you'll need to send it to Intercom via the JavaScript snippet, the API, or an app from our app store. 👌

You can also create new attributes directly by adding additional key/value pairs to your intercomSettings code snippet. (The key is the attribute name; the value is a placeholder for the data you’ll track). 

Double check that your keys always have a JSON-valid value that is a string (text), number, or boolean (true or false). That means using double quotes around text strings and sending NULL to cater for cases when no value exists for a user. 

You can also send us dates or URLs. You can track URLs as a text string, e.g. "http://www.google.com". Intercom will recognize this and automatically turn it into a hyperlink. Track dates by sending us a unix timestamp in seconds. If you create a key name that ends with “_at” we'll automatically treat it as a date rather than a number (see  "last_order_at"  below). Find out how dates work in Intercom here.

Here are some examples of data attribute key and value pairs:

window.intercomSettings = {
  email: "bob@example.com",
  user_id: "123",
  app_id: "abc1234",
  created_at: 1234567890,
  "subdomain": "intercom", // Put quotes around text strings
  "teammates": 4, // Send numbers without quotes
  "active_accounts": 12,
  "last_order_at" : 1350466020, // Send dates in unix timestamp format and end key names with "_at"
  "custom_domain": null // Send null when no value exists for a user
}

Things to remember:

• Key names are case sensitive, and can’t contain periods ('.'), dollar signs ('$'), characters like ~`!@#%^&*'{}|\'"  or the NULL character. — If an unsupported character is used, the attribute will be created with an underscore in its place.

• Data values must be sent as JSON strings, numbers or booleans (true or false). We can’t accept object, nested hashes and array data formats.

• Text string values can only hold up to 255 characters.

• You can clear existing data values by sending empty strings. 

• Intercom automatically tracks a number of standard attributes. Check these before creating custom attributes.

Once you’ve updated your code snippet and started tracking the data, you should: 

• Turn on identity verification for your users.

• Create descriptions for each attribute to help your teammates understand them.

Other methods

It's also possible to track and update custom attributes about your users, with CSV imports, Intercom's REST API, or many third party applications.

What is custom qualification data?

Qualification data is a special set of attributes you can manually update in your customer profiles as you qualify them. You can set these up via a simple form in Intercom. If you intend to update this data manually, you don’t need to do anything else. 

If you want to track this data via a ping, you need to add the key/value pairs to your intercomSettings code snippet, just as you would with other custom data.

To create new custom qualification data, go to Settings > Your workspace data > Qualification settings:

Next, click ‘Add data’ then ' + Create new data’ from the dropdown menu. 

Here you can create a name (that’s your key) and choose a format for the values you’ll collect (Text, Number, True or False, or List). If you choose the List format, which creates a defined list of options to choose from, you’ll be able to define the values for the list here as well. Finally, you can add a description to help your teammates understand the data.

Note: choose simple names for your custom qualification data. If you decide you want Operator to qualify this data, customers will see these names in the Messenger.

How do I archive data attributes?

You can archive data anytime. Archived data won’t appear as a filter in your user or lead lists, so it’s a good way to clean up data you don’t need.
Go to Settings > Your workspace data > People data.

Choose a piece of data you'd like to archive. Then, click 'Archive' in the pop-up box. You can unarchive them if you change your mind — right now, you can’t completely delete custom data attributes.

Tip: To find your archived custom attributes, just scroll to the bottom of the page.