There are three ways to send events to Intercom:

  1. The Intercom JavaScript API
  2. Directly via the REST API
  3. Through our mobile SDKs

Here's how to set up each method:

1. The Intercom JavaScript API

You can submit an event using the Intercom(‘trackEvent’) method. This will associate the event with the currently tracked visitor, lead or user and send it to Intercom. The final parameter is an optional metadata object that can be used to send additional details about the event.

Intercom('trackEvent', 'purchased-item');

Event with metadata:

var metadata = {
  item: 'NES',
  price: {"amount": 2900, "currency": "usd"},
  catalog_img: "https://downloads.intercomcdn.com/128113c39a6a.jpg",
  order_number: {URL: "https://example.com/tx186373", value: "TX186373"},
  stripe_customer: "0ry6mmrFxKxtGG"  
};

Intercom('trackEvent', 'purchased-item', metadata);

2. Directly via the REST API

You can track events directly via the REST API, using the language of your choice, or one of our supported SDKs:

When tracking an event with the REST API, you can also specify a “created_at” time to define specifically when an event took place. The created time is a Unix timestamp, measuring the number of seconds elapsed since Thursday, 1 January 1970, UTC. We don't support submitting a timezone with the timestamp. Timestamps sent with a higher resolution (e.g. milliseconds) will be rounded to seconds. 

See our API Documentation for more details.

3. From your mobile app using one of our mobile SDKs

You can use any of our mobile SDKs to set up event tracking:

We also provide event tracking via a number of apps like Segment or Stripe.

Things to remember:

  • Key names are case insensitive, and can’t contain periods ('.'), dollar signs ('$'), characters like ~`!@#%^&*'{}|\'" or the NULL character.
  • Text string values can only hold up to 255 characters.
  • In the event summary in Intercom any dashes in key names will be removed. The key is still important for tracking data, while 'invited-friend' and 'invited friend' will both be displayed as Invited friend in the UI, the two fields represent different data.

Adding descriptions to events 

You can add a description to any event you create in Intercom. This will help both you and your teammates remember what that event means and you'll quickly understand how to use it. 

Viewing events in Intercom

Events are visible in two places in Intercom:

1. Events are aggregated and a summary is displayed on the sidebar of a user profile.
2. Each individual event appears in the activity timeline on a user profile along with other activities such as segments and conversations.

Note: When someone first contacts you and is added as a lead in Intercom, you can see any events they’ve tracked in the last 90 days before getting in touch.

How do I delete events?

Follow these steps to archive an event.

  1. Open your ‘Settings’ menu in the bottom left-hand corner of the screen by clicking on your avatar.
  2. Select 'Events' from the left hand side menu.
  3. Click on the event that you want to archive and click the 'Archive' button. 

You can always unarchive an event later if you change your mind, but archived events aren't recreated if you track them again. 

Metadata support

As we've mentioned, you can send metadata with any event, which we'll store and you'll see it in Intercom. Please note that it's currently not possible to filter your customers based on event metadata, or include it in messages. Each event can be sent with up to five fields and we support the following kinds of data:

Metadata: Description
String: A plain string.
Number: Positive or negative number.
Date: A timestamp which we'll show as a human readable date.
Link: An http or https url, which we'll create a link to.
Rich link: An http or https link, also sent with a title, which we'll create a link to.
Image: An http or https link to an image, which we'll show.
Stripe (retail): A Stripe invoice, customer or charge identifier, which we'll create a link to.
Monetary (retail): An amount with a currency.

Best practices for capturing events

Events are best for filtering and segmenting your users, and sending targeted messages to your customers.

With that in mind, we have some recommendations on how to get the most out of Events:

  1. Send events which capture meaningful actions. A purchase is a great basis for a conversation as opposed to recording all the clicks that lead up to that purchase. Meaningful events will also make creating filters and auto-messages much easier.
  2. Send events as if they were social interactions between your users and your business. Each of your Users in Intercom has their own activity timeline visible from the profile page.
  3. Send the right amount of metadata. Metadata is a great way to contextualise activity, but sending too much can be distracting. Remember that you can always link back to your own systems for more details.
  4. Use events to understand user to user interactions like invitations and social activity. You can use metadata to provide a rich view of how users are interacting with your business and each other.
  5. Name your events in a way that makes them easily readable in Intercom. Using a past tense verb at the beginning of the event name makes the action more easily understood when it appears in the user activity timeline e.g. "Purchased an item", "Created a profile" or "Viewed the product tour".

Troubleshooting events

There are a couple of things to keep in mind if you have trouble tracking events in Intercom:

Have I tracked more than 120 events?

You can track up to 120 active events. After that limit is exceeded any new events you try to track will not be stored and will return an error. You can archive any unused events to make way for new ones. Keeping within this limit will help reduce the noise in your workspace, making it easier for you to filter and segment users. 

Am I sending duplicate events?

Each event is identified using the following data:

  • The event name
  • The created timestamp
  • The user that triggered the event
  • The workspace the user belongs to

Any two events that have the same values for those fields will be treated as the same event. As such, we don't store subsequent copies of the event after receiving the first copy. Note that currently, we maintain de-duplication information for 48 hours from the time we see the first event, but this is subject to change.

Have I loaded the Intercom JavaScript library?

To track events with the JavaScript API you’ll need to ensure that the Intercom JavaScript snippet has already successfully loaded on the page. To Install Intercom, copy the first code snippet in your web settings, where we pre-populate your workspace ID (this is called your App_ID in the code) for you. Then paste the code right before the closing body tag of any page where you want to track events.

Have I tracked the event in the right place?

To target a user auto message based on an event, the event needs to have been tracked by a logged- in user of your product. The same applies when targeting visitor auto messages - only events that have been tracked by a logged-out visitors will appear as available audience filters.

What's next?

Read this article to understand when to use custom attributes vs events.

Did this answer your question?