The intercom API reference.
URL https://developers.intercom.com
License MIT
The intercom API reference.
With the AI Content APIs, you can create and manage External Pages and Content Import Sources for your Fin Content Library.
External Pages are pages that you want Fin to be able to answer questions about. The API for External Pages is a great way to ingest into your Fin Content Library pages that are not publicly accessible and hence can't be crawled by Intercom.
Content Import Sources are the sources of those pages, and they are used to determine the default audience for the pages (configured via the UI). You should create a Content Import Source for each source of External Pages that you want to ingest into your Fin Content Library.
You can then iterate through the content from that source via its API and POST it to the External Pages endpoint. That endpoint has an external_id parameter which allows you to specify the identifier from the source. The endpoint will then either create a new External Page or update an existing one as appropriate.",
Activities performed by Admins.
{ "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\"." }
A paginated list of activity logs.
String representing the object's type. Always has the value activity_log.list.
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": "activity_log.list", "pages": { "type": "pages", "page": 1, "next": { … }, "per_page": 2, "total_pages": 13 }, "activity_logs": [ { … } ] }
Additional data provided about Admin activity.
The unique identifier for the contact which is provided by the Client.
The away mode status which is set to true when away and false when returned.
Indicates if conversations should be reassigned while an Admin is away.
The action that initiated the status change.
Indicates if the status was changed automatically or manually.
{ "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" }
Payload of the request to reply on behalf of an admin
The text body of the reply. Notes accept some HTML formatting. Must be present for comment and note message types.
The time the reply was created. If not provided, the current time will be used.
The quick reply options to display. Must be present for quick_reply message types.
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" ], "attachment_files": [ { … } ] }
Payload of the request to reply on behalf of an admin
The text body of the reply. Notes accept some HTML formatting. Must be present for comment and note message types.
The time the reply was created. If not provided, the current time will be used.
The quick reply options to display. Must be present for quick_reply message types.
{ "message_type": "comment", "type": "admin", "body": "Hello there!", "admin_id": "3156780", "created_at": 1590000000, "reply_options": [ { … } ], "attachment_urls": [ "http://example.com" ] }
Admins are the teammate accounts that have access to a workspace
Identifies if this admin is set to automatically reassign new conversations to the apps default inbox.
Identifies if this admin has a paid inbox seat to restrict/allow features that require them.
This is a list of ids of the teams that this admin is part of.
{ "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 } }
The Content of an Article.
The type of object - article_content .
The description of the article.
The time when the article was last updated (seconds).
{ "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" }
This will return a list of articles for the App.
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", "pages": { "type": "pages", "page": 1, "next": { … }, "per_page": 2, "total_pages": 13 }, "total_count": 1, "data": [ { … } ] }
The statistics of an article.
The type of object - article_statistics.
The percentage of happy reactions the article has received against other types of reaction.
The percentage of neutral reactions the article has received against other types of reaction.
{ "type": "article_statistics", "views": 10, "conversions": 0, "reactions": 10, "happy_reaction_percentage": 40, "neutral_reaction_percentage": 40, "sad_reaction_percentage": 20 }
The Translated Content of an Article. The keys are the locale codes and the values are the translated content of the article.
The type of object - article_translated_content.
{ "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" } }
Payload of the request to assign a conversation
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).
{ "message_type": "assignment", "type": "admin", "admin_id": "12345", "assignee_id": "4324241", "body": "Let me pass you over to one of my colleagues." }
This will return a list of Collections for the App.
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", "pages": { "type": "pages", "page": 1, "next": { … }, "per_page": 2, "total_pages": 13 }, "total_count": 1, "data": [ { … } ] }
A list of Contact Objects
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 } }
This will return a list of companies for the App.
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", "pages": { "type": "pages", "page": 1, "next": { … }, "per_page": 2, "total_pages": 13 }, "total_count": 100, "data": [ { … } ] }
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.
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": [ { … } ], "pages": { "type": "pages", "page": 1, "next": { … }, "per_page": 2, "total_pages": 13 }, "total_count": 100, "scroll_param": "25b649f7-4d33-4ef6-88f5-60e5b8244309" }
archived contact object
The unique identifier for the contact which is given by Intercom.
The unique identifier for the contact which is provided by the Client.
{ "type": "contact", "id": "5ba682d23d7cf92bef87bfd4", "external_id": "f3b87a2e09d514c6c2e79b9a", "archived": true }
A list of Company Objects
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 } }
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.
Url to get more company resources for this contact
Int representing the total number of companyies attached to this contact
{ "url": "/contacts/5ba682d23d7cf92bef87bfd4/companies", "total_count": 100, "has_more": true }
deleted contact object
The unique identifier for the contact which is given by Intercom.
The unique identifier for the contact which is provided by the Client.
{ "type": "contact", "id": "5ba682d23d7cf92bef87bfd4", "external_id": "f3b87a2e09d514c6c2e79b9a", "deleted": true }
Contacts are your users in Intercom.
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 } }
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.
Url to get more company resources for this contact
Int representing the total number of companyies attached to this contact
{ "data": [ { … } ], "url": "/contacts/5ba682d23d7cf92bef87bfd4/notes", "total_count": 100, "has_more": true }
Payload of the request to reply on behalf of a contact using their intercom_user_id
A list of files that will be added as attachments.
The time the reply was created. If not provided, the current time will be used.
{ "intercom_user_id": "string", "attachment_files": [ { … } ], "message_type": "comment", "type": "user", "body": "string", "created_at": 1590000000, "attachment_urls": [ "http://example.com" ] }
Payload of the request to reply on behalf of a contact using their email
A list of files that will be added as attachments.
The time the reply was created. If not provided, the current time will be used.
{ "email": "string", "attachment_files": [ { … } ], "message_type": "comment", "type": "user", "body": "string", "created_at": 1590000000, "attachment_urls": [ "http://example.com" ] }
Payload of the request to reply on behalf of a contact using their intercom_user_id
A list of files that will be added as attachments.
The time the reply was created. If not provided, the current time will be used.
{ "intercom_user_id": "string", "attachment_files": [ { … } ], "message_type": "comment", "type": "user", "body": "string", "created_at": 1590000000, "attachment_urls": [ "http://example.com" ] }
Payload of the request to reply on behalf of a contact using their email
The time the reply was created. If not provided, the current time will be used.
{ "email": "string", "message_type": "comment", "type": "user", "body": "string", "created_at": 1590000000, "attachment_urls": [ "http://example.com" ] }
Payload of the request to reply on behalf of a contact using their intercom_user_id
The time the reply was created. If not provided, the current time will be used.
{ "intercom_user_id": "string", "message_type": "comment", "type": "user", "body": "string", "created_at": 1590000000, "attachment_urls": [ "http://example.com" ] }
Payload of the request to reply on behalf of a contact using their intercom_user_id
The time the reply was created. If not provided, the current time will be used.
{ "intercom_user_id": "string", "message_type": "comment", "type": "user", "body": "string", "created_at": 1590000000, "attachment_urls": [ "http://example.com" ] }
Payload of the request to reply on behalf of a contact using their user_id
The time the reply was created. If not provided, the current time will be used.
{ "user_id": "string", "message_type": "comment", "type": "user", "body": "string", "created_at": 1590000000, "attachment_urls": [ "http://example.com" ] }
Payload of the request to reply on behalf of a contact using their user_id
A list of files that will be added as attachments. You can include up to 10 files.
The time the reply was created. If not provided, the current time will be used.
{ "user_id": "string", "attachment_files": [ { … } ], "message_type": "comment", "type": "user", "body": "string", "created_at": 1590000000, "attachment_urls": [ "http://example.com" ] }
An object containing Subscription Types meta data about the SubscriptionTypes that a contact has.
This object represents the subscriptions attached to a contact.
Url to get more subscription type resources for this contact
Int representing the total number of subscription types attached to this contact
{ "data": [ { … } ], "url": "/contacts/5ba682d23d7cf92bef87bfd4/subscriptions", "total_count": 100, "has_more": true }
unarchived contact object
The unique identifier for the contact which is given by Intercom.
The unique identifier for the contact which is provided by the Client.
{ "type": "contact", "id": "5ba682d23d7cf92bef87bfd4", "external_id": "f3b87a2e09d514c6c2e79b9a", "archived": false }
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.
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 } }
A Conversation Part represents a message in the conversation.
The message body, which may contain HTML. For Twitter, this will show a generic message regarding why the body is obscured.
The time the user was notified with the conversation part.
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.
{ "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, "email_message_metadata": { "subject": "Question about my order", "email_address_headers": [ … ] } }
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.
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.
{ "type": "conversation_part.list", "conversation_parts": [ { … } ], "total_count": 2 }
The Conversation Rating object which contains information on the rating and/or remark added by a Contact and the Admin assigned to the conversation.
The time the rating was requested in the conversation being rated.
{ "rating": 5, "remark": "", "created_at": 1671028894, "contact": { "type": "contact", "id": "5ba682d23d7cf92bef87bfd4", "external_id": "f3b87a2e09d514c6c2e79b9a" }, "teammate": { "type": "contact", "id": "1a2b3c" } }
The Conversation Part that originated this conversation, which can be Contact, Admin, Campaign, Automated or Operator initiated.
This includes conversation, email, facebook, instagram, phone_call, phone_switch, push, sms, twitter and whatsapp.
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).
Optional. The message subject. For Twitter, this will show a generic message regarding why the subject is obscured.
The message body, which may contain HTML. For Twitter, this will show a generic message regarding why the body is obscured.
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.
The URL where the conversation was started. For Twitter, Email, and Bots, this will be blank.
{ "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 }
A Statistics object containing all information required for reporting, with timestamps and calculated metrics.
Duration until last assignment before first admin reply. In seconds.
Duration until first admin reply. Subtracts out of business hours. In seconds.
Duration until conversation was closed first time. Subtracts out of business hours. In seconds.
Duration until conversation was closed last time. Subtracts out of business hours. In seconds.
Median based on all admin replies after a contact reply. Subtracts out of business hours. In seconds.
Time of first text conversation part from a contact.
Time of first assignment after first_contact_reply_at.
Time of first admin reply after first_contact_reply_at.
Time of first close after first_contact_reply_at.
Time of last assignment after first_contact_reply_at.
Time of first admin reply since most recent assignment.
Time of the last conversation part from a contact.
Time of the last conversation part from an admin.
The last admin who closed the conversation. Returns a reference to an Admin object.
An array of conversation response time objects
An array of conversation response time objects within office hours
{ "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, "assigned_team_first_response_time_by_team": [ { … } ], "assigned_team_first_response_time_in_office_hours": [ { … } ], "handling_time": 2310 }
You can convert a Conversation to a Ticket
The ID of the type of ticket you want to convert the conversation to
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).
{ "ticket_type_id": "1234", "attributes": { "_default_title_": "Found a bug", "_default_description_": "The button is not working" } }
You can merge a Visitor to a Contact of role type lead or user.
The unique identifiers retained after converting or merging.
The unique identifiers retained after converting or merging.
The unique identifier for the contact which is given by Intercom.
A unique identifier for the contact which is given to Intercom, which will be represented as external_id.
The unique identifiers to convert a single Visitor.
The unique identifiers to convert a single Visitor.
The unique identifier for the contact which is given by Intercom.
A unique identifier for the contact which is given to Intercom.
{ "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" } }
You can create an Article
The title of the article.For multilingual articles, this will be the title of the default language's content.
The description of the article. For multilingual articles, this will be the description of the default language's content.
The content of the article. For multilingual articles, this will be the body of the default language's content.
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.
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.
The id of the article's parent collection or section. An article without this field stands alone.
The type of parent, which can either be a collection or section.
{ "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": { … } } }
You can create a collection
The name of the collection. For multilingual collections, this will be the name of the default language's content.
The description of the collection. For multilingual collections, this will be the description of the default language's content.
The Translated Content of an Group. The keys are the locale codes and the values are the translated content of the Group.
The id of the parent collection. If null then it will be created as the first level collection.
{ "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" }
Payload to create a contact
Payload to create a contact
An image URL containing the avatar of a contact
The time specified for when a contact signed up
The time when the contact was last seen (either where the Intercom Messenger was installed or when specified manually)
The id of an admin that has been assigned account ownership of the contact
Whether the contact is unsubscribed from emails
{ "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": {} }
You can add an Content Import Source to your Fin Content Library.
If you intend to create or update External Pages via the API, this should be set to api.
The status of the content import source.
{ "sync_behavior": "api", "status": "active", "url": "https://help.example.com" }
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.
{ "from": { "type": "user", "id": "536e564f316c83104c000020" }, "body": "Hello" }
The model that the data attribute belongs to.
The type of data stored for this attribute.
The readable description you see in the UI for the attribute.
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.
{ "name": "My Data Attribute", "model": "contact", "data_type": "string", "description": "My Data Attribute Description", "options": [ "option1", "option2" ], "messenger_writable": false }
The name of the event that occurred. This is presented to your App's admins when filtering and creating segments - a good event name is typically a past tense 'verb-noun' combination, to improve readability, for example updated-plan.
The time the event occurred as a UTC Unix timestamp
The unique identifier for the contact (lead or user) which is given by Intercom.
An email address for your user. An email should only be used where your application uses email to uniquely identify users.
{ "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" } }
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_id": "314159", "event_summaries": { "event_name": "invited-friend", "count": 1, "first": 1671028894, "last": 1671028894 } }
You can add an External Page to your Fin Content Library.
The URL of the external page. This will be used by Fin to link end users to the page it based its answer on.
Whether the external page should be used to answer questions by Fin.
The unique identifier for the source of the external page which was given by Intercom. Every external page must be associated with a Content Import Source which represents the place it comes from and from which it inherits a default audience (configured in the UI). For a new source, make a POST request to the Content Import Source endpoint and an ID for the source will be returned in the response.
{ "title": "Getting started with...", "html": "<p>Hello world!</p>", "url": "https://help.example.com/en/articles/1234-getting-started", "fin_availability": true, "locale": "en", "source_id": 1234, "external_id": "5678" }
You can create a message
You can create a message
The kind of message being created. Values: in_app or email.
The content of the message. HTML and plaintext are supported.
The style of the outgoing message. Possible values plain or personal.
The sender of the message. If not provided, the default sender will be used.
The sender of the message. If not provided, the default sender will be used.
The time the message was created. If not provided, the current time will be used.
{ "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 }
You can create or update a Company
The company id you have defined for the company. Can't be updated
The URL for this company's website. Please note that the value specified here is not validated. Accepts any string.
A hash of key/value pairs containing any other data about the company you want Intercom to store.
{ "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 }
Payload to create or update a Custom Object instance
A unique identifier for the Custom Object instance in the external system it originated from.
The time when the Custom Object instance was created in the external system it originated from.
The time when the Custom Object instance was last updated in the external system it originated from.
{ "external_id": "string", "external_created_at": 1571672154, "external_updated_at": 1571672154, "custom_attributes": {} }
Payload of the request to reply on behalf of a contact using their intercom_user_id
The time the reply was created. If not provided, the current time will be used.
{ "intercom_user_id": "string", "message_type": "comment", "type": "user", "body": "string", "created_at": 1590000000, "attachment_urls": [ "http://example.com" ] }
You can create a Ticket
The list of contacts (users or leads) affected by this ticket. Currently only one is allowed
The ID of the company that the ticket is associated with. The unique identifier for the company which is given by Intercom
The time the ticket was created. If not provided, the current time will be used.
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).
{ "ticket_type_id": "1234", "contacts": [ { … } ], "company_id": "5f4d3c1c-7b1b-4d7d-a97e-6095715c6632", "created_at": 1590000000, "ticket_attributes": { "_default_title_": "Found a bug", "_default_description_": "The button is not working" } }
You can create a Ticket Type Attribute
The description of the attribute presented to the teammate or contact
The data type of the attribute
Whether the attribute is required to be filled in when teammates are creating the ticket in Inbox.
Whether the attribute is required to be filled in when contacts are creating the ticket in Messenger.
Whether the attribute is visible to teammates when creating a ticket in Inbox.
Whether the attribute is visible to contacts when creating a ticket in Messenger.
Whether the attribute allows multiple lines of text (only applicable to string attributes)
A comma delimited list of items for the attribute value (only applicable to list attributes)
{ "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 }
The request payload for creating a ticket type. You can copy the icon property for your ticket type from Twemoji Cheatsheet
{ "name": "Bug", "description": "Used for tracking bugs", "category": "Customer", "icon": "🐞", "is_internal": false }
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": "pages", "page": 1, "next": { "per_page": 2, "starting_after": "your-cursor-from-response" }, "per_page": 2, "total_pages": 13 }
This will return a list of data events for the App.
{ "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" } }
A CSV output file
The company ID of the user in relation to the message that was sent. Will return -1 if no company is present.
The specific content that was received. In an A/B test each version has its own Content ID.
As you edit content we record new versions. This ID can help you determine which version of a piece of content that was received.
ID for this receipt. Will be included with any related stats in other files to identify this specific delivery of a message.
The id of the series that this content is part of. Will return -1 if not part of a series.
The id of the series node that this ruleset is associated with. Each block in a series has a corresponding node_id.
The first time a user replied to this message if the content was able to receive replies.
The first time a user completed this message if the content was able to be completed e.g. Tours, Surveys.
The first time the series this message was a part of was completed by the user.
The first time the series this message was a part of was disengaged by the user.
The first time the series this message was a part of was exited by the 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 }
The API will return an Error List for a failed request, which will contain one or more Error objects.
An array of one or more error objects
A string indicating the kind of error, used to further qualify the HTTP response code
Optional. Human readable description of the error.
{ "type": "error.list", "request_id": "f93ecfa8-d08a-4325-8694-89aeb89c8f85", "errors": [ { … } ] }
The value describing a file upload set for a custom attribute
The url of the file. This is a temporary URL and will expire after 30 minutes.
{ "type": "upload", "name": "Screenshot.png", "url": "https://intercom-attachments-1.com/.../Screenshot.png", "content_type": "image/png", "filesize": 11308309, "width": 3024, "height": 1964 }
The Translated Content of an Group. The keys are the locale codes and the values are the translated content of the Group.
The type of object - group_translated_content.
{ "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" } }
A News Item is a content type in Intercom enabling you to announce product updates, company news, promotions, events and more with your customers.
The news item body, which may contain HTML.
The id of the sender of the news item. Must be a teammate on the workspace.
News items will not be visible to your users in the assigned newsfeeds until they are set live.
When set to true, the news item will appear in the messenger newsfeed without showing a notification badge.
Label names displayed to users to categorize the news item.
Ordered list of emoji reactions to the news item. When empty, reactions are disabled.
{ "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": [ { … } ] }
A paginated list of notes associated with a contact.
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 } }
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.
A link to the next page of results. A response that does not contain a next link does not have further data to fetch.
{ "type": "pages", "page": 1, "next": "http://example.com", "per_page": 50, "total_pages": 1 }
Paginated Response
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", "pages": { "type": "pages", "page": 1, "next": { … }, "per_page": 2, "total_pages": 13 }, "total_count": 1, "data": [ { … } ] }
Payload of the request to reply on behalf of a contact using their intercom_user_id
A list of files that will be added as attachments.
The time the reply was created. If not provided, the current time will be used.
{ "intercom_user_id": "string", "attachment_files": [ { … } ], "message_type": "comment", "type": "user", "body": "string", "created_at": 1590000000, "attachment_urls": [ "http://example.com" ] }
Search using Intercoms Search APIs.
Search using Intercoms Search APIs with a single filter.
The accepted operators you can use to define how you want to search for the value.
{ "query": { "field": "created_at", "operator": ">", "value": "73732934" }, "pagination": { "per_page": 2, "starting_after": "your-cursor-from-response" } }
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.
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.{ "type": "conversation_sla_summary", "sla_name": "", "sla_status": "hit" }
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_.
{ "_default_title_": "Found a bug", "_default_description_": "The button's not working" }
Tickets are how you track requests from your users.
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 } }
A Ticket Part representing a note, comment, or quick_reply on a ticket
The author that wrote or triggered the part. Can be a bot, admin, team or user.
{ "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 }
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).
{ "_default_title_": "Found a bug", "_default_description_": "The button is not working" }
Ticket type attribute, used to define each data field to be captured in a ticket.
String representing the object's type. Always has the value ticket_type_attribute.
The id of the workspace that the ticket type attribute belongs to.
The type of the data attribute (allowed values: "string list integer decimal boolean datetime files")
Whether the attribute is required or not for teammates.
Whether the attribute is required or not for contacts.
Whether the attribute is visible or not to teammates.
Whether the attribute is visible or not to contacts.
{ "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 }
You can Update an Article
The title of the article.For multilingual articles, this will be the title of the default language's content.
The description of the article. For multilingual articles, this will be the description of the default language's content.
The content of the article. For multilingual articles, this will be the body of the default language's content.
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.
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.
The id of the article's parent collection or section. An article without this field stands alone.
The type of parent, which can either be a collection or section.
{ "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": { … } } }
You can update a collection
The name of the collection. For multilingual collections, this will be the name of the default language's content.
The description of the collection. For multilingual collections, this will be the description of the default language's content.
The Translated Content of an Group. The keys are the locale codes and the values are the translated content of the Group.
{ "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" }
You can update a contact
An image URL containing the avatar of a contact
The time specified for when a contact signed up
The time when the contact was last seen (either where the Intercom Messenger was installed or when specified manually)
The id of an admin that has been assigned account ownership of the contact
Whether the contact is unsubscribed from emails
{ "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": {} }
You can modify a Content Import Source of your Fin Content Library.
If you intend to create or update External Pages via the API, this should be set to api. You can not change the value to or from api.
The status of the content import source.
{ "sync_behavior": "api", "status": "active", "url": "https://help.example.com" }
The readable description you see in the UI for the attribute.
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.
{ "archived": false, "description": "My Data Attribute Description", "options": [ "option1", "option2" ], "messenger_writable": false }
You can update an External Page in your Fin Content Library.
The URL of the external page. This will be used by Fin to link end users to the page it based its answer on.
Whether the external page should be used to answer questions by Fin.
The unique identifier for the source of the external page which was given by Intercom. Every external page must be associated with a Content Import Source which represents the place it comes from and from which it inherits a default audience (configured in the UI). For a new source, make a POST request to the Content Import Source endpoint and an ID for the source will be returned in the response.
{ "title": "Getting started with...", "html": "<p>Hello world!</p>", "url": "https://help.example.com/en/articles/1234-getting-started", "fin_availability": true, "locale": "en", "source_id": 1234, "external_id": "5678" }
You can update a Ticket
The attributes set on the ticket.
Specify if a ticket is open. Set to false to close a ticket. Closing a ticket will also unsnooze it.
{ "ticket_attributes": { "_default_title_": "example", "_default_description_": "having a problem" }, "ticket_state_id": "123", "open": true, "is_shared": true, "snoozed_until": 1673609604, "assignment": { "admin_id": "123", "assignee_id": "123" } }
You can update a Ticket Type Attribute
The description of the attribute presented to the teammate or contact
Whether the attribute is required to be filled in when teammates are creating the ticket in Inbox.
Whether the attribute is required to be filled in when contacts are creating the ticket in Messenger.
Whether the attribute is visible to teammates when creating a ticket in Inbox.
Whether the attribute is visible to contacts when creating a ticket in Messenger.
Whether the attribute allows multiple lines of text (only applicable to string attributes)
A comma delimited list of items for the attribute value (only applicable to list attributes)
Whether the attribute allows multiple files to be attached to it (only applicable to file attributes)
{ "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 }
The request payload for updating a ticket type. You can copy the icon property for your ticket type from Twemoji Cheatsheet
{ "name": "Bug", "description": "A bug has been occured", "category": "Customer", "icon": "🐞", "archived": false, "is_internal": false }
Update an existing visitor.
Update an existing visitor.
A unique identified for the visitor which is given by Intercom.
{ "id": "8a88a590-e", "user_id": "123", "name": "Christian Bale", "custom_attributes": { "paid_subscriber": true, "monthly_spend": 155.5, "team_mates": 9 } }
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.
Automatically generated identifier for the Visitor.
{ "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 }