The intercom API reference.
URL https://developers.intercom.com
License MIT
The intercom API reference.
With the AI Content APIs, you can create and manage External Pages and Content Import Sources for your Fin Content Library.
Â
External Pages are pages that you want Fin to be able to answer questions about. The API for External Pages is a great way to ingest into your Fin Content Library pages that are not publicly accessible and hence can't be crawled by Intercom.
Â
Content Import Sources are the sources of those pages, and they are used to determine the default audience for the pages (configured via the UI). You should create a Content Import Source for each source of External Pages that you want to ingest into your Fin Content Library.
Â
You can then iterate through the content from that source via its API and POST it to the External Pages endpoint. That endpoint has an external_id parameter which allows you to specify the identifier from the source. The endpoint will then either create a new External Page or update an existing one as appropriate.",
Data events are used to notify Intercom of changes to your data.
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
An email address for your user. An email should only be used where your application uses email to uniquely identify users.
{ "type": "event", "event_name": "invited-friend", "created_at": 1671028894, "user_id": "314159", "id": "8a88a590-e1c3-41e2-a502-e0649dbf721c", "intercom_user_id": "63a0979a5eeebeaf28dd56ba", "email": "frodo.baggins@example.com", "metadata": { "invite_code": "ADDAFRIEND" } }
You will need an Access Token that has write permissions to send Events. Once you have a key you can submit events via POST to the Events resource, which is located at https://api.intercom.io/events, or you can send events using one of the client libraries. When working with the HTTP API directly a client should send the event with a Content-Type of application/json.
When using the JavaScript API, adding the code to your app makes the Events API available. Once added, you can submit an event using the trackEvent method. This will associate the event with the Lead or currently logged-in user or logged-out visitor/lead and send it to Intercom. The final parameter is a map that can be used to send optional metadata about the event.
With the Ruby client you pass a hash describing the event to Intercom::Event.create, or call the track_user method directly on the current user object (e.g. user.track_event).
NB: For the JSON object types, please note that we do not currently support nested JSON structure.
| Type | Description | Example |
|---|---|---|
| String | The value is a JSON String | "source":"desktop" |
| Number | The value is a JSON Number | "load": 3.67 |
| Date | The key ends with the String _date and the value is a Unix timestamp, assumed to be in the UTC timezone. | "contact_date": 1392036272 |
| Link | The value is a HTTP or HTTPS URI. | "article": "https://example.org/ab1de.html" |
| Rich Link | The value is a JSON object that contains url and value keys. | "article": {"url": "https://example.org/ab1de.html", "value":"the dude abides"} |
| Monetary Amount | The value is a JSON object that contains amount and currency keys. The amount key is a positive integer representing the amount in cents. The price in the example to the right denotes €349.99. | "price": {"amount": 34999, "currency": "eur"} |
Lead Events
When submitting events for Leads, you will need to specify the Lead's id.
Metadata behaviour
Event de-duplication
The API may detect and ignore duplicate events. Each event is uniquely identified as a combination of the following data - the Workspace identifier, the Contact external identifier, the Data Event name and the Data Event created time. As a result, it is strongly recommended to send a second granularity Unix timestamp in the created_at field.
Duplicated events are responded to using the normal 202 Accepted code - an error is not thrown, however repeat requests will be counted against any rate limit that is in place.
202 Accepted with an empty body.401 Unauthorized or 403 Forbidden response code.404 Not Found.500 response code and may contain an error message in the body.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
The unique identifier for the contact (lead or user) which is given by Intercom.
An email address for your user. An email should only be used where your application uses email to uniquely identify users.
curl -i -X POST \
https://api.intercom.io/events \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-H 'Intercom-Version: Unstable' \
-d '{
"event_name": "invited-friend",
"created_at": 1671028894,
"user_id": "314159",
"id": "8a88a590-e1c3-41e2-a502-e0649dbf721c",
"email": "frodo.baggins@example.com",
"metadata": {
"invite_code": "ADDAFRIEND"
}
}'{ "type": "error.list", "request_id": "18ac76c7-3a43-41d0-89a2-0e1d026c79c3", "errors": [ { … } ] }
🚧
Please note that you can only 'list' events that are less than 90 days old. Event counts and summaries will still include your events older than 90 days but you cannot 'list' these events individually if they are older than 90 days
The events belonging to a customer can be listed by sending a GET request to https://api.intercom.io/events with a user or lead identifier along with a type parameter. The identifier parameter can be one of user_id, email or intercom_user_id. The type parameter value must be user.
https://api.intercom.io/events?type=user&user_id={user_id}https://api.intercom.io/events?type=user&email={email}https://api.intercom.io/events?type=user&intercom_user_id={id} (this call can be used to list leads)The email parameter value should be url encoded when sending.
You can optionally define the result page size as well with the per_page parameter.
curl -i -X GET \
'https://api.intercom.io/events?summary=true&type=string&user_id=string' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Intercom-Version: Unstable'{ "type": "event.summary", "events": [], "pages": { "next": "http://api.intercom.test/events?next page" }, "email": "user26@email.com", "intercom_user_id": "67506288d5eefd6f04e7d13d", "user_id": "3ecf64d0-9ed1-4e9f-88e1-da7d6e6782f3" }
curl -i -X POST \
https://api.intercom.io/events/summaries \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-H 'Intercom-Version: Unstable' \
-d '{
"user_id": "314159",
"event_summaries": {
"event_name": "invited-friend",
"count": 1,
"first": 1671028894,
"last": 1671028894
}
}'{ "type": "error.list", "request_id": "98bdc0cf-cfd5-438e-84e4-02bed25124b0", "errors": [ { … } ] }