Intercom API (2.11)

The intercom API reference.

Download OpenAPI description
Languages
Servers
The production API server
https://api.intercom.io/
The european API server
https://api.eu.intercom.io/
The australian API server
https://api.au.intercom.io/

Admins

Everything about your Admins

Operations

Articles

Everything about your Articles

Operations

Companies

Everything about your Companies

Operations

Contacts

Everything about your contacts

Operations

Conversations

Everything about your Conversations

Operations

Data Attributes

Everything about your Data Attributes

Operations

Data Events

Everything about your Data Events

Operations

Data Export

Everything about your Data Exports

Operations

Help Center

Everything about your Help Center

Operations

Messages

Everything about your messages

Operations

News

Everything about your News

Operations

Notes

Everything about your Notes

Operations

Segments

Everything about your Segments

Operations

Subscription Types

Everything about subscription types

Operations

Switch

Everything about Switch

Operations

Tags

Everything about tags

Operations

Teams

Everything about your Teams

Operations

Ticket Type Attributes

Everything about your ticket type attributes

Operations

Ticket Types

Everything about your ticket types

Operations

Tickets

Everything about your tickets

Operations

Visitors

Everything about your Visitors

Operations

Models

Activity Log

Activities performed by Admins.

idstring

The id representing the activity.

Example: "6"
performed_byobject

Details about the Admin involved in the activity.

metadataobject or null(Activity Log Metadata)

Additional data provided about Admin activity.

created_atinteger(date-time)

The time the activity was created.

Example: 1671028894
activity_typestring
Enum"admin_assignment_limit_change""admin_away_mode_change""admin_deletion""admin_deprovisioned""admin_impersonation_end""admin_impersonation_start""admin_invite_change""admin_invite_creation""admin_invite_deletion""admin_login_failure"
Example: "app_name_change"
activity_descriptionstring

A sentence or two describing the activity.

Example: "Admin updated the app's name to \"My App\"."
{ "id": "6", "performed_by": { "type": "admin", "id": "1295", "email": "john@example.com", "ip": "198.51.100.255" }, "metadata": { "sign_in_method": "email_password", "external_id": "f3b87a2e09d514c6c2e79b9a", "away_mode": true, "away_status_reason": "😌 On a break", "reassign_conversations": false, "source": "admin update from web - Admin id: 93", "auto_changed": false, "update_by": 93, "update_by_name": "Joe Bloggs" }, "created_at": 1671028894, "activity_type": "app_name_change", "activity_description": "Admin updated the app's name to \"My App\"." }

Paginated Response

A paginated list of activity logs.

typestring

String representing the object's type. Always has the value activity_log.list.

Example: "activity_log.list"
pagesobject or null(Cursor based pages)

Cursor-based pagination is a technique used in the Intercom API to navigate through large amounts of data. A "cursor" or pointer is used to keep track of the current position in the result set, allowing the API to return the data in small chunks or "pages" as needed.

activity_logsArray of objects or null(Activity Log)

An array of activity logs

{ "type": "activity_log.list", "pages": { "type": "pages", "page": 1, "next": {}, "per_page": 2, "total_pages": 13 }, "activity_logs": [ {} ] }

Activity Log Metadata

Additional data provided about Admin activity.

sign_in_methodstring or null

The way the admin signed in.

Example: "email_password"
external_idstring or null

The unique identifier for the contact which is provided by the Client.

Example: "f3b87a2e09d514c6c2e79b9a"
away_modeboolean or null

The away mode status which is set to true when away and false when returned.

Example: true
away_status_reasonstring or null

The reason the Admin is away.

Example: "😌 On a break"
reassign_conversationsboolean or null

Indicates if conversations should be reassigned while an Admin is away.

Example: false
sourcestring or null

The action that initiated the status change.

Example: "admin update from web - Admin id: 93"
auto_changedstring or null

Indicates if the status was changed automatically or manually.

Example: false
update_byinteger or null

The ID of the Admin who initiated the activity.

Example: 93
update_by_namestring or null

The name of the Admin who initiated the activity.

Example: "Joe Bloggs"
{ "sign_in_method": "email_password", "external_id": "f3b87a2e09d514c6c2e79b9a", "away_mode": true, "away_status_reason": "😌 On a break", "reassign_conversations": false, "source": "admin update from web - Admin id: 93", "auto_changed": false, "update_by": 93, "update_by_name": "Joe Bloggs" }

Addressable List

A list used to access other resources from a parent model.

typestring(uri)

The addressable object type

Example: "note"
idstring

The id of the addressable object

Example: "123"
urlstring(uri)

Url to get more company resources for this contact

Example: "/contacts/5ba682d23d7cf92bef87bfd4/notes"
{ "type": "note", "id": "123", "url": "/contacts/5ba682d23d7cf92bef87bfd4/notes" }

Admins

A list of admins associated with a given workspace.

typestring

String representing the object's type. Always has the value admin.list.

Example: "admin.list"
adminsArray of objects or null(Admin)

A list of admins associated with a given workspace.

{ "type": "admin.list", "admins": [ {} ] }

Admin Priority Level

Admin priority levels for the team

primary_admin_idsArray of integers or null

The primary admin ids for the team

Example: [493881]
secondary_admin_idsArray of integers or null

The secondary admin ids for the team

Example: [814865]
{ "primary_admin_ids": [ 493881 ], "secondary_admin_ids": [ 814865 ] }

Admin Reply

Payload of the request to reply on behalf of an admin

message_typestringrequired
Enum"comment""note"
typestringrequired
Value"admin"
Example: "admin"
bodystring

The text body of the reply. Notes accept some HTML formatting. Must be present for comment and note message types.

Example: "Hello there!"
admin_idstringrequired

The id of the admin who is authoring the comment.

Example: "3156780"
created_atinteger

The time the reply was created. If not provided, the current time will be used.

Example: 1590000000
attachment_urlsArray of strings(uri)<= 10 items

A list of image URLs that will be added as attachments. You can include up to 10 URLs.

attachment_filesArray of objects(Conversation attachment files)<= 10 items

A list of files that will be added as attachments. You can include up to 10 files

{ "message_type": "comment", "type": "admin", "body": "Hello there!", "admin_id": "3156780", "created_at": 1590000000, "attachment_urls": [ "http://example.com" ], "attachment_files": [ {} ] }

Admin Reply on ticket

Payload of the request to reply on behalf of an admin

message_typestringrequired
Enum"comment""note""quick_reply"
Example: "comment"
typestringrequired
Value"admin"
Example: "admin"
bodystring

The text body of the reply. Notes accept some HTML formatting. Must be present for comment and note message types.

Example: "Hello there!"
admin_idstringrequired

The id of the admin who is authoring the comment.

Example: "3156780"
created_atinteger

The time the reply was created. If not provided, the current time will be used.

Example: 1590000000
reply_optionsArray of objects(Quick Reply Options)

The quick reply options to display. Must be present for quick_reply message types.

attachment_urlsArray of strings(uri)<= 10 items

A list of image URLs that will be added as attachments. You can include up to 10 URLs.

{ "message_type": "comment", "type": "admin", "body": "Hello there!", "admin_id": "3156780", "created_at": 1590000000, "reply_options": [ {} ], "attachment_urls": [ "http://example.com" ] }

Admin

Admins are the teammate accounts that have access to a workspace

typestring

String representing the object's type. Always has the value admin.

Example: "admin"
idstring

The id representing the admin.

Example: "1295"
namestring

The name of the admin.

Example: "Hoban Washburne"
emailstring

The email of the admin.

Example: "wash@serenity.io"
job_titlestring

The job title of the admin.

Example: "Philosopher"
away_mode_enabledboolean

Identifies if this admin is currently set in away mode.

Example: false
away_mode_reassignboolean

Identifies if this admin is set to automatically reassign new conversations to the apps default inbox.

Example: false
has_inbox_seatboolean

Identifies if this admin has a paid inbox seat to restrict/allow features that require them.

Example: true
team_idsArray of integers

This is a list of ids of the teams that this admin is part of.

Example: [814865]
avatarobject

This object represents the avatar associated with the admin.

email_verifiedboolean or null

Identifies if this admin's email is verified.

Example: true
appobject or null(App)

App is a workspace on Intercom

{ "type": "admin", "id": "1295", "name": "Hoban Washburne", "email": "wash@serenity.io", "job_title": "Philosopher", "away_mode_enabled": false, "away_mode_reassign": false, "has_inbox_seat": true, "team_ids": [ 814865 ], "avatar": { "type": "avatar", "image_url": "https://example.com/avatar.png" }, "email_verified": true, "app": { "type": "app", "id_code": "xyz789", "name": "ACME", "region": "US", "timezone": "America/Los_Angeles", "created_at": 1671465577, "identity_verification": false } }

App

App is a workspace on Intercom

typestring
Default "app"
Example: "app"
id_codestring

The id of the app.

Example: "xyz789"
namestring

The name of the app.

Example: "ACME"
regionstring

The Intercom region the app is located in.

Example: "US"
timezonestring

The timezone of the region where the app is located.

Example: "America/Los_Angeles"
created_atinteger

When the app was created.

Example: 1671465577
identity_verificationboolean

Whether or not the app uses identity verification.

Example: false
{ "type": "app", "id_code": "xyz789", "name": "ACME", "region": "US", "timezone": "America/Los_Angeles", "created_at": 1671465577, "identity_verification": false }

Article Content

The Content of an Article.

typestring or null

The type of object - article_content .

Enumnull"article_content"
Example: "article_content"
titlestring

The title of the article.

Example: "How to create a new article"
descriptionstring

The description of the article.

Example: "This article will show you how to create a new article."
bodystring

The body of the article.

Example: "This is the body of the article."
author_idinteger

The ID of the author of the article.

Example: "5017691"
statestring

Whether the article is published or is a draft .

Enum"published""draft"
Example: "draft"
created_atinteger(date-time)

The time when the article was created (seconds).

Example: 1663597223
updated_atinteger(date-time)

The time when the article was last updated (seconds).

Example: 1663597260
urlstring

The URL of the article.

Example: "http://intercom.test/help/en/articles/3-default-language"
{ "type": "article_content", "title": "How to create a new article", "description": "This article will show you how to create a new article.", "body": "This is the body of the article.", "author_id": "5017691", "state": "draft", "created_at": 1663597223, "updated_at": 1663597260, "url": "http://intercom.test/help/en/articles/3-default-language" }

Articles

This will return a list of articles for the App.

typestring

The type of the object - list.

Value"list"
Example: "list"
pagesobject or null(Cursor based pages)

Cursor-based pagination is a technique used in the Intercom API to navigate through large amounts of data. A "cursor" or pointer is used to keep track of the current position in the result set, allowing the API to return the data in small chunks or "pages" as needed.

total_countinteger

A count of the total number of articles.

Example: 1
dataArray of objects(Articles)

An array of Article objects

{ "type": "list", "pages": { "type": "pages", "page": 1, "next": {}, "per_page": 2, "total_pages": 13 }, "total_count": 1, "data": [ {} ] }

Article Statistics

The statistics of an article.

typestring

The type of object - article_statistics.

Default "article_statistics"
Value"article_statistics"
Example: "article_statistics"
viewsinteger

The number of total views the article has received.

Example: 10
conversionsinteger

The number of conversations started from the article.

Example: 0
reactionsinteger

The number of total reactions the article has received.

Example: 10
happy_reaction_percentagenumber(float)

The percentage of happy reactions the article has received against other types of reaction.

Example: 40
neutral_reaction_percentagenumber(float)

The percentage of neutral reactions the article has received against other types of reaction.

Example: 40
sad_reaction_percentagenumber(float)

The percentage of sad reactions the article has received against other types of reaction.

Example: 20
{ "type": "article_statistics", "views": 10, "conversions": 0, "reactions": 10, "happy_reaction_percentage": 40, "neutral_reaction_percentage": 40, "sad_reaction_percentage": 20 }

Article Translated Content

The Translated Content of an Article. The keys are the locale codes and the values are the translated content of the article.

typestring or null

The type of object - article_translated_content.

Enumnull"article_translated_content"
Example: "article_translated_content"
arobject or null(Article Content)

The Content of an Article.

bgobject or null(Article Content)

The Content of an Article.

bsobject or null(Article Content)

The Content of an Article.

caobject or null(Article Content)

The Content of an Article.

csobject or null(Article Content)

The Content of an Article.

daobject or null(Article Content)

The Content of an Article.

deobject or null(Article Content)

The Content of an Article.

elobject or null(Article Content)

The Content of an Article.

enobject or null(Article Content)

The Content of an Article.

esobject or null(Article Content)

The Content of an Article.

etobject or null(Article Content)

The Content of an Article.

fiobject or null(Article Content)

The Content of an Article.

frobject or null(Article Content)

The Content of an Article.

heobject or null(Article Content)

The Content of an Article.

hrobject or null(Article Content)

The Content of an Article.

huobject or null(Article Content)

The Content of an Article.

idobject or null(Article Content)

The Content of an Article.

itobject or null(Article Content)

The Content of an Article.

jaobject or null(Article Content)

The Content of an Article.

koobject or null(Article Content)

The Content of an Article.

ltobject or null(Article Content)

The Content of an Article.

lvobject or null(Article Content)

The Content of an Article.

mnobject or null(Article Content)

The Content of an Article.

nbobject or null(Article Content)

The Content of an Article.

nlobject or null(Article Content)

The Content of an Article.

plobject or null(Article Content)

The Content of an Article.

ptobject or null(Article Content)

The Content of an Article.

roobject or null(Article Content)

The Content of an Article.

ruobject or null(Article Content)

The Content of an Article.

slobject or null(Article Content)

The Content of an Article.

srobject or null(Article Content)

The Content of an Article.

svobject or null(Article Content)

The Content of an Article.

trobject or null(Article Content)

The Content of an Article.

viobject or null(Article Content)

The Content of an Article.

pt-BRobject or null(Article Content)

The Content of an Article.

zh-CNobject or null(Article Content)

The Content of an Article.

zh-TWobject or null(Article Content)

The Content of an Article.

