DocsBuilding AppsInstalling IntercomAPI & Webhook ReferenceCanvas Kit Reference
DocsApp StoreForumBlogYour Apps

Event Model

Event Object

  "event_name" : "invited-friend",
  "created_at": 1389913941,
  "user_id": "342311"
// Sufficient to send just the event name
Intercom('trackEvent', 'invited-friend');
# create an event as a hash
event = {
  :event_name => "invited-friend",
  :email =>,
  :created_at => 1391691571
} event
$event = array(
  "event_name" => "invited-friend",
  "created_at" => 1391691571,
  "user_id" => "314159"
Event event = new Event()


Event Object

An Event Object describes the event and contains the following fields






The name of the event that occurred. This is presented to your App's admins when filtering and creating segments - a good event name is typically a past tense 'verb-noun' combination, to improve readability, for example updated-plan.



The time the event occurred as a UTC Unix timestamp


yes if no email

Your identifier for the user.


yes if no email or user_id.

Your identifier for a lead or a user.


yes if no user_id

An email address for your user. An email should only be used where your application uses email to uniquely identify users



optional metadata about the event.

The event_name field is processed as follows -

  • Names are treated as case insensitive - 'Completed-Order' and 'completed-order' will be considered the same event for your application.
  • Periods (.) and dollars ($) in event names are replaced with hyphens. e.g., 'completed.order' will be stored as 'completed-order'.

To avoid confusion we recommend submitting lower case event names that do not contain periods or dollars!

Metadata Object

Sending an event with metadata

$ curl \
-H 'Authorization:Bearer <Your access token>' \
-H "Content-Type: application/json" -d'
  "event_name" : "invited-friend",
  "created_at": 1389913941,
  "user_id": "314159",
  "metadata": {
     "invitee_email": "[email protected]",
     "invite_code": "ADDAFRIEND"
var metadata = {
  invitee_email: '[email protected]',
  invite_code: 'ADDAFRIEND'
Intercom('trackEvent', 'invited-friend', metadata);
metadata = {
  :invitee_email => '[email protected]',
  :invite_code => 'ADDAFRIEND'
} {
  :event_name => "invited-friend",
  :email =>,
  :created_at => 1391691571,
  :metadata => metadata
$metadata = array(
  "invitee_email" => "[email protected]",
  "invite_code" => "ADDAFRIEND"
  "event_name" => "invited-friend",
  "created_at" => 1391691571,
  "user_id" => "314159",
  "metadata" => $metadata
Event event = new Event()
  .putMetadata("invite_mail", "[email protected]")
  .putMetadata("invite_code", "ADDAFRIEND")
  .putMetadata("found_date", currentTimeMillis()/1000L);


Metadata can be used to submit an event with extra key value data. Each event can contain up to ten metadata key values.

Some use cases for event metadata are -

  • Linking an event back to a page in your website.
  • Describing before and after values for a subscription plan change.
  • Sending contextual information about an online order, a booking.


You can now trigger messages to your users based on event and event metadata and also include the metadata in the messages. For more information on how this works, learn more about event based messaging

See the section 'Metadata Types' for more information on the kinds of metadata you can send.