You can send Intercom any interesting activity performed by users in your app. They are stored as events. Events can be as simple or as rich as you like. Events record the count, first and last occurrence of an event. Once you're sending Intercom this data, you can filter your user base according to these events and create auto messages to send whenever an event occurs.

Here are some examples of things you can track using the events feature:

  • You could track the most recent time a user performed an action. For example, this could be the last time they exported a PDF or when they contacted support most recently.
  • You could track the first time a user opted for a paid plan, or used a discount code.
  • You could track when a user invites someone else to your service.
  • You can track when (and what) someone ordered on your site.

Events vs custom attributes

  • Custom attributes is data about users, e.g., how many times they've created a project in your app. It's a single value about a single piece of information.
  • Events is information on what users do, and when they do it, e.g. when was the first time they created a project, and when the most recent time they created a project.

Custom attributes are ideal for:

  • Descriptive information about users, such as profile data, region/country, subscription type, or device data.
  • A single value that gets updated such as last active date, follower count, or a single value that becomes true, such as completing a product tour.

Events record the count, first and last occurrence, and so are ideal for:

  • Activity, such as using a particular feature, or the number of times a feature has been used.
  • When data changed, such as when a subscription was changed or the last time an order was placed.
  • Data that may only be needed for a period of time, such as initial use of a feature.

For example, which subscription plan a customer is on, is something you can track using custom attributes. You can then filter and message all those users on that plan. On the other hand, when a user changes their subscription is ideal for recording as an event; you can ask to see all the users that have changed their plan in the last thirty days. Naturally you can mix the data together. e.g. So if you wanted to know who downgraded to your lowest plan over the last 30 days, your filters would be:

  • Plan = Starter plan (This is a standard custom attribute)
  • Downgraded plan less than 30 days ago. (this is an event)

Another example would be recording purchase information. The total amount a user has spent is a good fit for custom attributes, as it is a single value that gets updated over time, whereas the individual orders are better recorded as events, letting you discover how often people are ordering over a period of time.

Example use-cases

You can capture many kinds of activity in Intercom.

Upgrade subscription

In this example, a user has changed their subscription from the Starter plan to the Dynamite+ Pro plan. We can view that as a plain event, like this:

We could then send an auto message thanking the user for their upgrade, triggered by this event. But we can also add context by sending some metadata with the event, such as:

  • New plan name
  • New plan price
  • Previous plan name
  • Previous plan price
  • Date of change

Product feature usage

In this example, a user has used the new mail feature on the app. By tracking this kind of event we can conduct product research on the new mail feature and contact our users to find out things like "what worked well?" and "what could be improved?".

Purchase

In this example we'll record that a user has purchased a video-game. This will allow us to send a cross-sell message, or a thank you message to the customer. As well as noting that the purchase happened, we'll send along some extra metadata:

  • The name of the item ordered
  • An order number that links back to the retail site. We can use a rich link here as that allows us to present the order number as the link title.
  • The order time. We can send this as a timestamp and show a nice readable date for the event.
  • The order amount. We can send the amount in dollars.
  • The Stripe invoice, which we'll also create a link to.

Viewed page

You might want to know which users viewed a particular page a certain amount of times. If users visit your pricing page multiple times, for example, maybe they’re interested in purchasing a subscription. Or when users reach your confirmation page after a purchase flow, you could send them a thank-you message.

If you want to find out which users viewed your pricing page more than 20 times, you can filter your user list for:

Logged in

Maybe you want to see a list of super engaged users who have logged into your product over 20 times in the past month.

Charged

It’s important to track when your user has been charged for a purchase or subscription fee. This makes it easier to chase up any outstanding payments due.

Invited friend

If you run a referral scheme, you will want to see how many people have invited a friend for the first time. You can also see who these users are along with any metadata you've recorded about the event like the name of the referral scheme and the date it ran on. Then you can add credit to your users' account and thank them.

Deleted subscription

Maybe you want to know who has deleted their subscription in the past 2 month so you can investigate what prompted these users to leave.

You can send whatever events you like to Intercom.

Filtering and Messaging based on Events

By filtering on events, you could tell Intercom to show you:

  • All the users who have created more than two reports.
  • All the users that created their first report more than 5 days ago.

We can combine these rules with some of Intercom's standard filters like the "Last Seen' filter, if we want to send the message to a more specific group of active customers. 

How to Submit Events

There are three ways to send events to Intercom:

1. The Intercom JavaScript library

Here's how:

You can submit an event using the trackEvent method. This will associate the event with the currently logged in user and send it to Intercom. The final parameter is a map that can be used to send optional metadata about the event.

Intercom('trackEvent', 'invited-friend');