{ "type": "article_translated_content", "ar": { "type": "article_content", "title": "How to create a new article", "description": "This article will show you how to create a new article.", "body": "This is the body of the article.", "author_id": "5017691", "state": "draft", "created_at": 1663597223, "updated_at": 1663597260, "url": "http://intercom.test/help/en/articles/3-default-language" }, "bg": { "type": "article_content", "title": "How to create a new article", "description": "This article will show you how to create a new article.", "body": "This is the body of the article.", "author_id": "5017691", "state": "draft", "created_at": 1663597223, "updated_at": 1663597260, "url": "http://intercom.test/help/en/articles/3-default-language" }, "bs": { "type": "article_content", "title": "How to create a new article", "description": "This article will show you how to create a new article.", "body": "This is the body of the article.", "author_id": "5017691", "state": "draft", "created_at": 1663597223, "updated_at": 1663597260, "url": "http://intercom.test/help/en/articles/3-default-language" }, "ca": { "type": "article_content", "title": "How to create a new article", "description": "This article will show you how to create a new article.", "body": "This is the body of the article.", "author_id": "5017691", "state": "draft", "created_at": 1663597223, "updated_at": 1663597260, "url": "http://intercom.test/help/en/articles/3-default-language" }, "cs": { "type": "article_content", "title": "How to create a new article", "description": "This article will show you how to create a new article.", "body": "This is the body of the article.", "author_id": "5017691", "state": "draft", "created_at": 1663597223, "updated_at": 1663597260, "url": "http://intercom.test/help/en/articles/3-default-language" }, "da": { "type": "article_content", "title": "How to create a new article", "description": "This article will show you how to create a new article.", "body": "This is the body of the article.", "author_id": "5017691", "state": "draft", "created_at": 1663597223, "updated_at": 1663597260, "url": "http://intercom.test/help/en/articles/3-default-language" }, "de": { "type": "article_content", "title": "How to create a new article", "description": "This article will show you how to create a new article.", "body": "This is the body of the article.", "author_id": "5017691", "state": "draft", "created_at": 1663597223, "updated_at": 1663597260, "url": "http://intercom.test/help/en/articles/3-default-language" }, "el": { "type": "article_content", "title": "How to create a new article", "description": "This article will show you how to create a new article.", "body": "This is the body of the article.", "author_id": "5017691", "state": "draft", "created_at": 1663597223, "updated_at": 1663597260, "url": "http://intercom.test/help/en/articles/3-default-language" }, "en": { "type": "article_content", "title": "How to create a new article", "description": "This article will show you how to create a new article.", "body": "This is the body of the article.", "author_id": "5017691", "state": "draft", "created_at": 1663597223, "updated_at": 1663597260, "url": "http://intercom.test/help/en/articles/3-default-language" }, "es": { "type": "article_content", "title": "How to create a new article", "description": "This article will show you how to create a new article.", "body": "This is the body of the article.", "author_id": "5017691", "state": "draft", "created_at": 1663597223, "updated_at": 1663597260, "url": "http://intercom.test/help/en/articles/3-default-language" }, "et": { "type": "article_content", "title": "How to create a new article", "description": "This article will show you how to create a new article.", "body": "This is the body of the article.", "author_id": "5017691", "state": "draft", "created_at": 1663597223, "updated_at": 1663597260, "url": "http://intercom.test/help/en/articles/3-default-language" }, "fi": { "type": "article_content", "title": "How to create a new article", "description": "This article will show you how to create a new article.", "body": "This is the body of the article.", "author_id": "5017691", "state": "draft", "created_at": 1663597223, "updated_at": 1663597260, "url": "http://intercom.test/help/en/articles/3-default-language" }, "fr": { "type": "article_content", "title": "How to create a new article", "description": "This article will show you how to create a new article.", "body": "This is the body of the article.", "author_id": "5017691", "state": "draft", "created_at": 1663597223, "updated_at": 1663597260, "url": "http://intercom.test/help/en/articles/3-default-language" }, "he": { "type": "article_content", "title": "How to create a new article", "description": "This article will show you how to create a new article.", "body": "This is the body of the article.", "author_id": "5017691", "state": "draft", "created_at": 1663597223, "updated_at": 1663597260, "url": "http://intercom.test/help/en/articles/3-default-language" }, "hr": { "type": "article_content", "title": "How to create a new article", "description": "This article will show you how to create a new article.", "body": "This is the body of the article.", "author_id": "5017691", "state": "draft", "created_at": 1663597223, "updated_at": 1663597260, "url": "http://intercom.test/help/en/articles/3-default-language" }, "hu": { "type": "article_content", "title": "How to create a new article", "description": "This article will show you how to create a new article.", "body": "This is the body of the article.", "author_id": "5017691", "state": "draft", "created_at": 1663597223, "updated_at": 1663597260, "url": "http://intercom.test/help/en/articles/3-default-language" }, "id": { "type": "article_content", "title": "How to create a new article", "description": "This article will show you how to create a new article.", "body": "This is the body of the article.", "author_id": "5017691", "state": "draft", "created_at": 1663597223, "updated_at": 1663597260, "url": "http://intercom.test/help/en/articles/3-default-language" }, "it": { "type": "article_content", "title": "How to create a new article", "description": "This article will show you how to create a new article.", "body": "This is the body of the article.", "author_id": "5017691", "state": "draft", "created_at": 1663597223, "updated_at": 1663597260, "url": "http://intercom.test/help/en/articles/3-default-language" }, "ja": { "type": "article_content", "title": "How to create a new article", "description": "This article will show you how to create a new article.", "body": "This is the body of the article.", "author_id": "5017691", "state": "draft", "created_at": 1663597223, "updated_at": 1663597260, "url": "http://intercom.test/help/en/articles/3-default-language" }, "ko": { "type": "article_content", "title": "How to create a new article", "description": "This article will show you how to create a new article.", "body": "This is the body of the article.", "author_id": "5017691", "state": "draft", "created_at": 1663597223, "updated_at": 1663597260, "url": "http://intercom.test/help/en/articles/3-default-language" }, "lt": { "type": "article_content", "title": "How to create a new article", "description": "This article will show you how to create a new article.", "body": "This is the body of the article.", "author_id": "5017691", "state": "draft", "created_at": 1663597223, "updated_at": 1663597260, "url": "http://intercom.test/help/en/articles/3-default-language" }, "lv": { "type": "article_content", "title": "How to create a new article", "description": "This article will show you how to create a new article.", "body": "This is the body of the article.", "author_id": "5017691", "state": "draft", "created_at": 1663597223, "updated_at": 1663597260, "url": "http://intercom.test/help/en/articles/3-default-language" }, "mn": { "type": "article_content", "title": "How to create a new article", "description": "This article will show you how to create a new article.", "body": "This is the body of the article.", "author_id": "5017691", "state": "draft", "created_at": 1663597223, "updated_at": 1663597260, "url": "http://intercom.test/help/en/articles/3-default-language" }, "nb": { "type": "article_content", "title": "How to create a new article", "description": "This article will show you how to create a new article.", "body": "This is the body of the article.", "author_id": "5017691", "state": "draft", "created_at": 1663597223, "updated_at": 1663597260, "url": "http://intercom.test/help/en/articles/3-default-language" }, "nl": { "type": "article_content", "title": "How to create a new article", "description": "This article will show you how to create a new article.", "body": "This is the body of the article.", "author_id": "5017691", "state": "draft", "created_at": 1663597223, "updated_at": 1663597260, "url": "http://intercom.test/help/en/articles/3-default-language" }, "pl": { "type": "article_content", "title": "How to create a new article", "description": "This article will show you how to create a new article.", "body": "This is the body of the article.", "author_id": "5017691", "state": "draft", "created_at": 1663597223, "updated_at": 1663597260, "url": "http://intercom.test/help/en/articles/3-default-language" }, "pt": { "type": "article_content", "title": "How to create a new article", "description": "This article will show you how to create a new article.", "body": "This is the body of the article.", "author_id": "5017691", "state": "draft", "created_at": 1663597223, "updated_at": 1663597260, "url": "http://intercom.test/help/en/articles/3-default-language" }, "ro": { "type": "article_content", "title": "How to create a new article", "description": "This article will show you how to create a new article.", "body": "This is the body of the article.", "author_id": "5017691", "state": "draft", "created_at": 1663597223, "updated_at": 1663597260, "url": "http://intercom.test/help/en/articles/3-default-language" }, "ru": { "type": "article_content", "title": "How to create a new article", "description": "This article will show you how to create a new article.", "body": "This is the body of the article.", "author_id": "5017691", "state": "draft", "created_at": 1663597223, "updated_at": 1663597260, "url": "http://intercom.test/help/en/articles/3-default-language" }, "sl": { "type": "article_content", "title": "How to create a new article", "description": "This article will show you how to create a new article.", "body": "This is the body of the article.", "author_id": "5017691", "state": "draft", "created_at": 1663597223, "updated_at": 1663597260, "url": "http://intercom.test/help/en/articles/3-default-language" }, "sr": { "type": "article_content", "title": "How to create a new article", "description": "This article will show you how to create a new article.", "body": "This is the body of the article.", "author_id": "5017691", "state": "draft", "created_at": 1663597223, "updated_at": 1663597260, "url": "http://intercom.test/help/en/articles/3-default-language" }, "sv": { "type": "article_content", "title": "How to create a new article", "description": "This article will show you how to create a new article.", "body": "This is the body of the article.", "author_id": "5017691", "state": "draft", "created_at": 1663597223, "updated_at": 1663597260, "url": "http://intercom.test/help/en/articles/3-default-language" }, "tr": { "type": "article_content", "title": "How to create a new article", "description": "This article will show you how to create a new article.", "body": "This is the body of the article.", "author_id": "5017691", "state": "draft", "created_at": 1663597223, "updated_at": 1663597260, "url": "http://intercom.test/help/en/articles/3-default-language" }, "vi": { "type": "article_content", "title": "How to create a new article", "description": "This article will show you how to create a new article.", "body": "This is the body of the article.", "author_id": "5017691", "state": "draft", "created_at": 1663597223, "updated_at": 1663597260, "url": "http://intercom.test/help/en/articles/3-default-language" }, "pt-BR": { "type": "article_content", "title": "How to create a new article", "description": "This article will show you how to create a new article.", "body": "This is the body of the article.", "author_id": "5017691", "state": "draft", "created_at": 1663597223, "updated_at": 1663597260, "url": "http://intercom.test/help/en/articles/3-default-language" }, "zh-CN": { "type": "article_content", "title": "How to create a new article", "description": "This article will show you how to create a new article.", "body": "This is the body of the article.", "author_id": "5017691", "state": "draft", "created_at": 1663597223, "updated_at": 1663597260, "url": "http://intercom.test/help/en/articles/3-default-language" }, "zh-TW": { "type": "article_content", "title": "How to create a new article", "description": "This article will show you how to create a new article.", "body": "This is the body of the article.", "author_id": "5017691", "state": "draft", "created_at": 1663597223, "updated_at": 1663597260, "url": "http://intercom.test/help/en/articles/3-default-language" } }

Assign Conversation Request

Payload of the request to assign a conversation

message_typestringrequired
Value"assignment"
Example: "assignment"
typestringrequired
Enum"admin""team"
Example: "admin"
admin_idstringrequired

The id of the admin who is performing the action.

Example: "12345"
assignee_idstringrequired

The id of the admin or team which will be assigned the conversation. A conversation can be assigned both an admin and a team.\nSet 0 if you want this assign to no admin or team (ie. Unassigned).

Example: "4324241"
bodystring

Optionally you can send a response in the conversation when it is assigned.

Example: "Let me pass you over to one of my colleagues."
{ "message_type": "assignment", "type": "admin", "admin_id": "12345", "assignee_id": "4324241", "body": "Let me pass you over to one of my colleagues." }

Assign Conversation Request

Payload of the request to assign a conversation

admin_idstring

The id of the admin who is adding the new participant.

Example: "12345"
customerIntercom User ID (object) or User ID (object) or Email (object)
One of:
{ "admin_id": "12345", "customer": { "intercom_user_id": "6329bd9ffe4e2e91dac76188", "customer": {} } }

Close Conversation Request

Payload of the request to close a conversation

message_typestringrequired
Value"close"
Example: "close"
typestringrequired
Value"admin"
Example: "admin"
admin_idstringrequired

The id of the admin who is performing the action.

Example: "12345"
bodystring

Optionally you can leave a message in the conversation to provide additional context to the user and other teammates.

Example: " This conversation is now closed!"
{ "message_type": "close", "type": "admin", "admin_id": "12345", "body": " This conversation is now closed!" }

Collections

This will return a list of Collections for the App.

typestring

The type of the object - list.

Value"list"
Example: "list"
pagesobject or null(Cursor based pages)

Cursor-based pagination is a technique used in the Intercom API to navigate through large amounts of data. A "cursor" or pointer is used to keep track of the current position in the result set, allowing the API to return the data in small chunks or "pages" as needed.

total_countinteger

A count of the total number of collections.

Example: 1
dataArray of objects(Collection)

An array of collection objects

{ "type": "list", "pages": { "type": "pages", "page": 1, "next": {}, "per_page": 2, "total_pages": 13 }, "total_count": 1, "data": [ {} ] }

Company Attached Contacts

A list of Contact Objects

typestring

The type of object - list

Value"list"
Example: "list"
dataArray of objects(Contact)

An array containing Contact Objects

total_countinteger

The total number of contacts

Example: 100
pagesobject or null(Cursor based pages)

Cursor-based pagination is a technique used in the Intercom API to navigate through large amounts of data. A "cursor" or pointer is used to keep track of the current position in the result set, allowing the API to return the data in small chunks or "pages" as needed.

{ "type": "list", "data": [ {} ], "total_count": 100, "pages": { "type": "pages", "page": 1, "next": {}, "per_page": 2, "total_pages": 13 } }

Company Attached Segments

A list of Segment Objects

typestring

The type of object - list

Value"list"
Example: "list"
dataArray of objects(Segment)

An array containing Segment Objects

{ "type": "list", "data": [ {} ] }

Companies

This will return a list of companies for the App.

typestring

The type of object - list.

Value"list"
Example: "list"
pagesobject or null(Cursor based pages)

Cursor-based pagination is a technique used in the Intercom API to navigate through large amounts of data. A "cursor" or pointer is used to keep track of the current position in the result set, allowing the API to return the data in small chunks or "pages" as needed.

total_countinteger

The total number of companies.

Example: 100
dataArray of objects(Company)

An array containing Company Objects.

{ "type": "list", "pages": { "type": "pages", "page": 1, "next": {}, "per_page": 2, "total_pages": 13 }, "total_count": 100, "data": [ {} ] }

Company Scroll

Companies allow you to represent organizations using your product. Each company will have its own description and be associated with contacts. You can fetch, create, update and list companies.

typestring

The type of object - list

Value"list"
Example: "list"
dataArray of objects(Company)
pagesobject or null(Cursor based pages)

Cursor-based pagination is a technique used in the Intercom API to navigate through large amounts of data. A "cursor" or pointer is used to keep track of the current position in the result set, allowing the API to return the data in small chunks or "pages" as needed.

total_countinteger or null

The total number of companies

Example: 100
scroll_paramstring

The scroll parameter to use in the next request to fetch the next page of results.

