The intercom API reference.
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.",
Everything about your Custom Object instances.
From now on, to access this endpoint, you need additional permissions. Please head over to the Developer Hub app package authentication settings to configure the required permissions.
A Custom Object Instance represents an instance of a custom object type. This allows you to create and set custom attributes to store data about your customers that is not already captured by Intercom. The parent object includes recommended default attributes and you can add your own custom attributes.
The id you have defined for the custom object instance.
The time when the Custom Object instance was created in the external system it originated from.
The time when the Custom Object instance was last updated in the external system it originated from.
The time the attribute was created as a UTC Unix timestamp
The time the attribute was last updated as a UTC Unix timestamp
The identifier of the custom object type that defines the structure of the custom object instance.
{ "id": 16032025, "external_id": "0001d1c1e65a7a19e9f59ae2", "external_created_at": 1571672154, "external_updated_at": 1571672154, "created_at": 1671028894, "updated_at": 1671028894, "type": "Order", "custom_attributes": { "property1": "string", "property2": "string" } }
You can update a contact
An image URL containing the avatar of a contact
The time specified for when a contact signed up
The time when the contact was last seen (either where the Intercom Messenger was installed or when specified manually)
The id of an admin that has been assigned account ownership of the contact
Whether the contact is unsubscribed from emails
curl -i -X PUT \
https://api.intercom.io/contacts/63a07ddf05a32042dffac965 \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-H 'Intercom-Version: Unstable' \
-d '{
"email": "joebloggs@intercom.io",
"name": "joe bloggs"
}'
successful
The unique identifier for the contact which is given by Intercom.
The unique identifier for the contact which is provided by the Client.
The contacts phone number normalized to the E164 format
The id of an admin that has been assigned account ownership of the contact.
Whether the contact has marked an email sent to them as spam.
(UNIX timestamp) The time when the contact was created.
(UNIX timestamp) The time when the contact was last updated.
(UNIX timestamp) The time specified for when a contact signed up.
(UNIX timestamp) The time when the contact was last seen (either where the Intercom Messenger was installed or when specified manually).
(UNIX timestamp) The time when the contact last messaged in.
(UNIX timestamp) The time when the contact was last messaged.
(UNIX timestamp) The time when the contact last opened an email.
(UNIX timestamp) The time when the contact last clicked a link in an email.
A preferred language setting for the contact, used by the Intercom Messenger even if their browser settings change.
The version of the browser which the contact is using.
The language set by the browser which the contact is using.
The name of the Android app which the contact is using.
The version of the Android app which the contact is using.
The version of the Android OS which the contact is using.
The version of the Android SDK which the contact is using.
(UNIX timestamp) The time when the contact was last seen on an Android device.
The version of the iOS app which the contact is using.
The version of the iOS SDK which the contact is using.
(UNIX timestamp) The last time the contact used the iOS app.
An object containing tags meta data about the tags that a contact has. Up to 10 will be displayed here. Use the url to get more.
An object containing notes meta data about the notes that a contact has. Up to 10 will be displayed here. Use the url to get more.
An object with metadata about companies attached to a contact . Up to 10 will be displayed here. Use the url to get more.
{ "type": "contact", "id": "6762f0cd1bb69f9f2193bb7c", "workspace_id": "this_is_an_id279_that_should_be_at_least_", "external_id": "70", "role": "user", "email": "joebloggs@intercom.io", "phone": null, "formatted_phone": null, "name": "joe bloggs", "avatar": null, "owner_id": null, "social_profiles": { "type": "list", "data": [] }, "has_hard_bounced": false, "marked_email_as_spam": false, "unsubscribed_from_emails": false, "created_at": 1734537421, "updated_at": 1734537422, "signed_up_at": 1734537421, "last_seen_at": null, "last_replied_at": null, "last_contacted_at": null, "last_email_opened_at": null, "last_email_clicked_at": null, "language_override": null, "browser": null, "browser_version": null, "browser_language": null, "os": null, "location": { "type": "location", "country": null, "region": null, "city": null, "country_code": null, "continent_code": null }, "android_app_name": null, "android_app_version": null, "android_device": null, "android_os_version": null, "android_sdk_version": null, "android_last_seen_at": null, "ios_app_name": null, "ios_app_version": null, "ios_device": null, "ios_os_version": null, "ios_sdk_version": null, "ios_last_seen_at": null, "custom_attributes": {}, "tags": { "type": "list", "data": [], "url": "/contacts/6762f0cd1bb69f9f2193bb7c/tags", "total_count": 0, "has_more": false }, "notes": { "type": "list", "data": [], "url": "/contacts/6762f0cd1bb69f9f2193bb7c/notes", "total_count": 0, "has_more": false }, "companies": { "type": "list", "data": [], "url": "/contacts/6762f0cd1bb69f9f2193bb7c/companies", "total_count": 0, "has_more": false }, "opted_out_subscription_types": { "type": "list", "data": [], "url": "/contacts/6762f0cd1bb69f9f2193bb7c/subscriptions", "total_count": 0, "has_more": false }, "opted_in_subscription_types": { "type": "list", "data": [], "url": "/contacts/6762f0cd1bb69f9f2193bb7c/subscriptions", "total_count": 0, "has_more": false }, "utm_campaign": null, "utm_content": null, "utm_medium": null, "utm_source": null, "utm_term": null, "referrer": null, "enabled_push_messaging": null }
You can update an existing conversation.
If you want to reply to a coveration or take an action such as assign, unassign, open, close or snooze, take a look at the reply and manage endpoints.
This endpoint handles both conversation updates and custom object associations.
See update a conversation with an association to a custom object instance
in the request/response examples to see the custom object association format.
curl -i -X PUT \
'https://api.intercom.io/conversations/123?display_as=plaintext' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-H 'Intercom-Version: Unstable' \
-d '{
"read": true,
"title": "new conversation title",
"custom_attributes": {
"issue_type": "Billing",
"priority": "High"
}
}'
update a conversation with an association to a custom object instance
The last time a Contact responded to an Admin. In other words, the time a customer started waiting for a response. Set to null if last reply is from an Admin.
If set this is the time in the future when this conversation will be marked as open. i.e. it will be in a snoozed state until this time. i.e. it will be in a snoozed state until this time.
If marked as priority, it will return priority or else not_priority.
The id of the admin assigned to the conversation. If it's not assigned to an admin it will return null.
The id of the team assigned to the conversation. If it's not assigned to a team it will return null.
The Conversation Rating object which contains information on the rating and/or remark added by a Contact and the Admin assigned to the conversation.
The type of the conversation part that started this conversation. Can be Contact, Admin, Campaign, Automated or Operator initiated.
The list of contacts (users or leads) involved in this conversation. This will only contain one customer unless more were added via the group conversation feature.
The list of teammates who participated in the conversation (wrote at least one conversation part).
An object containing the different custom attributes associated to the conversation as key-value pairs. For relationship attributes the value will be a list of custom object instance models.
An object containing information on the first users message. For a contact initiated message this will represent the users original message.
The SLA Applied object contains the details for which SLA has been applied to this conversation. Important: if there are any canceled sla_events for the conversation - meaning an SLA has been manually removed from a conversation, the sla_status will always be returned as null.
A Statistics object containing all information required for reporting, with timestamps and calculated metrics.
A list of Conversation Part objects for each part message in the conversation. This is only returned when Retrieving a Conversation, and ignored when Listing all Conversations. There is a limit of 500 parts.
An object containing metadata about linked conversations and linked tickets. Up to 1000 can be returned.
Indicates whether the AI Agent participated in the conversation.
{ "type": "conversation", "id": "507", "created_at": 1734537521, "updated_at": 1734537523, "waiting_since": null, "snoozed_until": null, "source": { "type": "conversation", "id": "403918338", "delivered_as": "admin_initiated", "subject": "", "body": "<p>this is the message body</p>", "author": { … }, "attachments": [], "url": null, "redacted": false }, "contacts": { "type": "contact.list", "contacts": [ … ] }, "first_contact_reply": null, "admin_assignee_id": null, "team_assignee_id": null, "open": false, "state": "closed", "read": true, "tags": { "type": "tag.list", "tags": [] }, "priority": "not_priority", "sla_applied": null, "statistics": null, "conversation_rating": null, "teammates": null, "title": null, "custom_attributes": { "issue_type": "Billing", "priority": "High" }, "topics": {}, "ticket": null, "linked_objects": { "type": "list", "data": [], "total_count": 0, "has_more": false }, "ai_agent": null, "ai_agent_participated": false, "conversation_parts": { "type": "conversation_part.list", "conversation_parts": [ … ], "total_count": 2 } }
A unique identifier for the Custom Object instance in the external system it originated from.
The time when the Custom Object instance was created in the external system it originated from.
The time when the Custom Object instance was last updated in the external system it originated from.
curl -i -X POST \
https://api.intercom.io/custom_object_instances/Order \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-H 'Intercom-Version: Unstable' \
-d '{
"external_id": "123",
"external_created_at": 1392036272,
"external_updated_at": 1392036272,
"custom_attributes": {
"order_number": "ORDER-12345",
"total_amount": 99.99
}
}'
successful
The id you have defined for the custom object instance.
The time when the Custom Object instance was created in the external system it originated from.
The time when the Custom Object instance was last updated in the external system it originated from.
The time the attribute was created as a UTC Unix timestamp
The time the attribute was last updated as a UTC Unix timestamp
The identifier of the custom object type that defines the structure of the custom object instance.
{ "id": "22", "type": "Order", "custom_attributes": { "order_number": "ORDER-12345", "total_amount": 99.99 }, "external_id": "123", "external_created_at": 1392036272, "external_updated_at": 1392036272, "created_at": 1734537745, "updated_at": 1734537745 }
curl -i -X GET \
'https://api.intercom.io/custom_object_instances/Order?external_id=string' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Intercom-Version: Unstable'
successful
The id you have defined for the custom object instance.
The time when the Custom Object instance was created in the external system it originated from.
The time when the Custom Object instance was last updated in the external system it originated from.
The time the attribute was created as a UTC Unix timestamp
The time the attribute was last updated as a UTC Unix timestamp
The identifier of the custom object type that defines the structure of the custom object instance.
{ "id": "24", "type": "Order", "custom_attributes": { "order_number": "ORDER-12345", "total_amount": 99.99 }, "external_id": "123", "external_created_at": null, "external_updated_at": null, "created_at": 1734537748, "updated_at": 1734537748 }
curl -i -X DELETE \
'https://api.intercom.io/custom_object_instances/Order?external_id=string' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Intercom-Version: Unstable'
{ "id": "26", "object": "Order", "deleted": true }
curl -i -X GET \
'https://api.intercom.io/custom_object_instances/Order/{id}' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Intercom-Version: Unstable'
successful
The id you have defined for the custom object instance.
The time when the Custom Object instance was created in the external system it originated from.
The time when the Custom Object instance was last updated in the external system it originated from.
The time the attribute was created as a UTC Unix timestamp
The time the attribute was last updated as a UTC Unix timestamp
The identifier of the custom object type that defines the structure of the custom object instance.
{ "id": "25", "type": "Order", "custom_attributes": { "order_number": "ORDER-12345", "total_amount": 99.99 }, "external_id": "123", "external_created_at": null, "external_updated_at": null, "created_at": 1734537750, "updated_at": 1734537750 }
curl -i -X DELETE \
'https://api.intercom.io/custom_object_instances/Order/{id}' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Intercom-Version: Unstable'
{ "id": "26", "object": "Order", "deleted": true }