event with metadata:

var metadata = {
  invitee_email: 'pi@example.org',
  invite_code: 'ADDAFRIEND'
};
Intercom('trackEvent', 'invited-friend', metadata);

2. The Ruby Library

3. Directly to the REST API

See our API Documentation for more details.

Note: In Intercom the events will be capitalized and the dashes will be removed. That means 'invited-friend' will appear as INVITED FRIEND. 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.

For each event you create in Intercom, we record the following for every user:

  • The first time it occurred for that user.
  • The most recent occurrence for that user.
  • The number of times it has occurred in total.

We also provide event delivery via Segment.io.

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 side bar of a user profile.

2. Each individual event appears in the activity stream on a user profile along with other activities such as segments and conversations.

How do I delete events?

Follow these steps to archive an event.

  1. Open your ‘App 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. Find the event that you want to archive and click the 'Archive' icon. 

You can always unarchive an event later, if you change your mind. 

Note: 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. 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 A http or https url: which we'll create a link to.
Rich Link A http or https link: also sent with a title, which we'll create a link to.
Image A 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.

See our API documentation for more details on how to send metadata.

Please note that it's currently not possible to segment users or message them based on event metadata.

Best practices for capturing events

While we believe behavioral and data analytics has it place, events are not intended for use as low-level behavioral metrics. Instead, the purpose is to engage in a conversation with a user. Honestly, we think you'll have as much fun getting to understand your users this way, as you would staring at charts and graphs.

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. As well as the recent activity stream, each of your Users in Intercom has their own activity timeline visible from the profile page.
  3. Send just enough 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. For retail purchases or subscription changes, you can use the Stripe, currency and date metadata extensions to see things in context.
  6. For support related activity, you can send urls that link back to your own systems and use the ability to filter by count and date to see which users are getting in contact and how often.
  7. 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 feed e.g. "Purchased an item", "Created a profile" or "Viewed the product tour".

More about events

Events FAQs

What kind of events should I send?

An event should be something you want to have a conversation about with a customer. With that in mind you can send:

  • Social activity such as inviting other users
  • Retail activity such as placing orders
  • Subscription activity such as plan changes, upgrades or cancellations
  • Site and app interactions such as use of new features

What should I call my events?

We recommend using reasonably short, memorable names for your events that represent the user behavior you want to understand. Using a past tense verb at the beginning of the event name makes the action more readable e.g "Purchased an item", "Created a profile" or "Viewed the product tour". This is because the event names are not simply for machine processing, they are also seen and used by you for filtering and segmentation and will appear in the recent activity stream.

Should I use events for clickstreams and page impressions?

We don't recommend sending volume data such as clickstreams - their signal to noise ratio means won't be as useful as recording significant actions from your users. For example the act of completing an order is more useful for segmentation and messaging than trying to create a segment based on the page impressions that lead up to that action. Low level events will also clutter your filter bar and activity streams making them less useful.

Can I get a feed of event activity?

We don't support event API feeds today. But it is something we might look at in the future as we develop our APIs.

Is there a limit on the number of event types I can send?

You can create up to 120 types of events. After that the limit is exceeded. Events that are over the limit will not be stored and will return an error. 

Why is there a limit on the number of event types I can send?

Limiting the number of events reduces the noise on the site, making it easier for you to filter and segment users. It also helps avoid issues that can arise when trying to record and filter users from low level behavior.

What kind of metadata can I send?

You can send the following:

  • Plain Strings, Dates, and Numbers
  • Links and image links
  • Monetary amounts along with a currency
  • Stripe invoice, customer and charge identifiers

Can I filter or search on metadata?

We don't support filtering or searching on metadata today. Currently metadata is primarily for adding context to an event in the activity stream, but filtering and searching on event metadata is something we might look at in the future.

Is there a limit on how much metadata I can send?

You can send up to 5 metadata items with each event.

What values can I send for the event name?

The letters a-z, A-Z, the numbers 0-9, underscores and hyphens. In particular the following are applied to event names:

  • Periods (.), dollars ($), and whitespace are replaced with hyphens.
  • Event names are treated as case insensitive - the event "Contacted-Support" and "contacted-support" will be treated as the same name.

What values can I send for the created time of an event?

The created time is a Unix timestamp, measuring the number of seconds elapsed since Thursday, 1 January 1970, UTC, which we also store as second resolution in UTC - we don't support submitting a timezone with the timestamp. It's worth bearing in mind that timestamps sent with a higher resolution (e.g. milliseconds) will be rounded to seconds.

How does event de-duplication work?

Each event is identified using the following data:

  • The event name
  • The created timestamp
  • The user that triggered the event
  • The app 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.

Did this answer your question?