Example: "25b649f7-4d33-4ef6-88f5-60e5b8244309"
{ "type": "list", "data": [ {} ], "pages": { "type": "pages", "page": 1, "next": {}, "per_page": 2, "total_pages": 13 }, "total_count": 100, "scroll_param": "25b649f7-4d33-4ef6-88f5-60e5b8244309" }

Contact Archived

archived contact object

typestring

always contact

Value"contact"
Example: "contact"
idstring

The unique identifier for the contact which is given by Intercom.

Example: "5ba682d23d7cf92bef87bfd4"
external_idstring or null

The unique identifier for the contact which is provided by the Client.

Example: "f3b87a2e09d514c6c2e79b9a"
archivedboolean

Whether the contact is archived or not.

Example: true
{ "type": "contact", "id": "5ba682d23d7cf92bef87bfd4", "external_id": "f3b87a2e09d514c6c2e79b9a", "archived": true }

Contact Attached Companies

A list of Company Objects

typestring

The type of object

Value"list"
Example: "list"
companiesArray of objects(Company)

An array containing Company Objects

total_countinteger

The total number of companies associated to this contact

Example: 100
pagesobject(Pagination Object)

The majority of list resources in the API are paginated to allow clients to traverse data over multiple requests.

Their responses are likely to contain a pages object that hosts pagination links which a client can use to paginate through the data without having to construct a query. The link relations for the pages field are as follows.

{ "type": "list", "companies": [ {} ], "total_count": 100, "pages": { "type": "pages", "page": 1, "next": "http://example.com", "per_page": 50, "total_pages": 1 } }

Contact companies

An object containing companies meta data about the companies that a contact has. Up to 10 will be displayed here. Use the url to get more.

urlstring(uri)

Url to get more company resources for this contact

Example: "/contacts/5ba682d23d7cf92bef87bfd4/companies"
total_countinteger

Int representing the total number of companyies attached to this contact

Example: 100
has_moreboolean

Whether there's more Addressable Objects to be viewed. If true, use the url to view all

Example: true
{ "url": "/contacts/5ba682d23d7cf92bef87bfd4/companies", "total_count": 100, "has_more": true }

Contact Deleted

deleted contact object

typestring

always contact

Value"contact"
Example: "contact"
idstring

The unique identifier for the contact which is given by Intercom.

Example: "5ba682d23d7cf92bef87bfd4"
external_idstring or null

The unique identifier for the contact which is provided by the Client.

Example: "f3b87a2e09d514c6c2e79b9a"
deletedboolean

Whether the contact is deleted or not.

Example: true
{ "type": "contact", "id": "5ba682d23d7cf92bef87bfd4", "external_id": "f3b87a2e09d514c6c2e79b9a", "deleted": true }

Contact List

Contacts are your users in Intercom.

typestring

Always list

Value"list"
Example: "list"
dataArray of objects(Contact)

The list of contact objects

total_countinteger

A count of the total number of objects.

Example: 100
pagesobject or null(Cursor based pages)

Cursor-based pagination is a technique used in the Intercom API to navigate through large amounts of data. A "cursor" or pointer is used to keep track of the current position in the result set, allowing the API to return the data in small chunks or "pages" as needed.

{ "type": "list", "data": [ {} ], "total_count": 100, "pages": { "type": "pages", "page": 1, "next": {}, "per_page": 2, "total_pages": 13 } }

Contact Location

An object containing location meta data about a Intercom contact.

typestring or null

Always location

Example: "location"
countrystring or null

The country that the contact is located in

Example: "Ireland"
regionstring or null

The overal region that the contact is located in

Example: "Dublin"
citystring or null

The city that the contact is located in

Example: "Dublin"
{ "type": "location", "country": "Ireland", "region": "Dublin", "city": "Dublin" }

Contact notes

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.

dataArray of objects(Addressable List)

This object represents the notes attached to a contact.

urlstring(uri)

Url to get more company resources for this contact

Example: "/contacts/5ba682d23d7cf92bef87bfd4/notes"
total_countinteger

Int representing the total number of companyies attached to this contact

Example: 100
has_moreboolean

Whether there's more Addressable Objects to be viewed. If true, use the url to view all

Example: true
{ "data": [ {} ], "url": "/contacts/5ba682d23d7cf92bef87bfd4/notes", "total_count": 100, "has_more": true }

Contact Reference

reference to contact object

typestring

always contact

Value"contact"
Example: "contact"
idstring

The unique identifier for the contact which is given by Intercom.

Example: "5ba682d23d7cf92bef87bfd4"
external_idstring or null

The unique identifier for the contact which is provided by the Client.

Example: "f3b87a2e09d514c6c2e79b9a"
{ "type": "contact", "id": "5ba682d23d7cf92bef87bfd4", "external_id": "f3b87a2e09d514c6c2e79b9a" }

Contact Reply Base Object

message_typestringrequired
Value"comment"
typestringrequired
Value"user"
bodystringrequired

The text body of the comment.

created_atinteger

The time the reply was created. If not provided, the current time will be used.

Example: 1590000000
attachment_urlsArray of strings(uri)(Attachment URLs)<= 10 items

A list of image URLs that will be added as attachments. You can include up to 10 URLs.

{ "message_type": "comment", "type": "user", "body": "string", "created_at": 1590000000, "attachment_urls": [ "http://example.com" ] }

Contact Reply

One of:

Payload of the request to reply on behalf of a contact using their intercom_user_id

intercom_user_idstringrequired

The identifier for the contact as given by Intercom.

attachment_filesArray of objects(Conversation attachment files)

A list of files that will be added as attachments.

message_typestringrequired
Value"comment"
typestringrequired
Value"user"
bodystringrequired

The text body of the comment.

created_atinteger

The time the reply was created. If not provided, the current time will be used.

Example: 1590000000
attachment_urlsArray of strings(uri)(Attachment URLs)<= 10 items

A list of image URLs that will be added as attachments. You can include up to 10 URLs.

{ "intercom_user_id": "string", "attachment_files": [ {} ], "message_type": "comment", "type": "user", "body": "string", "created_at": 1590000000, "attachment_urls": [ "http://example.com" ] }

Email

Payload of the request to reply on behalf of a contact using their email

emailstringrequired

The email you have defined for the user.

attachment_filesArray of objects(Conversation attachment files)

A list of files that will be added as attachments.

message_typestringrequired
Value"comment"
typestringrequired
Value"user"
bodystringrequired

The text body of the comment.

created_atinteger

The time the reply was created. If not provided, the current time will be used.

Example: 1590000000
attachment_urlsArray of strings(uri)(Attachment URLs)<= 10 items

A list of image URLs that will be added as attachments. You can include up to 10 URLs.

{ "email": "string", "attachment_files": [ {} ], "message_type": "comment", "type": "user", "body": "string", "created_at": 1590000000, "attachment_urls": [ "http://example.com" ] }

Intercom User ID

Payload of the request to reply on behalf of a contact using their intercom_user_id

intercom_user_idstringrequired

The identifier for the contact as given by Intercom.

attachment_filesArray of objects(Conversation attachment files)

A list of files that will be added as attachments.

message_typestringrequired
Value"comment"
typestringrequired
Value"user"
bodystringrequired

The text body of the comment.

created_atinteger

The time the reply was created. If not provided, the current time will be used.

Example: 1590000000
attachment_urlsArray of strings(uri)(Attachment URLs)<= 10 items

A list of image URLs that will be added as attachments. You can include up to 10 URLs.

{ "intercom_user_id": "string", "attachment_files": [ {} ], "message_type": "comment", "type": "user", "body": "string", "created_at": 1590000000, "attachment_urls": [ "http://example.com" ] }

Email

Payload of the request to reply on behalf of a contact using their email

emailstringrequired

The email you have defined for the user.

message_typestringrequired
Value"comment"
typestringrequired
Value"user"
bodystringrequired

The text body of the comment.

created_atinteger

The time the reply was created. If not provided, the current time will be used.

Example: 1590000000
attachment_urlsArray of strings(uri)(Attachment URLs)<= 10 items

A list of image URLs that will be added as attachments. You can include up to 10 URLs.

{ "email": "string", "message_type": "comment", "type": "user", "body": "string", "created_at": 1590000000, "attachment_urls": [ "http://example.com" ] }

Intercom User ID

Payload of the request to reply on behalf of a contact using their intercom_user_id

intercom_user_idstringrequired

The identifier for the contact as given by Intercom.

message_typestringrequired
Value"comment"
typestringrequired
Value"user"
bodystringrequired

The text body of the comment.

created_atinteger

The time the reply was created. If not provided, the current time will be used.

Example: 1590000000
attachment_urlsArray of strings(uri)(Attachment URLs)<= 10 items

A list of image URLs that will be added as attachments. You can include up to 10 URLs.

{ "intercom_user_id": "string", "message_type": "comment", "type": "user", "body": "string", "created_at": 1590000000, "attachment_urls": [ "http://example.com" ] }

Contact Reply on ticket

One of:

Payload of the request to reply on behalf of a contact using their intercom_user_id

intercom_user_idstringrequired

The identifier for the contact as given by Intercom.

message_typestringrequired
Value"comment"
typestringrequired
Value"user"
bodystringrequired

The text body of the comment.

created_atinteger

The time the reply was created. If not provided, the current time will be used.

Example: 1590000000
attachment_urlsArray of strings(uri)(Attachment URLs)<= 10 items

A list of image URLs that will be added as attachments. You can include up to 10 URLs.

{ "intercom_user_id": "string", "message_type": "comment", "type": "user", "body": "string", "created_at": 1590000000, "attachment_urls": [ "http://example.com" ] }

User ID

Payload of the request to reply on behalf of a contact using their user_id

user_idstringrequired

The external_id you have defined for the contact.

message_typestringrequired
Value"comment"
typestringrequired
Value"user"
bodystringrequired

The text body of the comment.

created_atinteger

The time the reply was created. If not provided, the current time will be used.

Example: 1590000000
attachment_urlsArray of strings(uri)(Attachment URLs)<= 10 items

A list of image URLs that will be added as attachments. You can include up to 10 URLs.

{ "user_id": "string", "message_type": "comment", "type": "user", "body": "string", "created_at": 1590000000, "attachment_urls": [ "http://example.com" ] }

User ID

Payload of the request to reply on behalf of a contact using their user_id

user_idstringrequired

The external_id you have defined for the contact.

attachment_filesArray of objects(Conversation attachment files)<= 10 items

A list of files that will be added as attachments. You can include up to 10 files.

message_typestringrequired
Value"comment"
typestringrequired
Value"user"
bodystringrequired

The text body of the comment.

created_atinteger

The time the reply was created. If not provided, the current time will be used.

Example: 1590000000
attachment_urlsArray of strings(uri)(Attachment URLs)<= 10 items

A list of image URLs that will be added as attachments. You can include up to 10 URLs.

{ "user_id": "string", "attachment_files": [ {} ], "message_type": "comment", "type": "user", "body": "string", "created_at": 1590000000, "attachment_urls": [ "http://example.com" ] }

Segments

A list of segments objects attached to a specific contact.

typestring

The type of the object

Value"list"
Example: "list"
dataArray of objects(Segment)

Segment objects associated with the contact.

{ "type": "list", "data": [ {} ] }

Social Profile

An object containing social profiles that a contact has.

dataArray of objects(Social Profile)

A list of social profiles objects associated with the contact.

{ "data": [ {} ] }

Contact Subscription Types

An object containing Subscription Types meta data about the SubscriptionTypes that a contact has.

dataArray of objects(Addressable List)

This object represents the subscriptions attached to a contact.

urlstring(uri)

Url to get more subscription type resources for this contact

Example: "/contacts/5ba682d23d7cf92bef87bfd4/subscriptions"
total_countinteger

Int representing the total number of subscription types attached to this contact

Example: 100
has_moreboolean

Whether there's more Addressable Objects to be viewed. If true, use the url to view all

Example: true
{ "data": [ {} ], "url": "/contacts/5ba682d23d7cf92bef87bfd4/subscriptions", "total_count": 100, "has_more": true }

Contact Tags

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.

dataArray of objects(Addressable List)

This object represents the tags attached to a contact.

urlstring(uri)

url to get more tag resources for this contact

Example: "/contacts/5ba682d23d7cf92bef87bfd4/tags"
total_countinteger

Int representing the total number of tags attached to this contact

Example: 100
has_moreboolean

Whether there's more Addressable Objects to be viewed. If true, use the url to view all

Example: true
{ "data": [ {} ], "url": "/contacts/5ba682d23d7cf92bef87bfd4/tags", "total_count": 100, "has_more": true }

Contact Unarchived

unarchived contact object

typestring

always contact

Value"contact"
Example: "contact"
idstring

The unique identifier for the contact which is given by Intercom.

Example: "5ba682d23d7cf92bef87bfd4"
external_idstring or null

The unique identifier for the contact which is provided by the Client.

Example: "f3b87a2e09d514c6c2e79b9a"
archivedboolean

Whether the contact is archived or not.

Example: false
{ "type": "contact", "id": "5ba682d23d7cf92bef87bfd4", "external_id": "f3b87a2e09d514c6c2e79b9a", "archived": false }

Content Source List

typestring
Value"content_source.list"
Example: "content_source.list"
total_countinteger

The total number of content sources used by AI Agent in the conversation.

Example: 1
content_sourcesArray of objects(Content Source)

The content sources used by AI Agent in the conversation.

{ "type": "content_source.list", "total_count": 1, "content_sources": [ {} ] }

Conversation attachment files

Properties of the attachment files in a conversation part

content_typestring

The content type of the file

Example: "application/json"
datastring

The base64 encoded file data.

Example: "ewogICJ0ZXN0IjogMQp9"
namestring

The name of the file.

Example: "test.json"
{ "content_type": "application/json", "data": "ewogICJ0ZXN0IjogMQp9", "name": "test.json" }

Contacts

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.

typestring
Value"contact.list"
Example: "contact.list"
contactsArray of objects(Contact Reference)

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.

{ "type": "contact.list", "contacts": [ {} ] }

First contact reply

An object containing information on the first users message. For a contact initiated message this will represent the users original message.

created_atinteger(date-time)
Example: 1663597223
typestring
Example: "conversation"
urlstring or null
Example: "https://developers.intercom.com/"
{ "created_at": 1663597223, "type": "conversation", "url": "https://developers.intercom.com/" }

Conversation List

Conversations are how you can communicate with users in Intercom. They are created when a contact replies to an outbound message, or when one admin directly sends a message to a single contact.

typestring

Always conversation.list

Value"conversation.list"
Example: "conversation.list"
conversationsArray of objects(Conversation)

The list of conversation objects

total_countinteger

A count of the total number of objects.

Example: 12345
pagesobject or null(Cursor based pages)

Cursor-based pagination is a technique used in the Intercom API to navigate through large amounts of data. A "cursor" or pointer is used to keep track of the current position in the result set, allowing the API to return the data in small chunks or "pages" as needed.

{ "type": "conversation.list", "conversations": [ {} ], "total_count": 12345, "pages": { "type": "pages", "page": 1, "next": {}, "per_page": 2, "total_pages": 13 } }

Conversation Part

A Conversation Part represents a message in the conversation.

typestring

Always conversation_part

Example: "conversation_part"
idstring

The id representing the conversation part.

Example: "3"
part_typestring

The type of conversation part.

Example: "comment"
bodystring or null

The message body, which may contain HTML. For Twitter, this will show a generic message regarding why the body is obscured.

Example: "<p>Okay!</p>"
created_atinteger(date-time)

The time the conversation part was created.

Example: 1663597223
updated_atinteger(date-time)

The last time the conversation part was updated.

Example: 1663597260
notified_atinteger(date-time)

The time the user was notified with the conversation part.

Example: 1663597260
assigned_toobject(Reference)

reference to another object

authorobject(Conversation part author)

The object who initiated the conversation, which can be a Contact, Admin or Team. Bots and campaigns send messages on behalf of Admins or Teams. For Twitter, this will be blank.

attachmentsArray of objects(Conversation part attachments)

A list of attachments for the part.

external_idstring or null

The external id of the conversation part

Example: "abcd1234"
redactedboolean

Whether or not the conversation part has been redacted.

Example: false
{ "type": "conversation_part", "id": "3", "part_type": "comment", "body": "<p>Okay!</p>", "created_at": 1663597223, "updated_at": 1663597260, "notified_at": 1663597260, "assigned_to": { "type": "contact", "id": "1a2b3c" }, "author": { "type": "admin", "id": "274", "name": "Operator", "email": "operator+abcd1234@intercom.io" }, "attachments": [ {} ], "external_id": "abcd1234", "redacted": false }

Conversation part author

The object who initiated the conversation, which can be a Contact, Admin or Team. Bots and campaigns send messages on behalf of Admins or Teams. For Twitter, this will be blank.

typestring

The type of the author

Example: "admin"
idstring

The id of the author

Example: "274"
namestring

The name of the author

Example: "Operator"
emailstring(email)

The email of the author

Example: "operator+abcd1234@intercom.io"
{ "type": "admin", "id": "274", "name": "Operator", "email": "operator+abcd1234@intercom.io" }

Conversation Parts

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.

typestring
Value"conversation_part.list"
Example: "conversation_part.list"
conversation_partsArray of objects(Conversation Parts)

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.

total_countinteger
Example: 2
{ "type": "conversation_part.list", "conversation_parts": [ {} ], "total_count": 2 }

Conversation Rating

The Conversation Rating object which contains information on the rating and/or remark added by a Contact and the Admin assigned to the conversation.

ratinginteger

The rating, between 1 and 5, for the conversation.

Example: 5
remarkstring

An optional field to add a remark to correspond to the number rating

Example: ""
created_atinteger(date-time)

The time the rating was requested in the conversation being rated.

Example: 1671028894
contactobject(Contact Reference)

reference to contact object

teammateobject(Reference)

reference to another object

{ "rating": 5, "remark": "", "created_at": 1671028894, "contact": { "type": "contact", "id": "5ba682d23d7cf92bef87bfd4", "external_id": "f3b87a2e09d514c6c2e79b9a" }, "teammate": { "type": "contact", "id": "1a2b3c" } }

Conversation source

The Conversation Part that originated this conversation, which can be Contact, Admin, Campaign, Automated or Operator initiated.

typestring

This includes conversation, email, facebook, instagram, phone_call, phone_switch, push, sms, twitter and whatsapp.

Example: "conversation"
idstring

The id representing the message.

Example: "3"
delivered_asstring

The conversation's initiation type. Possible values are customer_initiated, campaigns_initiated (legacy campaigns), operator_initiated (Custom bot), automated (Series and other outbounds with dynamic audience message) and admin_initiated (fixed audience message, ticket initiated by an admin, group email).

Example: "operator_initiated"
subjectstring

Optional. The message subject. For Twitter, this will show a generic message regarding why the subject is obscured.

Example: ""
bodystring

The message body, which may contain HTML. For Twitter, this will show a generic message regarding why the body is obscured.

Example: "<p>Hey there!</p>"
authorobject(Conversation part author)

The object who initiated the conversation, which can be a Contact, Admin or Team. Bots and campaigns send messages on behalf of Admins or Teams. For Twitter, this will be blank.

attachmentsArray of objects(Part attachment)

A list of attachments for the part.

urlstring or null

The URL where the conversation was started. For Twitter, Email, and Bots, this will be blank.

Example: null
redactedboolean

Whether or not the source message has been redacted. Only applicable for contact initiated messages.

Example: false
{ "type": "conversation", "id": "3", "delivered_as": "operator_initiated", "subject": "", "body": "<p>Hey there!</p>", "author": { "type": "admin", "id": "274", "name": "Operator", "email": "operator+abcd1234@intercom.io" }, "attachments": [ {} ], "url": null, "redacted": false }

Conversation statistics

A Statistics object containing all information required for reporting, with timestamps and calculated metrics.

typestring
Example: "conversation_statistics"
time_to_assignmentinteger

Duration until last assignment before first admin reply. In seconds.

Example: 2310
time_to_admin_replyinteger

Duration until first admin reply. Subtracts out of business hours. In seconds.

Example: 2310
time_to_first_closeinteger

Duration until conversation was closed first time. Subtracts out of business hours. In seconds.

Example: 2310
time_to_last_closeinteger

Duration until conversation was closed last time. Subtracts out of business hours. In seconds.

Example: 2310
median_time_to_replyinteger

Median based on all admin replies after a contact reply. Subtracts out of business hours. In seconds.

Example: 2310
first_contact_reply_atinteger(date-time)

Time of first text conversation part from a contact.

Example: 1663597233
first_assignment_atinteger(date-time)

Time of first assignment after first_contact_reply_at.

Example: 1663597233
first_admin_reply_atinteger(date-time)

Time of first admin reply after first_contact_reply_at.

Example: 1663597233
first_close_atinteger(date-time)

Time of first close after first_contact_reply_at.

Example: 1663597233
last_assignment_atinteger(date-time)

Time of last assignment after first_contact_reply_at.

Example: 1663597233
last_assignment_admin_reply_atinteger(date-time)

Time of first admin reply since most recent assignment.

Example: 1663597233
last_contact_reply_atinteger(date-time)

Time of the last conversation part from a contact.

Example: 1663597233
last_admin_reply_atinteger(date-time)

Time of the last conversation part from an admin.

Example: 1663597233
last_close_atinteger(date-time)

Time of the last conversation close.

Example: 1663597233
last_closed_by_idstring

The last admin who closed the conversation. Returns a reference to an Admin object.

Example: "c3po"
count_reopensinteger

Number of reopens after first_contact_reply_at.

Example: 1
count_assignmentsinteger

Number of assignments after first_contact_reply_at.

Example: 1
count_conversation_partsinteger

Total number of conversation parts.

Example: 1
{ "type": "conversation_statistics", "time_to_assignment": 2310, "time_to_admin_reply": 2310, "time_to_first_close": 2310, "time_to_last_close": 2310, "median_time_to_reply": 2310, "first_contact_reply_at": 1663597233, "first_assignment_at": 1663597233, "first_admin_reply_at": 1663597233, "first_close_at": 1663597233, "last_assignment_at": 1663597233, "last_assignment_admin_reply_at": 1663597233, "last_contact_reply_at": 1663597233, "last_admin_reply_at": 1663597233, "last_close_at": 1663597233, "last_closed_by_id": "c3po", "count_reopens": 1, "count_assignments": 1, "count_conversation_parts": 1 }

Conversation teammates

The list of teammates who participated in the conversation (wrote at least one conversation part).

typestring

The type of the object - admin.list.

Example: "admin.list"
teammatesArray of objects(Reference)

The list of teammates who participated in the conversation (wrote at least one conversation part).

{ "type": "admin.list", "teammates": [ {} ] }

Convert Ticket Request Payload

You can convert a Conversation to a Ticket

ticket_type_idstringrequired

The ID of the type of ticket you want to convert the conversation to

Example: "1234"
attributesobject(Ticket Attributes)

The attributes set on the ticket. When setting the default title and description attributes, the attribute keys that should be used are _default_title_ and _default_description_. When setting ticket type attributes of the list attribute type, the key should be the attribute name and the value of the attribute should be the list item id, obtainable by listing the ticket type. For example, if the ticket type has an attribute called priority of type list, the key should be priority and the value of the attribute should be the guid of the list item (e.g. de1825a0-0164-4070-8ca6-13e22462fa7e).

Example: {"_default_title_":"Found a bug","_default_description_":"The button is not working"}
{ "ticket_type_id": "1234", "attributes": { "_default_title_": "Found a bug", "_default_description_": "The button is not working" } }

Convert Visitor Request Payload

You can merge a Visitor to a Contact of role type lead or user.

typestringrequired

Represents the role of the Contact model. Accepts lead or user.

Example: "user"
userobject or objectrequired

The unique identifiers retained after converting or merging.

Any of:

The unique identifiers retained after converting or merging.

user.​idstringrequired

The unique identifier for the contact which is given by Intercom.

Example: "8a88a590-e1c3-41e2-a502-e0649dbf721c"
user.​user_idstring

A unique identifier for the contact which is given to Intercom, which will be represented as external_id.

Example: "8a88a590-e1c3-41e2-a502-e0649dbf721c"
user.​emailstring

The contact's email, retained by default if one is present.

Example: "winstonsmith@truth.org"
visitorobject or object or objectrequired

The unique identifiers to convert a single Visitor.

Any of:

The unique identifiers to convert a single Visitor.

visitor.​idstringrequired

The unique identifier for the contact which is given by Intercom.

Example: "8a88a590-e1c3-41e2-a502-e0649dbf721c"
visitor.​user_idstring

A unique identifier for the contact which is given to Intercom.

Example: "8a88a590-e1c3-41e2-a502-e0649dbf721c"
visitor.​emailstring

The visitor's email.

Example: "winstonsmith@truth.org"
{ "type": "user", "user": { "id": "8a88a590-e1c3-41e2-a502-e0649dbf721c", "user_id": "8a88a590-e1c3-41e2-a502-e0649dbf721c", "email": "winstonsmith@truth.org" }, "visitor": { "id": "8a88a590-e1c3-41e2-a502-e0649dbf721c", "user_id": "8a88a590-e1c3-41e2-a502-e0649dbf721c", "email": "winstonsmith@truth.org" } }

Create Article Request Payload

You can create an Article

titlestringrequired

The title of the article.For multilingual articles, this will be the title of the default language's content.

Example: "Thanks for everything"
descriptionstring

The description of the article. For multilingual articles, this will be the description of the default language's content.

Example: "Description of the Article"
bodystring

The content of the article. For multilingual articles, this will be the body of the default language's content.

Example: "<p>This is the body in html</p>"
author_idintegerrequired

The id of the author of the article. For multilingual articles, this will be the id of the author of the default language's content. Must be a teammate on the help center's workspace.

Example: 1295
statestring

Whether the article will be published or will be a draft. Defaults to draft. For multilingual articles, this will be the state of the default language's content.

Enum"published""draft"
Example: "draft"
parent_idinteger

The id of the article's parent collection or section. An article without this field stands alone.

Example: 18
parent_typestring

The type of parent, which can either be a collection or section.

Example: "collection"
translated_contentobject or null(Article Translated Content)

The Translated Content of an Article. The keys are the locale codes and the values are the translated content of the article.

{ "title": "Thanks for everything", "description": "Description of the Article", "body": "<p>This is the body in html</p>", "author_id": 1295, "state": "draft", "parent_id": 18, "parent_type": "collection", "translated_content": { "type": "article_translated_content", "ar": {}, "bg": {}, "bs": {}, "ca": {}, "cs": {}, "da": {}, "de": {}, "el": {}, "en": {}, "es": {}, "et": {}, "fi": {}, "fr": {}, "he": {}, "hr": {}, "hu": {}, "id": {}, "it": {}, "ja": {}, "ko": {}, "lt": {}, "lv": {}, "mn": {}, "nb": {}, "nl": {}, "pl": {}, "pt": {}, "ro": {}, "ru": {}, "sl": {}, "sr": {}, "sv": {}, "tr": {}, "vi": {}, "pt-BR": {}, "zh-CN": {}, "zh-TW": {} } }

Create Collection Request Payload

You can create a collection

namestringrequired

The name of the collection. For multilingual collections, this will be the name of the default language's content.

Example: "collection 51"
descriptionstring

The description of the collection. For multilingual collections, this will be the description of the default language's content.

Example: "English description"
translated_contentobject or null(Group Translated Content)

The Translated Content of an Group. The keys are the locale codes and the values are the translated content of the Group.

parent_idstring or null

The id of the parent collection. If null then it will be created as the first level collection.

Example: "6871118"
help_center_idinteger or null

The id of the help center where the collection will be created. If null then it will be created in the default help center.

Example: "123"
{ "name": "collection 51", "description": "English description", "translated_content": { "type": "group_translated_content", "ar": {}, "bg": {}, "bs": {}, "ca": {}, "cs": {}, "da": {}, "de": {}, "el": {}, "en": {}, "es": {}, "et": {}, "fi": {}, "fr": {}, "he": {}, "hr": {}, "hu": {}, "id": {}, "it": {}, "ja": {}, "ko": {}, "lt": {}, "lv": {}, "mn": {}, "nb": {}, "nl": {}, "pl": {}, "pt": {}, "ro": {}, "ru": {}, "sl": {}, "sr": {}, "sv": {}, "tr": {}, "vi": {}, "pt-BR": {}, "zh-CN": {}, "zh-TW": {} }, "parent_id": "6871118", "help_center_id": "123" }

Create Contact Request Payload

Payload to create a contact

Any of:

Payload to create a contact

rolestring

The role of the contact.

external_idstring

A unique identifier for the contact which is given to Intercom

emailstringrequired

The contacts email

Example: "jdoe@example.com"
phonestring or null

The contacts phone

Example: "+353871234567"
namestring or null

The contacts name

Example: "John Doe"
avatarstring or null

An image URL containing the avatar of a contact

Example: "https://www.example.com/avatar_image.jpg"
signed_up_atinteger or null(date-time)

The time specified for when a contact signed up

Example: 1571672154
last_seen_atinteger or null(date-time)

The time when the contact was last seen (either where the Intercom Messenger was installed or when specified manually)

Example: 1571672154
owner_idinteger or null

The id of an admin that has been assigned account ownership of the contact

Example: 123
unsubscribed_from_emailsboolean or null

Whether the contact is unsubscribed from emails

Example: true
custom_attributesobject or null

The custom attributes which are set for the contact

{ "role": "string", "external_id": "string", "email": "jdoe@example.com", "phone": "+353871234567", "name": "John Doe", "avatar": "https://www.example.com/avatar_image.jpg", "signed_up_at": 1571672154, "last_seen_at": 1571672154, "owner_id": 123, "unsubscribed_from_emails": true, "custom_attributes": {} }

Create Conversation Request Payload

Conversations are how you can communicate with users in Intercom. They are created when a contact replies to an outbound message, or when one admin directly sends a message to a single contact.

fromobjectrequired
from.​typestringrequired

The role associated to the contact - user or lead.

Enum"lead""user""contact"
Example: "user"
from.​idstring(uuid)= 24 charactersrequired

The identifier for the contact which is given by Intercom.

Example: "536e564f316c83104c000020"
bodystringrequired

The content of the message. HTML is not supported.

Example: "Hello"
{ "from": { "type": "user", "id": "536e564f316c83104c000020" }, "body": "Hello" }

Create Data Attribute Request

namestringrequired

The name of the data attribute.

Example: "My Data Attribute"
modelstringrequired

The model that the data attribute belongs to.

Enum"contact""company"
Example: "contact"
data_typestringrequired

The type of data stored for this attribute.

Enum"string""integer""float""boolean""datetime""date"
Example: "string"
descriptionstring

The readable description you see in the UI for the attribute.

Example: "My Data Attribute Description"
optionsArray of strings

To create list attributes. Provide a set of hashes with value as the key of the options you want to make. data_type must be string.

Example: ["option1","option2"]
messenger_writableboolean

Can this attribute be updated by the Messenger

Example: false
{ "name": "My Data Attribute", "model": "contact", "data_type": "string", "description": "My Data Attribute Description", "options": [ "option1", "option2" ], "messenger_writable": false }

Create Data Event Request

Any of:
event_namestringrequired

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.

Example: "invited-friend"
created_atinteger(date-time)required

The time the event occurred as a UTC Unix timestamp

Example: 1671028894
user_idstring

Your identifier for the user.

Example: "314159"
idstringrequired

The unique identifier for the contact (lead or user) which is given by Intercom.

Example: "8a88a590-e1c3-41e2-a502-e0649dbf721c"
emailstring

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

Example: "frodo.baggins@example.com"
metadataobject

Optional metadata about the event.

Example: {"invite_code":"ADDAFRIEND"}
{ "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" } }

Create Data Event Summaries Request

You can send a list of event summaries for a user. Each event summary should contain the event name, the time the event occurred, and the number of times the event occurred. The event name should be a past tense "verb-noun" combination, to improve readability, for example updated-plan.

user_idstring

Your identifier for the user.

Example: "314159"
event_summariesobject

A list of event summaries for the user. Each event summary should contain the event name, the time the event occurred, and the number of times the event occurred. The event name should be a past tense 'verb-noun' combination, to improve readability, for example updated-plan.

{ "user_id": "314159", "event_summaries": { "event_name": "invited-friend", "count": 1, "first": 1671028894, "last": 1671028894 } }

Create Data Export Request

Request for creating a data export

created_at_afterintegerrequired

The start date that you request data for. It must be formatted as a unix timestamp.

Example: 1527811200
created_at_beforeintegerrequired

The end date that you request data for. It must be formatted as a unix timestamp.

Example: 1527811200
{ "created_at_after": 1527811200, "created_at_before": 1527811200 }

Create Message Request Payload

You can create a message

Any of:

You can create a message

message_typestringrequired

The kind of message being created. Values: in_app or email.

Enum"in_app""email"
Example: "in_app"
subjectstringrequired

The title of the email.

Example: "Thanks for everything"
bodystringrequired

The content of the message. HTML and plaintext are supported.

Example: "Hello there"
templatestringrequired

The style of the outgoing message. Possible values plain or personal.

Example: "plain"
fromobjectrequired

The sender of the message. If not provided, the default sender will be used.

from.​typestringrequired

Always admin.

Value"admin"
Example: "admin"
from.​idintegerrequired

The identifier for the admin which is given by Intercom.

Example: 394051
toobjectrequired

The sender of the message. If not provided, the default sender will be used.

to.​typestringrequired

The role associated to the contact - user or lead.

Enum"user""lead"
Example: "user"
to.​idstringrequired

The identifier for the contact which is given by Intercom.

Example: "536e564f316c83104c000020"
created_atinteger

The time the message was created. If not provided, the current time will be used.

Example: 1590000000
create_conversation_without_contact_replyboolean

Whether a conversation should be opened in the inbox for the message without the contact replying. Defaults to false if not provided.

Default false
Example: true
{ "message_type": "in_app", "subject": "Thanks for everything", "body": "Hello there", "template": "plain", "from": { "type": "admin", "id": 394051 }, "to": { "type": "user", "id": "536e564f316c83104c000020" }, "created_at": 1590000000, "create_conversation_without_contact_reply": true }

Create Or Update Company Request Payload

You can create or update a Company

namestring

The name of the Company

Example: "Intercom"
company_idstring

The company id you have defined for the company. Can't be updated

Example: "625e90fc55ab113b6d92175f"
planstring

The name of the plan you have associated with the company.

Example: "Enterprise"
sizeinteger

The number of employees in this company.

Example: "100"
websitestring

The URL for this company's website. Please note that the value specified here is not validated. Accepts any string.

Example: "https://www.example.com"
industrystring

The industry that this company operates in.

Example: "Manufacturing"
custom_attributesobject

A hash of key/value pairs containing any other data about the company you want Intercom to store.

Example: {"paid_subscriber":true,"monthly_spend":155.5,"team_mates":9}
remote_created_atinteger

The time the company was created by you.

Example: 1394531169
monthly_spendinteger

How much revenue the company generates for your business. Note that this will truncate floats. i.e. it only allow for whole integers, 155.98 will be truncated to 155. Note that this has an upper limit of 2**31-1 or 2147483647..

Example: 1000
{ "name": "Intercom", "company_id": "625e90fc55ab113b6d92175f", "plan": "Enterprise", "size": "100", "website": "https://www.example.com", "industry": "Manufacturing", "custom_attributes": { "paid_subscriber": true, "monthly_spend": 155.5, "team_mates": 9 }, "remote_created_at": 1394531169, "monthly_spend": 1000 }

Create or Update Tag Request Payload

You can create or update an existing tag.

namestringrequired

The name of the tag, which will be created if not found, or the new name for the tag if this is an update request. Names are case insensitive.

Example: "Independent"
idstring

The id of tag to updates.

Example: "656452352"
{ "name": "Independent", "id": "656452352" }

Create Phone Switch Request Payload

You can create an phone switch

phonestringrequired

Phone number in E.164 format, that will receive the SMS to continue the conversation in the Messenger.

Example: "+1 1234567890"
custom_attributesobject(Custom Attributes)

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.

{ "phone": "+1 1234567890", "custom_attributes": { "property1": "string", "property2": "string" } }

Create Ticket Reply Request Payload

One of:
One of:

Payload of the request to reply on behalf of a contact using their intercom_user_id

intercom_user_idstringrequired

The identifier for the contact as given by Intercom.

message_typestringrequired
Value"comment"
typestringrequired
Value"user"
bodystringrequired

The text body of the comment.

created_atinteger

The time the reply was created. If not provided, the current time will be used.

Example: 1590000000
attachment_urlsArray of strings(uri)(Attachment URLs)<= 10 items

A list of image URLs that will be added as attachments. You can include up to 10 URLs.

{ "intercom_user_id": "string", "message_type": "comment", "type": "user", "body": "string", "created_at": 1590000000, "attachment_urls": [ "http://example.com" ] }

Create Ticket Request Payload

You can create a Ticket

ticket_type_idstringrequired

The ID of the type of ticket you want to create

Example: "1234"
contactsArray of ID (object) or External ID (object) or Email (object)required

The list of contacts (users or leads) affected by this ticket. Currently only one is allowed

Example: [{"id":"1234"}]
One of:
contacts[].​idstringrequired

The identifier for the contact as given by Intercom.

company_idstring

The ID of the company that the ticket is associated with. The ID that you set upon company creation.

Example: "1234"
created_atinteger

The time the ticket was created. If not provided, the current time will be used.

Example: 1590000000
ticket_attributesobject(Ticket Attributes)

The attributes set on the ticket. When setting the default title and description attributes, the attribute keys that should be used are _default_title_ and _default_description_. When setting ticket type attributes of the list attribute type, the key should be the attribute name and the value of the attribute should be the list item id, obtainable by listing the ticket type. For example, if the ticket type has an attribute called priority of type list, the key should be priority and the value of the attribute should be the guid of the list item (e.g. de1825a0-0164-4070-8ca6-13e22462fa7e).

Example: {"_default_title_":"Found a bug","_default_description_":"The button is not working"}
{ "ticket_type_id": "1234", "contacts": [ {} ], "company_id": "1234", "created_at": 1590000000, "ticket_attributes": { "_default_title_": "Found a bug", "_default_description_": "The button is not working" } }

Create Ticket Type Attribute Request Payload

You can create a Ticket Type Attribute

namestringrequired

The name of the ticket type attribute

Example: "Bug Priority"
descriptionstringrequired

The description of the attribute presented to the teammate or contact

Example: "Priority level of the bug"
data_typestringrequired

The data type of the attribute

Enum"string""list""integer""decimal""boolean""datetime""files"
Example: "string"
required_to_createboolean

Whether the attribute is required to be filled in when teammates are creating the ticket in Inbox.

Default false
Example: false
required_to_create_for_contactsboolean

Whether the attribute is required to be filled in when contacts are creating the ticket in Messenger.

Default false
Example: false
visible_on_createboolean

Whether the attribute is visible to teammates when creating a ticket in Inbox.

Default true
Example: true
visible_to_contactsboolean

Whether the attribute is visible to contacts when creating a ticket in Messenger.

Default true
Example: true
multilineboolean

Whether the attribute allows multiple lines of text (only applicable to string attributes)

Example: false
list_itemsstring

A comma delimited list of items for the attribute value (only applicable to list attributes)

Example: "Low Priority,Medium Priority,High Priority"
allow_multiple_valuesboolean

Whether the attribute allows multiple files to be attached to it (only applicable to file attributes)

Example: false
{ "name": "Bug Priority", "description": "Priority level of the bug", "data_type": "string", "required_to_create": false, "required_to_create_for_contacts": false, "visible_on_create": true, "visible_to_contacts": true, "multiline": false, "list_items": "Low Priority,Medium Priority,High Priority", "allow_multiple_values": false }

Create Ticket Type Request Payload

The request payload for creating a ticket type. You can copy the icon property for your ticket type from Twemoji Cheatsheet

namestringrequired

The name of the ticket type.

Example: "Bug"
descriptionstring

The description of the ticket type.

Example: "Used for tracking bugs"
categorystring

Category of the Ticket Type.

Enum"Customer""Back-office""Tracker"
Example: "Customer"
iconstring

The icon of the ticket type.

Default "🎟️"
Example: "🐞"
is_internalboolean

Whether the tickets associated with this ticket type are intended for internal use only or will be shared with customers. This is currently a limited attribute.

Default false
Example: false
{ "name": "Bug", "description": "Used for tracking bugs", "category": "Customer", "icon": "🐞", "is_internal": false }

Cursor based pages

Cursor-based pagination is a technique used in the Intercom API to navigate through large amounts of data. A "cursor" or pointer is used to keep track of the current position in the result set, allowing the API to return the data in small chunks or "pages" as needed.

typestring

the type of object pages.

Value"pages"
Example: "pages"
pageinteger

The current page

Example: 1
nextobject or null(Pagination: Starting After)
per_pageinteger

Number of results per page

Example: 2
total_pagesinteger

Total number of pages

Example: 13
{ "type": "pages", "page": 1, "next": { "per_page": 2, "starting_after": "your-cursor-from-response" }, "per_page": 2, "total_pages": 13 }

Custom Attributes

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.

property name*string or (Custom Object Instance (object or null))additional property
Any of:
string
{ "property1": "string", "property2": "string" }

customer_request

One of:
intercom_user_idstringrequired

The identifier for the contact as given by Intercom.

Example: "6329bd9ffe4e2e91dac76188"
{ "intercom_user_id": "6329bd9ffe4e2e91dac76188" }

Data Attribute List

A list of all data attributes belonging to a workspace for contacts, companies or conversations.

typestring

The type of the object

Value"list"
Example: "list"
dataArray of objects(Data Attribute)

A list of data attributes

{ "type": "list", "data": [ {} ] }

Data Event List

This will return a list of data events for the App.

typestring

The type of the object

Value"event.list"
Example: "event.list"
eventsArray of objects(Data Event)

A list of data events

pagesobject

Pagination

{ "type": "event.list", "events": [ {} ], "pages": { "next": "https://api.intercom.io/events?per_page=2&before=1389913941064&intercom_user_id=63a0979a5eeebeaf28dd56ba&type=user\"", "since": "https://api.intercom.io/events?intercom_user_id=63a0979a5eeebeaf28dd56ba&type=user&since=1389913941065" } }

Data Event Summary

This will return a summary of data events for the App.

typestring

The type of the object

Value"event.summary"
Example: "event.summary"
emailstring

The email address of the user

Example: "Sam.Sung@example.com"
intercom_user_idstring

The Intercom user ID of the user

Example: "63a0979a5eeebeaf28dd56ba"
user_idstring

The user ID of the user

Example: "62b997f288e14803c5006932"
eventsArray of objects or null(Data Event Summary Item)

A summary of data events

{ "type": "event.summary", "email": "Sam.Sung@example.com", "intercom_user_id": "63a0979a5eeebeaf28dd56ba", "user_id": "62b997f288e14803c5006932", "events": [ {} ] }

Data Event Summary Item

This will return a summary of a data event for the App.

namestring

The name of the event

Example: "placed-order"
firststring

The first time the event was sent

Example: "2014-01-16T23:12:21.000+00:00"
laststring

The last time the event was sent

Example: "2014-01-16T23:12:21.000+00:00 "
countinteger

The number of times the event was sent

Example: 1
descriptionstring

The description of the event

Example: "A user placed an order"
{ "name": "placed-order", "first": "2014-01-16T23:12:21.000+00:00", "last": "2014-01-16T23:12:21.000+00:00 ", "count": 1, "description": "A user placed an order" }

Data Export CSV

A CSV output file

user_idstring

The user_id of the user who was sent the message.

user_external_idstring

The external_user_id of the user who was sent the message

company_idstring

The company ID of the user in relation to the message that was sent. Will return -1 if no company is present.

emailstring

The users email who was sent the message.

namestring

The full name of the user receiving the message

ruleset_idstring

The id of the message.

content_idstring

The specific content that was received. In an A/B test each version has its own Content ID.

content_typestring

Email, Chat, Post etc.

content_titlestring

The title of the content you see in your Intercom workspace.

ruleset_version_idstring

As you edit content we record new versions. This ID can help you determine which version of a piece of content that was received.

receipt_idstring

ID for this receipt. Will be included with any related stats in other files to identify this specific delivery of a message.

received_atinteger

Timestamp for when the receipt was recorded.

series_idstring

The id of the series that this content is part of. Will return -1 if not part of a series.

series_titlestring

The title of the series that this content is part of.

node_idstring

The id of the series node that this ruleset is associated with. Each block in a series has a corresponding node_id.

first_replyinteger

The first time a user replied to this message if the content was able to receive replies.

first_completioninteger

The first time a user completed this message if the content was able to be completed e.g. Tours, Surveys.

first_series_completioninteger

The first time the series this message was a part of was completed by the user.

first_series_disengagementinteger

The first time the series this message was a part of was disengaged by the user.

first_series_exitinteger

The first time the series this message was a part of was exited by the user.

first_goal_successinteger

The first time the user met this messages associated goal if one exists.

first_openinteger

The first time the user opened this message.

first_clickinteger

The first time the series the user clicked on a link within this message.

first_dismisallinteger

The first time the series the user dismissed this message.

first_unsubscribeinteger

The first time the user unsubscribed from this message.

first_hard_bounceinteger

The first time this message hard bounced for this user

{ "user_id": "string", "user_external_id": "string", "company_id": "string", "email": "string", "name": "string", "ruleset_id": "string", "content_id": "string", "content_type": "string", "content_title": "string", "ruleset_version_id": "string", "receipt_id": "string", "received_at": 0, "series_id": "string", "series_title": "string", "node_id": "string", "first_reply": 0, "first_completion": 0, "first_series_completion": 0, "first_series_disengagement": 0, "first_series_exit": 0, "first_goal_success": 0, "first_open": 0, "first_click": 0, "first_dismisall": 0, "first_unsubscribe": 0, "first_hard_bounce": 0 }

Deleted Article Object

Response returned when an object is deleted

idstring

The unique identifier for the article which you provided in the URL.

Example: "6890762"
objectstring

The type of object which was deleted. - article

Value"article"
Example: "article"
deletedboolean

Whether the article was deleted successfully or not.

Example: true
{ "id": "6890762", "object": "article", "deleted": true }

Deleted Collection Object

Response returned when an object is deleted

idstring

The unique identifier for the collection which you provided in the URL.

Example: "6890762"
objectstring

The type of object which was deleted. - collection

Value"collection"
Example: "collection"
deletedboolean

Whether the collection was deleted successfully or not.

Example: true
{ "id": "6890762", "object": "collection", "deleted": true }

Deleted Company Object

Response returned when an object is deleted

idstring

The unique identifier for the company which is given by Intercom.

Example: "5b7e8b2f-7a1a-4e6c-8e1b-4f9d4f4c4d4f"
objectstring

The type of object which was deleted. - company

Value"company"
Example: "company"
deletedboolean

Whether the company was deleted successfully or not.

Example: true
{ "id": "5b7e8b2f-7a1a-4e6c-8e1b-4f9d4f4c4d4f", "object": "company", "deleted": true }

Deleted Object

Response returned when an object is deleted

idstring

The unique identifier for the news item which you provided in the URL.

Example: "6890762"
objectstring

The type of object which was deleted - news-item.

Value"news-item"
Example: "news-item"
deletedboolean

Whether the news item was deleted successfully or not.

Example: true
{ "id": "6890762", "object": "news-item", "deleted": true }

detach_contact_from_conversation_request

admin_idstringrequired

The id of the admin who is performing the action.

Example: "5017690"
{ "admin_id": "5017690" }

Error

The API will return an Error List for a failed request, which will contain one or more Error objects.

typestringrequired

The type is error.list

Example: "error.list"
request_idstring or null(uuid)
Example: "f93ecfa8-d08a-4325-8694-89aeb89c8f85"
errorsArray of objectsrequired

An array of one or more error objects

errors[].​codestringrequired

A string indicating the kind of error, used to further qualify the HTTP response code

Example: "unauthorized"
errors[].​messagestring or null

Optional. Human readable description of the error.

Example: "Access Token Invalid"
errors[].​fieldstring or null

Optional. Used to identify a particular field or query parameter that was in error.

Example: "email"
{ "type": "error.list", "request_id": "f93ecfa8-d08a-4325-8694-89aeb89c8f85", "errors": [ {} ] }

File

The value describing a file upload set for a custom attribute

typestring
Example: "upload"
namestring

The name of the file

Example: "Screenshot.png"
urlstring

The url of the file. This is a temporary URL and will expire after 30 minutes.

Example: "https://intercom-attachments-1.com/.../Screenshot.png"
content_typestring

The type of file

Example: "image/png"
filesizeinteger

The size of the file in bytes

Example: 11308309
widthinteger

The width of the file in pixels, if applicable

Example: 3024
heightinteger

The height of the file in pixels, if applicable

Example: 1964
{ "type": "upload", "name": "Screenshot.png", "url": "https://intercom-attachments-1.com/.../Screenshot.png", "content_type": "image/png", "filesize": 11308309, "width": 3024, "height": 1964 }

Group Content

The Content of a Group.

typestring or null

The type of object - group_content .

Enumnull"group_content"
Example: "group_content"
namestring

The name of the collection or section.

Example: "Collection name"
descriptionstring

The description of the collection. Only available for collections.

Example: " Collection description"
{ "type": "group_content", "name": "Collection name", "description": " Collection description" }

Group Translated Content

The Translated Content of an Group. The keys are the locale codes and the values are the translated content of the Group.

typestring or null

The type of object - group_translated_content.

Enumnull"group_translated_content"
Example: "group_translated_content"
arobject or null(Group Content)

The Content of a Group.

bgobject or null(Group Content)

The Content of a Group.

bsobject or null(Group Content)

The Content of a Group.

caobject or null(Group Content)

The Content of a Group.

csobject or null(Group Content)

The Content of a Group.

daobject or null(Group Content)

The Content of a Group.

deobject or null(Group Content)

The Content of a Group.

elobject or null(Group Content)

The Content of a Group.

enobject or null(Group Content)

The Content of a Group.

esobject or null(Group Content)

The Content of a Group.

etobject or null(Group Content)

The Content of a Group.

fiobject or null(Group Content)

The Content of a Group.

frobject or null(Group Content)

The Content of a Group.

heobject or null(Group Content)

The Content of a Group.

hrobject or null(Group Content)

The Content of a Group.

huobject or null(Group Content)

The Content of a Group.

idobject or null(Group Content)

The Content of a Group.

itobject or null(Group Content)

The Content of a Group.

jaobject or null(Group Content)

The Content of a Group.

koobject or null(Group Content)

The Content of a Group.

ltobject or null(Group Content)

The Content of a Group.

lvobject or null(Group Content)

The Content of a Group.

mnobject or null(Group Content)

The Content of a Group.

nbobject or null(Group Content)

The Content of a Group.

nlobject or null(Group Content)

The Content of a Group.

plobject or null(Group Content)

The Content of a Group.

ptobject or null(Group Content)

The Content of a Group.

roobject or null(Group Content)

The Content of a Group.

ruobject or null(Group Content)

The Content of a Group.

slobject or null(Group Content)

The Content of a Group.

srobject or null(Group Content)

The Content of a Group.

svobject or null(Group Content)

The Content of a Group.

trobject or null(Group Content)

The Content of a Group.

viobject or null(Group Content)

The Content of a Group.

pt-BRobject or null(Group Content)

The Content of a Group.

zh-CNobject or null(Group Content)

The Content of a Group.

zh-TWobject or null(Group Content)

The Content of a Group.

{ "type": "group_translated_content", "ar": { "type": "group_content", "name": "Collection name", "description": " Collection description" }, "bg": { "type": "group_content", "name": "Collection name", "description": " Collection description" }, "bs": { "type": "group_content", "name": "Collection name", "description": " Collection description" }, "ca": { "type": "group_content", "name": "Collection name", "description": " Collection description" }, "cs": { "type": "group_content", "name": "Collection name", "description": " Collection description" }, "da": { "type": "group_content", "name": "Collection name", "description": " Collection description" }, "de": { "type": "group_content", "name": "Collection name", "description": " Collection description" }, "el": { "type": "group_content", "name": "Collection name", "description": " Collection description" }, "en": { "type": "group_content", "name": "Collection name", "description": " Collection description" }, "es": { "type": "group_content", "name": "Collection name", "description": " Collection description" }, "et": { "type": "group_content", "name": "Collection name", "description": " Collection description" }, "fi": { "type": "group_content", "name": "Collection name", "description": " Collection description" }, "fr": { "type": "group_content", "name": "Collection name", "description": " Collection description" }, "he": { "type": "group_content", "name": "Collection name", "description": " Collection description" }, "hr": { "type": "group_content", "name": "Collection name", "description": " Collection description" }, "hu": { "type": "group_content", "name": "Collection name", "description": " Collection description" }, "id": { "type": "group_content", "name": "Collection name", "description": " Collection description" }, "it": { "type": "group_content", "name": "Collection name", "description": " Collection description" }, "ja": { "type": "group_content", "name": "Collection name", "description": " Collection description" }, "ko": { "type": "group_content", "name": "Collection name", "description": " Collection description" }, "lt": { "type": "group_content", "name": "Collection name", "description": " Collection description" }, "lv": { "type": "group_content", "name": "Collection name", "description": " Collection description" }, "mn": { "type": "group_content", "name": "Collection name", "description": " Collection description" }, "nb": { "type": "group_content", "name": "Collection name", "description": " Collection description" }, "nl": { "type": "group_content", "name": "Collection name", "description": " Collection description" }, "pl": { "type": "group_content", "name": "Collection name", "description": " Collection description" }, "pt": { "type": "group_content", "name": "Collection name", "description": " Collection description" }, "ro": { "type": "group_content", "name": "Collection name", "description": " Collection description" }, "ru": { "type": "group_content", "name": "Collection name", "description": " Collection description" }, "sl": { "type": "group_content", "name": "Collection name", "description": " Collection description" }, "sr": { "type": "group_content", "name": "Collection name", "description": " Collection description" }, "sv": { "type": "group_content", "name": "Collection name", "description": " Collection description" }, "tr": { "type": "group_content", "name": "Collection name", "description": " Collection description" }, "vi": { "type": "group_content", "name": "Collection name", "description": " Collection description" }, "pt-BR": { "type": "group_content", "name": "Collection name", "description": " Collection description" }, "zh-CN": { "type": "group_content", "name": "Collection name", "description": " Collection description" }, "zh-TW": { "type": "group_content", "name": "Collection name", "description": " Collection description" } }

intercom_version

Intercom API version.
By default, it's equal to the version set in the app package.

string(intercom_version)

Intercom API version.
By default, it's equal to the version set in the app package.

Default "2.11"
Enum"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"
"2.11"

Linked Object

A linked conversation or ticket.

typestring

ticket or conversation

Enum"ticket""conversation"
Example: "ticket"
idstring

The ID of the linked object

Example: "7583"
categorystring or null

Category of the Linked Ticket Object.

Enum"Customer""Back-office""Tracker"null
Example: "Customer"
{ "type": "ticket", "id": "7583", "category": "Customer" }

Linked Objects

An object containing metadata about linked conversations and linked tickets. Up to 1000 can be returned.

typestring

Always list.

Value"list"
Example: "list"
total_countinteger

The total number of linked objects.

Example: 100
has_moreboolean

Whether or not there are more linked objects than returned.

Example: false
dataArray of objects(Linked Object)

An array containing the linked conversations and linked tickets.

{ "type": "list", "total_count": 100, "has_more": false, "data": [ {} ] }

Merge contact data

Merge contact data.

fromstring

The unique identifier for the contact to merge away from. Must be a lead.

Example: "5d70dd30de4efd54f42fd526"
intostring

The unique identifier for the contact to merge into. Must be a user.

Example: "5ba682d23d7cf92bef87bfd4"
{ "from": "5d70dd30de4efd54f42fd526", "into": "5ba682d23d7cf92bef87bfd4" }

Multiple Filter Search Request

Search using Intercoms Search APIs with more than one filter.

operatorstring

An operator to allow boolean inspection between multiple fields.

Enum"AND""OR"
Example: "AND"
valueArray of multiple filter search request (objects) or Array of single filter search request (objects)
One of:

Add mutiple filters.

{ "operator": "AND", "value": [ {} ] }

Create News Item Request

A News Item is a content type in Intercom enabling you to announce product updates, company news, promotions, events and more with your customers.

titlestringrequired

The title of the news item.

Example: "Halloween is here!"
bodystring

The news item body, which may contain HTML.

Example: "<p>New costumes in store for this spooky season</p>"
sender_idintegerrequired

The id of the sender of the news item. Must be a teammate on the workspace.

Example: 123
statestring

News items will not be visible to your users in the assigned newsfeeds until they are set live.

Enum"draft""live"
Example: "live"
deliver_silentlyboolean

When set to true, the news item will appear in the messenger newsfeed without showing a notification badge.

Example: true
labelsArray of strings

Label names displayed to users to categorize the news item.

Example: ["Product","Update","New"]
reactionsArray of strings or null

Ordered list of emoji reactions to the news item. When empty, reactions are disabled.

Example: ["😆","😅"]
newsfeed_assignmentsArray of objects(Newsfeed Assignment)

A list of newsfeed_assignments to assign to the specified newsfeed.

{ "title": "Halloween is here!", "body": "<p>New costumes in store for this spooky season</p>", "sender_id": 123, "state": "live", "deliver_silently": true, "labels": [ "Product", "Update", "New" ], "reactions": [ "😆", "😅" ], "newsfeed_assignments": [ {} ] }

Paginated Response

A paginated list of notes associated with a contact.

typestring

String representing the object's type. Always has the value list.

Example: "list"
dataArray of objects(Note)

An array of notes.

total_countinteger

A count of the total number of notes.

Example: 1
pagesobject or null(Cursor based pages)

Cursor-based pagination is a technique used in the Intercom API to navigate through large amounts of data. A "cursor" or pointer is used to keep track of the current position in the result set, allowing the API to return the data in small chunks or "pages" as needed.

{ "type": "list", "data": [ {} ], "total_count": 1, "pages": { "type": "pages", "page": 1, "next": {}, "per_page": 2, "total_pages": 13 } }

Open Conversation Request

Payload of the request to open a conversation

message_typestringrequired
Value"open"
Example: "open"
admin_idstringrequired

The id of the admin who is performing the action.

Example: "5017690"
{ "message_type": "open", "admin_id": "5017690" }

Paginated Response

Paginated Response

typestring

The type of object

Enum"list""conversation.list"
Example: "list"
pagesobject or null(Cursor based pages)

Cursor-based pagination is a technique used in the Intercom API to navigate through large amounts of data. A "cursor" or pointer is used to keep track of the current position in the result set, allowing the API to return the data in small chunks or "pages" as needed.

total_countinteger

A count of the total number of objects.

Example: 1
dataArray of News Item (object) or Newsfeed (object)

An array of Objects

{ "type": "list", "pages": { "type": "pages", "page": 1, "next": {}, "per_page": 2, "total_pages": 13 }, "total_count": 1, "data": [ {} ] }

Part attachment

The file attached to a part

typestring

The type of attachment

Example: "upload"
namestring

The name of the attachment

Example: "example.png"
urlstring

The URL of the attachment

Example: "https://picsum.photos/200/300"
content_typestring

The content type of the attachment

Example: "image/png"
filesizeinteger

The size of the attachment

Example: 100
widthinteger

The width of the attachment

Example: 100
heightinteger

The height of the attachment

Example: 100
{ "type": "upload", "name": "example.png", "url": "https://picsum.photos/200/300", "content_type": "image/png", "filesize": 100, "width": 100, "height": 100 }

Phone Switch

Phone Switch Response

typestring
Default "phone_call_redirect"
Value"phone_call_redirect"
Example: "phone_call_redirect"
phonestring

Phone number in E.164 format, that has received the SMS to continue the conversation in the Messenger.

Example: "+1 1234567890"
{ "type": "phone_call_redirect", "phone": "+1 1234567890" }

redact_conversation_request

One of:

Payload of the request to redact a conversation part

typestringrequired

The type of resource being redacted.

Value"conversation_part"
Example: "conversation_part"
conversation_idstringrequired

The id of the conversation.

Example: "19894788788"
conversation_part_idstringrequired

The id of the conversation_part.

Example: "19381789428"
{ "type": "conversation_part", "conversation_id": "19894788788", "conversation_part_id": "19381789428" }

Reference

reference to another object

typestring
Example: "contact"
idstring or null
Example: "1a2b3c"
{ "type": "contact", "id": "1a2b3c" }

reply_conversation_request

One of:
One of:

Payload of the request to reply on behalf of a contact using their intercom_user_id

intercom_user_idstringrequired

The identifier for the contact as given by Intercom.

attachment_filesArray of objects(Conversation attachment files)

A list of files that will be added as attachments.

message_typestringrequired
Value"comment"
typestringrequired
Value"user"
bodystringrequired

The text body of the comment.

created_atinteger

The time the reply was created. If not provided, the current time will be used.

Example: 1590000000
attachment_urlsArray of strings(uri)(Attachment URLs)<= 10 items

A list of image URLs that will be added as attachments. You can include up to 10 URLs.

{ "intercom_user_id": "string", "attachment_files": [ {} ], "message_type": "comment", "type": "user", "body": "string", "created_at": 1590000000, "attachment_urls": [ "http://example.com" ] }

Search data

Search using Intercoms Search APIs.

querySingle Filter Search Request (object) or Multiple Filter Search Request (object)required
One of:

Search using Intercoms Search APIs with a single filter.

query.​fieldstring

The accepted field that you want to search on.

Example: "created_at"
query.​operatorstring

The accepted operators you can use to define how you want to search for the value.

Enum"=""!=""IN""NIN""<"">""~""!~""^""$"
Example: ">"
query.​valuestring

The value that you want to search on.

Example: "73732934"
paginationobject or null(Pagination: Starting After)
{ "query": { "field": "created_at", "operator": ">", "value": "73732934" }, "pagination": { "per_page": 2, "starting_after": "your-cursor-from-response" } }

Segment List

This will return a list of Segment Objects. The result may also have a pages object if the response is paginated.

typestring

The type of the object

Value"segment.list"
Example: "segment.list"
segmentsArray of objects(Segment)

A list of Segment objects

pagesobject

A pagination object, which may be empty, indicating no further pages to fetch.

{ "type": "segment.list", "segments": [ {} ], "pages": {} }

Single Filter Search Request

Search using Intercoms Search APIs with a single filter.

fieldstring

The accepted field that you want to search on.

Example: "created_at"
operatorstring

The accepted operators you can use to define how you want to search for the value.

Enum"=""!=""IN""NIN""<"">""~""!~""^""$"
Example: ">"
valuestring

The value that you want to search on.

Example: "73732934"
{ "field": "created_at", "operator": ">", "value": "73732934" }

Applied SLA

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.

typestring

object type

Example: "conversation_sla_summary"
sla_namestring

The name of the SLA as given by the teammate when it was created.

Example: ""
sla_statusstring

SLA statuses:

  • hit: If there’s at least one hit event in the underlying sla_events table, and no “missed” or “canceled” events for the conversation.
  • missed: If there are any missed sla_events for the conversation and no canceled events. If there’s even a single missed sla event, the status will always be missed. A missed status is not applied when the SLA expires, only the next time a teammate replies.
  • active: An SLA has been applied to a conversation, but has not yet been fulfilled. SLA status is active only if there are no “hit, “missed”, or “canceled” events.
Enum"hit""missed""cancelled""active"
Example: "hit"
{ "type": "conversation_sla_summary", "sla_name": "", "sla_status": "hit" }

Snooze Conversation Request

Payload of the request to snooze a conversation

message_typestringrequired
Value"snoozed"
Example: "snoozed"
admin_idstringrequired

The id of the admin who is performing the action.

Example: "5017691"
snoozed_untilinteger(timestamp)required

The time you want the conversation to reopen.

Example: 1673609604
{ "message_type": "snoozed", "admin_id": "5017691", "snoozed_until": 1673609604 }

Social Profile

A Social Profile allows you to label your contacts, companies, and conversations and list them using that Social Profile.

typestring

value is "social_profile"

Example: "social_profile"
namestring

The name of the Social media profile

Example: "Facebook"
urlstring(uri)

The name of the Social media profile

Example: "http://twitter.com/th1sland"
{ "type": "social_profile", "name": "Facebook", "url": "http://twitter.com/th1sland" }

Pagination: Starting After

per_pageinteger

The number of results to fetch per page.

Example: 2
starting_afterstring or null

The cursor to use in the next request to get the next page of results.

Example: "your-cursor-from-response"
{ "per_page": 2, "starting_after": "your-cursor-from-response" }

Subscription Types

A list of subscription type objects.

typestring

The type of the object

Value"list"
Example: "list"
dataArray of objects(Subscription Types)

A list of subscription type objects associated with the workspace .

{ "type": "list", "data": [ {} ] }

Tag Company Request Payload

You can tag a single company or a list of companies.

namestringrequired

The name of the tag, which will be created if not found.

Example: "Independent"
companiesArray of objectsrequired

The id or company_id of the company can be passed as input parameters.

companies[].​idstring

The Intercom defined id representing the company.

Example: "531ee472cce572a6ec000006"
companies[].​company_idstring

The company id you have defined for the company.

Example: "6"
{ "name": "Independent", "companies": [ {} ] }

Tags

A list of tags objects in the workspace.

typestring

The type of the object

Value"list"
Example: "list"
dataArray of objects(Tag)

A list of tags objects associated with the workspace .

{ "type": "list", "data": [ {} ] }

Tag Users Request Payload

You can tag a list of users.

namestringrequired

The name of the tag, which will be created if not found.

Example: "Independent"
usersArray of objectsrequired
users[].​idstring

The Intercom defined id representing the user.

Example: "5f7f0d217289f8d2f4262080"
{ "name": "Independent", "users": [ {} ] }

Tags

A list of tags objects associated with a conversation

typestring

The type of the object

Value"tag.list"
Example: "tag.list"
tagsArray of objects(Tag)

A list of tags objects associated with the conversation.

{ "type": "tag.list", "tags": [ {} ] }

Team List

This will return a list of team objects for the App.

typestring

The type of the object

Value"team.list"
Example: "team.list"
teamsArray of objects(Team)

A list of team objects

{ "type": "team.list", "teams": [ {} ] }

Team Priority Level

Admin priority levels for teams

primary_team_idsArray of integers or null

The primary team ids for the team

Example: [814865]
secondary_team_idsArray of integers or null

The secondary team ids for the team

Example: [493881]
{ "primary_team_ids": [ 814865 ], "secondary_team_ids": [ 493881 ] }

Ticket Attributes

An object containing the different attributes associated to the ticket as key-value pairs. For the default title and description attributes, the keys are _default_title_ and _default_description_.

property name*(string or null) or number or boolean or Array of arrays or File (object)additional property
Any of:
string or null
{ "_default_title_": "Found a bug", "_default_description_": "The button's not working" }

Ticket List

Tickets are how you track requests from your users.

typestring

Always ticket.list

Value"ticket.list"
Example: "ticket.list"
ticketsArray of objects or null(Ticket)

The list of ticket objects

total_countinteger

A count of the total number of objects.

Example: 12345
pagesobject or null(Cursor based pages)

Cursor-based pagination is a technique used in the Intercom API to navigate through large amounts of data. A "cursor" or pointer is used to keep track of the current position in the result set, allowing the API to return the data in small chunks or "pages" as needed.

{ "type": "ticket.list", "tickets": [ {} ], "total_count": 12345, "pages": { "type": "pages", "page": 1, "next": {}, "per_page": 2, "total_pages": 13 } }

Ticket part author

The author that wrote or triggered the part. Can be a bot, admin, team or user.

typestring

The type of the author

Enum"admin""bot""team""user"
Example: "admin"
idstring

The id of the author

Example: "274"
namestring or null

The name of the author

Example: "Operator"
emailstring(email)

The email of the author

Example: "operator+abcd1234@intercom.io"
{ "type": "admin", "id": "274", "name": "Operator", "email": "operator+abcd1234@intercom.io" }

Ticket Parts

A list of Ticket Part objects for each note and event in the ticket. There is a limit of 500 parts.

typestring
Value"ticket_part.list"
Example: "ticket_part.list"
ticket_partsArray of objects(Tickt Parts)

A list of Ticket Part objects for each ticket. There is a limit of 500 parts.

total_countinteger
Example: 2
{ "type": "ticket_part.list", "ticket_parts": [ {} ], "total_count": 2 }

A Ticket Part representing a note, comment, or quick_reply on a ticket

A Ticket Part representing a note, comment, or quick_reply on a ticket

typestring

Always ticket_part

Value"ticket_part"
Example: "ticket_part"
idstring

The id representing the part.

Example: "3"
part_typestring

Type of the part

Enum"note""comment""quick_reply"
Example: "note"
bodystring or null

The message body, which may contain HTML.

Example: "<p>Okay!</p>"
created_atinteger(date-time)

The time the note was created.

Example: 1663597223
updated_atinteger(date-time)

The last time the note was updated.

Example: 1663597260
authorobject(Ticket part author)

The author that wrote or triggered the part. Can be a bot, admin, team or user.

attachmentsArray of objects(Ticket part attachments)

A list of attachments for the part.

redactedboolean

Whether or not the ticket part has been redacted.

Example: false
{ "type": "ticket_part", "id": "3", "part_type": "note", "body": "<p>Okay!</p>", "created_at": 1663597223, "updated_at": 1663597260, "author": { "type": "admin", "id": "274", "name": "Operator", "email": "operator+abcd1234@intercom.io" }, "attachments": [ {} ], "redacted": false }

Ticket Attributes

The attributes set on the ticket. When setting the default title and description attributes, the attribute keys that should be used are _default_title_ and _default_description_. When setting ticket type attributes of the list attribute type, the key should be the attribute name and the value of the attribute should be the list item id, obtainable by listing the ticket type. For example, if the ticket type has an attribute called priority of type list, the key should be priority and the value of the attribute should be the guid of the list item (e.g. de1825a0-0164-4070-8ca6-13e22462fa7e).

property name*(string or null) or number or boolean or Array of arraysadditional property
Any of:
string or null
{ "_default_title_": "Found a bug", "_default_description_": "The button is not working" }

Ticket Type Attribute

Ticket type attribute, used to define each data field to be captured in a ticket.

typestring

String representing the object's type. Always has the value ticket_type_attribute.

Example: "ticket_type_attribute"
idstring

The id representing the ticket type attribute.

Example: "1"
workspace_idstring

The id of the workspace that the ticket type attribute belongs to.

Example: "ecahpwf5"
namestring

The name of the ticket type attribute

Example: "Title"
descriptionstring

The description of the ticket type attribute

Example: "Bug title."
data_typestring

The type of the data attribute (allowed values: "string list integer decimal boolean datetime files")

Example: "string"
input_optionsobject

Input options for the attribute

Example: "multiline: true"
orderinteger

The order of the attribute against other attributes

Example: 1
required_to_createboolean

Whether the attribute is required or not for teammates.

Default false
Example: false
required_to_create_for_contactsboolean

Whether the attribute is required or not for contacts.

Default false
Example: false
visible_on_createboolean

Whether the attribute is visible or not to teammates.

Default true
Example: false
visible_to_contactsboolean

Whether the attribute is visible or not to contacts.

Default true
Example: false
defaultboolean

Whether the attribute is built in or not.

Example: true
ticket_type_idinteger

The id of the ticket type that the attribute belongs to.

Example: 42
archivedboolean

Whether the ticket type attribute is archived or not.

Example: false
created_atinteger(timestamp)

The date and time the ticket type attribute was created.

updated_atinteger(timestamp)

The date and time the ticket type attribute was last updated.

{ "type": "ticket_type_attribute", "id": "1", "workspace_id": "ecahpwf5", "name": "Title", "description": "Bug title.", "data_type": "string", "input_options": "multiline: true", "order": 1, "required_to_create": false, "required_to_create_for_contacts": false, "visible_on_create": false, "visible_to_contacts": false, "default": true, "ticket_type_id": 42, "archived": false, "created_at": 0, "updated_at": 0 }

Ticket Type Attributes

A list of attributes associated with a given ticket type.

typestring

String representing the object's type. Always has the value ticket_type_attributes.list.

ticket_type_attributesArray of objects or null(Ticket Type Attribute)

A list of ticket type attributes associated with a given ticket type.

{ "type": "string", "ticket_type_attributes": [ {} ] }

Ticket Types

A list of ticket types associated with a given workspace.

typestring

String representing the object's type. Always has the value ticket_type.list.

ticket_typesArray of objects or null(Ticket Type)

A list of ticket_types associated with a given workspace.

{ "type": "string", "ticket_types": [ {} ] }

Translation

A translation object contains the localised details of a subscription type.

namestring

The localised name of the subscription type.

Example: "Announcements"
descriptionstring

The localised description of the subscription type.

Example: "Offers, product and feature announcements"
localestring

The two character identifier for the language of the translation object.

Example: "en"
{ "name": "Announcements", "description": "Offers, product and feature announcements", "locale": "en" }

Untag Company Request Payload

You can tag a single company or a list of companies.

namestringrequired

The name of the tag which will be untagged from the company

Example: "Independent"
companiesArray of objectsrequired

The id or company_id of the company can be passed as input parameters.

companies[].​idstring

The Intercom defined id representing the company.

Example: "531ee472cce572a6ec000006"
companies[].​company_idstring

The company id you have defined for the company.

Example: "6"
companies[].​untagboolean

Always set to true

Example: "true"
{ "name": "Independent", "companies": [ {} ] }

Update Article Request Payload

You can Update an Article

titlestring

The title of the article.For multilingual articles, this will be the title of the default language's content.

Example: "Thanks for everything"
descriptionstring

The description of the article. For multilingual articles, this will be the description of the default language's content.

Example: "Description of the Article"
bodystring

The content of the article. For multilingual articles, this will be the body of the default language's content.

Example: "<p>This is the body in html</p>"
author_idinteger

The id of the author of the article. For multilingual articles, this will be the id of the author of the default language's content. Must be a teammate on the help center's workspace.

Example: 1295
statestring

Whether the article will be published or will be a draft. Defaults to draft. For multilingual articles, this will be the state of the default language's content.

Enum"published""draft"
Example: "draft"
parent_idstring

The id of the article's parent collection or section. An article without this field stands alone.

Example: "18"
parent_typestring

The type of parent, which can either be a collection or section.

Example: "collection"
translated_contentobject or null(Article Translated Content)

The Translated Content of an Article. The keys are the locale codes and the values are the translated content of the article.

{ "title": "Thanks for everything", "description": "Description of the Article", "body": "<p>This is the body in html</p>", "author_id": 1295, "state": "draft", "parent_id": "18", "parent_type": "collection", "translated_content": { "type": "article_translated_content", "ar": {}, "bg": {}, "bs": {}, "ca": {}, "cs": {}, "da": {}, "de": {}, "el": {}, "en": {}, "es": {}, "et": {}, "fi": {}, "fr": {}, "he": {}, "hr": {}, "hu": {}, "id": {}, "it": {}, "ja": {}, "ko": {}, "lt": {}, "lv": {}, "mn": {}, "nb": {}, "nl": {}, "pl": {}, "pt": {}, "ro": {}, "ru": {}, "sl": {}, "sr": {}, "sv": {}, "tr": {}, "vi": {}, "pt-BR": {}, "zh-CN": {}, "zh-TW": {} } }

Update Collection Request Payload

You can update a collection

namestring

The name of the collection. For multilingual collections, this will be the name of the default language's content.

Example: "collection 51"
descriptionstring

The description of the collection. For multilingual collections, this will be the description of the default language's content.

Example: "English description"
translated_contentobject or null(Group Translated Content)

The Translated Content of an Group. The keys are the locale codes and the values are the translated content of the Group.

parent_idstring or null

The id of the parent collection. If null then it will be updated as the first level collection.

Example: "6871118"
{ "name": "collection 51", "description": "English description", "translated_content": { "type": "group_translated_content", "ar": {}, "bg": {}, "bs": {}, "ca": {}, "cs": {}, "da": {}, "de": {}, "el": {}, "en": {}, "es": {}, "et": {}, "fi": {}, "fr": {}, "he": {}, "hr": {}, "hu": {}, "id": {}, "it": {}, "ja": {}, "ko": {}, "lt": {}, "lv": {}, "mn": {}, "nb": {}, "nl": {}, "pl": {}, "pt": {}, "ro": {}, "ru": {}, "sl": {}, "sr": {}, "sv": {}, "tr": {}, "vi": {}, "pt-BR": {}, "zh-CN": {}, "zh-TW": {} }, "parent_id": "6871118" }

Update Contact Request Payload

You can update a contact

rolestring

The role of the contact.

external_idstring

A unique identifier for the contact which is given to Intercom

emailstring

The contacts email

Example: "jdoe@example.com"
phonestring or null

The contacts phone

Example: "+353871234567"
namestring or null

The contacts name

Example: "John Doe"
avatarstring or null

An image URL containing the avatar of a contact

Example: "https://www.example.com/avatar_image.jpg"
signed_up_atinteger or null(date-time)

The time specified for when a contact signed up

Example: 1571672154
last_seen_atinteger or null(date-time)

The time when the contact was last seen (either where the Intercom Messenger was installed or when specified manually)

Example: 1571672154
owner_idinteger or null

The id of an admin that has been assigned account ownership of the contact

Example: 123
unsubscribed_from_emailsboolean or null

Whether the contact is unsubscribed from emails

Example: true
custom_attributesobject or null

The custom attributes which are set for the contact

{ "role": "string", "external_id": "string", "email": "jdoe@example.com", "phone": "+353871234567", "name": "John Doe", "avatar": "https://www.example.com/avatar_image.jpg", "signed_up_at": 1571672154, "last_seen_at": 1571672154, "owner_id": 123, "unsubscribed_from_emails": true, "custom_attributes": {} }

Update Conversation Request

Payload of the request to update a conversation

readboolean

Mark a conversation as read within Intercom.

Example: true
custom_attributesobject(Custom Attributes)

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.

{ "read": true, "custom_attributes": { "property1": "string", "property2": "string" } }

Update Data Attribute Request

archivedboolean

Whether the attribute is to be archived or not.

Example: false
descriptionstring

The readable description you see in the UI for the attribute.

Example: "My Data Attribute Description"
optionsArray of strings

To create list attributes. Provide a set of hashes with value as the key of the options you want to make. data_type must be string.

Example: ["option1","option2"]
messenger_writableboolean

Can this attribute be updated by the Messenger

Example: false
{ "archived": false, "description": "My Data Attribute Description", "options": [ "option1", "option2" ], "messenger_writable": false }

Update Ticket Request Payload

You can update a Ticket

ticket_attributesobject

The attributes set on the ticket.

Example: {"_default_title_":"example","_default_description_":"having a problem"}
statestring

The state of the ticket.

Enum"in_progress""waiting_on_customer""resolved"
Example: "submitted"
openboolean

Specify if a ticket is open. Set to false to close a ticket. Closing a ticket will also unsnooze it.

Example: true
is_sharedboolean

Specify whether the ticket is visible to users.

Example: true
snoozed_untilinteger(timestamp)

The time you want the ticket to reopen.

Example: 1673609604
assignmentobject
{ "ticket_attributes": { "_default_title_": "example", "_default_description_": "having a problem" }, "state": "submitted", "open": true, "is_shared": true, "snoozed_until": 1673609604, "assignment": { "admin_id": "123", "assignee_id": "123" } }

Update Ticket Type Attribute Request Payload

You can update a Ticket Type Attribute

namestring

The name of the ticket type attribute

Example: "Bug Priority"
descriptionstring

The description of the attribute presented to the teammate or contact

Example: "Priority level of the bug"
required_to_createboolean

Whether the attribute is required to be filled in when teammates are creating the ticket in Inbox.

Default false
Example: false
required_to_create_for_contactsboolean

Whether the attribute is required to be filled in when contacts are creating the ticket in Messenger.

Default false
Example: false
visible_on_createboolean

Whether the attribute is visible to teammates when creating a ticket in Inbox.

Default true
Example: true
visible_to_contactsboolean

Whether the attribute is visible to contacts when creating a ticket in Messenger.

Default true
Example: true
multilineboolean

Whether the attribute allows multiple lines of text (only applicable to string attributes)

Example: false
list_itemsstring

A comma delimited list of items for the attribute value (only applicable to list attributes)

Example: "Low Priority,Medium Priority,High Priority"
allow_multiple_valuesboolean

Whether the attribute allows multiple files to be attached to it (only applicable to file attributes)

Example: false
archivedboolean

Whether the attribute should be archived and not shown during creation of the ticket (it will still be present on previously created tickets)

Example: false
{ "name": "Bug Priority", "description": "Priority level of the bug", "required_to_create": false, "required_to_create_for_contacts": false, "visible_on_create": true, "visible_to_contacts": true, "multiline": false, "list_items": "Low Priority,Medium Priority,High Priority", "allow_multiple_values": false, "archived": false }

Update Ticket Type Request Payload

The request payload for updating a ticket type. You can copy the icon property for your ticket type from Twemoji Cheatsheet

namestring

The name of the ticket type.

Example: "Bug"
descriptionstring

The description of the ticket type.

Example: "A bug has been occured"
categorystring

Category of the Ticket Type.

Enum"Customer""Back-office""Tracker"
Example: "Customer"
iconstring

The icon of the ticket type.

Default "🎟️"
Example: "🐞"
archivedboolean

The archived status of the ticket type.

Example: false
is_internalboolean

Whether the tickets associated with this ticket type are intended for internal use only or will be shared with customers. This is currently a limited attribute.

Default false
Example: false
{ "name": "Bug", "description": "A bug has been occured", "category": "Customer", "icon": "🐞", "archived": false, "is_internal": false }

Update Visitor Request Payload

Update an existing visitor.

Any of:

Update an existing visitor.

idstringrequired

A unique identified for the visitor which is given by Intercom.

Example: "8a88a590-e"
user_idstring

A unique identified for the visitor which is given by you.

Example: "123"
namestring

The visitor's name.

Example: "Christian Bale"
custom_attributesobject

The custom attributes which are set for the visitor.

Example: {"paid_subscriber":true,"monthly_spend":155.5,"team_mates":9}
{ "id": "8a88a590-e", "user_id": "123", "name": "Christian Bale", "custom_attributes": { "paid_subscriber": true, "monthly_spend": 155.5, "team_mates": 9 } }

Visitor

Visitors are useful for representing anonymous people that have not yet been identified. They usually represent website visitors. Visitors are not visible in Intercom platform. The Visitors resource provides methods to fetch, update, convert and delete.

typestring

Value is 'visitor'

Default "visitor"
Example: "visitor"
idstring

The Intercom defined id representing the Visitor.

Example: "530370b477ad7120001d"
user_idstring

Automatically generated identifier for the Visitor.

Example: "8a88a590-e1c3-41e2-a502-e0649dbf721c"
anonymousboolean

Identifies if this visitor is anonymous.

Example: false
emailstring(email)

The email of the visitor.

Example: "jane.doe@example.com"
phonestring or null

The phone number of the visitor.

Example: "555-555-5555"
namestring or null

The name of the visitor.

Example: "Jane Doe"
pseudonymstring or null

The pseudonym of the visitor.

Example: "Red Duck from Dublin"
avatarobject
app_idstring

The id of the app the visitor is associated with.

Example: "hfi1bx4l"
companiesobject
location_dataobject
las_request_atinteger

The time the Lead last recorded making a request.

Example: 1663597260
created_atinteger

The time the Visitor was added to Intercom.

Example: 1663597223
remote_created_atinteger

The time the Visitor was added to Intercom.

Example: 1663597223
signed_up_atinteger

The time the Visitor signed up for your product.

Example: 1663597223
updated_atinteger

The last time the Visitor was updated.

Example: 1663597260
session_countinteger

The number of sessions the Visitor has had.

Example: 1
social_profilesobject
owner_idstring or null

The id of the admin that owns the Visitor.

Example: "5169261"
unsubscribed_from_emailsboolean

Whether the Visitor is unsubscribed from emails.

Example: false
marked_email_as_spamboolean

Identifies if this visitor has marked an email as spam.

Example: false
has_hard_bouncedboolean

Identifies if this visitor has had a hard bounce.

Example: false
tagsobject
segmentsobject
custom_attributesobject

The custom attributes you have set on the Visitor.

referrerstring or null

The referer of the visitor.

Example: "https://www.google.com/"
utm_campaignstring or null

The utm_campaign of the visitor.

Example: "intercom-link"
utm_contentstring or null

The utm_content of the visitor.

Example: "banner"
utm_mediumstring or null

The utm_medium of the visitor.

Example: "email"
utm_sourcestring or null

The utm_source of the visitor.

Example: "Intercom"
utm_termstring or null

The utm_term of the visitor.

Example: "messenger"
do_not_trackboolean or null

Identifies if this visitor has do not track enabled.

Example: false
{ "type": "visitor", "id": "530370b477ad7120001d", "user_id": "8a88a590-e1c3-41e2-a502-e0649dbf721c", "anonymous": false, "email": "jane.doe@example.com", "phone": "555-555-5555", "name": "Jane Doe", "pseudonym": "Red Duck from Dublin", "avatar": { "type": "avatar", "image_url": "https://example.com/avatar.png" }, "app_id": "hfi1bx4l", "companies": { "type": "company.list", "companies": [] }, "location_data": { "type": "location_data", "city_name": "Dublin", "continent_code": "EU", "country_code": "IRL", "country_name": "Ireland", "postal_code": "D02 N960", "region_name": "Leinster", "timezone": "Europe/Dublin" }, "las_request_at": 1663597260, "created_at": 1663597223, "remote_created_at": 1663597223, "signed_up_at": 1663597223, "updated_at": 1663597260, "session_count": 1, "social_profiles": { "type": "social_profile.list", "social_profiles": [] }, "owner_id": "5169261", "unsubscribed_from_emails": false, "marked_email_as_spam": false, "has_hard_bounced": false, "tags": { "type": "tag.list", "tags": [] }, "segments": { "type": "segment.list", "segments": [] }, "custom_attributes": { "property1": "string", "property2": "string" }, "referrer": "https://www.google.com/", "utm_campaign": "intercom-link", "utm_content": "banner", "utm_medium": "email", "utm_source": "Intercom", "utm_term": "messenger", "do_not_track": false }

Visitor Deleted Object

Response returned when an object is deleted

idstring

The unique identifier for the visitor which is given by Intercom.

Example: "530370b477ad7120001d"
typestring

The type of object which was deleted

Value"visitor"
Example: "visitor"
user_idstring

Automatically generated identifier for the Visitor.

Example: "8a88a590-e1c3-41e2-a502-e0649dbf721c"
{ "id": "530370b477ad7120001d", "type": "visitor", "user_id": "8a88a590-e1c3-41e2-a502-e0649dbf721c" }