This is external content
" url: https://support.example.com/us/3 ai_agent_availability: true ai_copilot_availability: true fin_availability: true locale: en source_id: 42 external_id: '3' created_at: 1734537269 updated_at: 1734537269 last_ingested_at: 1734537269 - id: '18' type: external_page title: My External Content html: "This is external content
" url: https://support.example.com/us/2 ai_agent_availability: true ai_copilot_availability: true fin_availability: true locale: en source_id: 41 external_id: '2' created_at: 1734537269 updated_at: 1734537269 last_ingested_at: 1734537269 - id: '17' type: external_page title: My External Content html: "This is external content
" url: https://support.example.com/us/1 ai_agent_availability: true ai_copilot_availability: true fin_availability: true locale: en source_id: 40 external_id: '1' created_at: 1734537269 updated_at: 1734537269 last_ingested_at: 1734537269 pages: type: pages page: 1 per_page: 50 total_pages: 1 total_count: 3 type: list schema: "$ref": "#/components/schemas/external_pages_list" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: bd0c53dd-d3fd-4095-be25-94537a8ba364 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" post: summary: Create an external page (or update an external page by external ID) parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" tags: - AI Content operationId: createExternalPage description: You can create a new external page by sending a POST request to this endpoint. If an external page already exists with the specified source_id and external_id, it will be updated instead. responses: '200': description: successful content: application/json: examples: successful: value: id: '21' type: external_page title: Test html: "This is external content
" url: https://support.example.com/us/6 ai_agent_availability: true ai_copilot_availability: true fin_availability: true locale: en source_id: 46 external_id: '5' created_at: 1734537278 updated_at: 1734537278 last_ingested_at: 1734537278 schema: "$ref": "#/components/schemas/external_page" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: 504cde98-f786-4f64-b373-e26a6a41fd11 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" put: summary: Update an external page parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" tags: - AI Content operationId: updateExternalPage description: You can update an existing external page (if it was created via the API). responses: '200': description: successful content: application/json: examples: successful: value: id: '24' type: external_page title: Test html: "Body of the Article
author_id: 991267497 state: published created_at: 1734537288 updated_at: 1734537288 url: http://help-center.test/myapp-68/en/articles/42-thanks-for-everything schema: "$ref": "#/components/schemas/article" '400': description: Bad Request content: application/json: examples: Bad Request: value: type: error.list request_id: e522ca8a-cd15-404e-84b3-7f7536003d4a errors: - code: parameter_not_found message: author_id must be in the main body or default locale translated_content object schema: "$ref": "#/components/schemas/error" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: 85e91429-72df-4e69-8a12-b55793dff59f errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" requestBody: content: application/json: schema: "$ref": "#/components/schemas/create_article_request" examples: article_created: summary: article created value: title: Thanks for everything description: Description of the Article body: Body of the Article author_id: 991267497 state: published parent_id: 145 parent_type: collection translated_content: fr: title: Merci pour tout description: Description de l'article body: Corps de l'article author_id: 991267497 state: published bad_request: summary: Bad Request value: title: Thanks for everything description: Description of the Article body: Body of the Article state: published "/articles/{article_id}": get: summary: Retrieve an article parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: article_id in: path required: true description: The unique identifier for the article which is given by Intercom. example: 123 schema: type: integer tags: - Articles operationId: retrieveArticle description: You can fetch the details of a single article by making a GET request to `https://api.intercom.io/articles/New gifts in store for the jolly season
author_id: 991267508 state: published created_at: 1734537297 updated_at: 1734537298 url: http://help-center.test/myapp-80/en/articles/48-christmas-is-here schema: "$ref": "#/components/schemas/article" '404': description: Article Not Found content: application/json: examples: Article Not Found: value: type: error.list request_id: f9adccb2-9fca-4b87-bbb7-65f2af5e1d78 errors: - code: not_found message: Resource Not Found schema: "$ref": "#/components/schemas/error" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: d1ea223d-bb62-42e3-8bcf-30fdcf7dbd99 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" requestBody: content: application/json: schema: "$ref": "#/components/schemas/update_article_request" examples: successful: summary: successful value: title: Christmas is here! body: "New gifts in store for the jolly season
" article_not_found: summary: Article Not Found value: title: Christmas is here! body: "New gifts in store for the jolly season
" delete: summary: Delete an article parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: article_id in: path required: true description: The unique identifier for the article which is given by Intercom. example: 123 schema: type: integer tags: - Articles operationId: deleteArticle description: You can delete a single article by making a DELETE request to `https://api.intercom.io/articles/New gifts in store for the jolly season
" internal_article_not_found: summary: Internal article not found value: title: Christmas is here! body: "New gifts in store for the jolly season
" delete: summary: Delete an internal article parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: internal_article_id in: path required: true description: The unique identifier for the internal article which is given by Intercom. example: 123 schema: type: integer tags: - Internal Articles operationId: deleteInternalArticle description: You can delete a single internal article by making a DELETE request to `https://api.intercom.io/internal_articles/This is a note.
" total_count: 1 pages: type: pages next: page: 1 per_page: 50 total_pages: 1 schema: "$ref": "#/components/schemas/note_list" '404': description: Company not found content: application/json: examples: Company not found: value: type: error.list request_id: 57055cde-3d0d-4c67-b5c9-b20b80340bf0 errors: - code: company_not_found message: Company Not Found schema: "$ref": "#/components/schemas/error" "/companies/list": post: summary: List all companies parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: page in: query required: false description: The page of results to fetch. Defaults to first page example: 1 schema: type: integer - name: per_page in: query required: false description: How many results to return per page. Defaults to 15 example: 15 schema: type: integer - name: order in: query required: false description: "`asc` or `desc`. Return the companies in ascending or descending order. Defaults to desc" example: desc schema: type: string tags: - Companies operationId: listAllCompanies description: | You can list companies. The company list is sorted by the `last_request_at` field and by default is ordered descending, most recently requested first. Note that the API does not include companies who have no associated users in list responses. When using the Companies endpoint and the pages object to iterate through the returned companies, there is a limit of 10,000 Companies that can be returned. If you need to list or iterate on more than 10,000 Companies, please use the [Scroll API](https://developers.intercom.com/reference#iterating-over-all-companies). {% admonition type="warning" name="Pagination" %} You can use pagination to limit the number of results returned. The default is `20` results per page. See the [pagination section](https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis/pagination/#pagination-for-list-apis) for more details on how to use the `starting_after` param. {% /admonition %} responses: '200': description: Successful content: application/json: examples: Successful: value: type: list data: - type: company company_id: remote_companies_scroll_2 id: 6762f0941bb69f9f2193bb25 app_id: this_is_an_id189_that_should_be_at_least_ name: IntercomQATest1 remote_created_at: 1734537364 created_at: 1734537364 updated_at: 1734537364 monthly_spend: 0 session_count: 0 user_count: 4 tags: type: tag.list tags: [] segments: type: segment.list segments: [] plan: {} custom_attributes: {} pages: type: pages next: page: 1 per_page: 15 total_pages: 1 total_count: 1 schema: "$ref": "#/components/schemas/company_list" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: 537ccc45-2cae-4e72-ac2f-849f1422a771 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" "/companies/scroll": get: summary: Scroll over all companies parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: scroll_param in: query required: false description: '' schema: type: string tags: - Companies operationId: scrollOverAllCompanies description: |2 The `list all companies` functionality does not work well for huge datasets, and can result in errors and performance problems when paging deeply. The Scroll API provides an efficient mechanism for iterating over all companies in a dataset. - Each app can only have 1 scroll open at a time. You'll get an error message if you try to have more than one open per app. - If the scroll isn't used for 1 minute, it expires and calls with that scroll param will fail - If the end of the scroll is reached, "companies" will be empty and the scroll parameter will expire {% admonition type="info" name="Scroll Parameter" %} You can get the first page of companies by simply sending a GET request to the scroll endpoint. For subsequent requests you will need to use the scroll parameter from the response. {% /admonition %} {% admonition type="danger" name="Scroll network timeouts" %} Since scroll is often used on large datasets network errors such as timeouts can be encountered. When this occurs you will see a HTTP 500 error with the following message: "Request failed due to an internal network error. Please restart the scroll operation." If this happens, you will need to restart your scroll query: It is not possible to continue from a specific point when using scroll. {% /admonition %} responses: '200': description: Successful content: application/json: examples: Successful: value: type: list data: - type: company company_id: remote_companies_scroll_2 id: 6762f0971bb69f9f2193bb2b app_id: this_is_an_id193_that_should_be_at_least_ name: IntercomQATest1 remote_created_at: 1734537367 created_at: 1734537367 updated_at: 1734537367 monthly_spend: 0 session_count: 0 user_count: 4 tags: type: tag.list tags: [] segments: type: segment.list segments: [] plan: {} custom_attributes: {} pages: total_count: scroll_param: 69352cd2-ab5b-42ac-b004-a13d4e55e9b0 schema: "$ref": "#/components/schemas/company_scroll" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: ca269b05-8c42-4615-a28d-7df0eb1687c5 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" "/contacts/{contact_id}/companies": post: summary: Attach a Contact to a Company parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: contact_id in: path required: true description: The unique identifier for the contact which is given by Intercom schema: type: string tags: - Companies - Contacts operationId: attachContactToACompany description: You can attach a company to a single contact. responses: '200': description: Successful content: application/json: examples: Successful: value: type: company company_id: '1' id: 6762f09a1bb69f9f2193bb34 app_id: this_is_an_id197_that_should_be_at_least_ name: company6 remote_created_at: 1734537370 created_at: 1734537370 updated_at: 1734537370 monthly_spend: 0 session_count: 0 user_count: 1 tags: type: tag.list tags: [] segments: type: segment.list segments: [] plan: {} custom_attributes: {} schema: "$ref": "#/components/schemas/company" '400': description: Bad Request content: application/json: examples: Bad Request: value: type: error.list request_id: 8879ee29-ade4-4b5a-a275-ab1ac531b82a errors: - code: parameter_not_found message: company not specified Contact Company Limit Exceeded: value: type: error.list request_id: 9a3d0816-9707-4598-977e-c009ba630148 errors: - code: contact_company_limit_exceeded message: Contact has reached the maximum of 1000 company associations schema: "$ref": "#/components/schemas/error" '404': description: Company Not Found content: application/json: examples: Company Not Found: value: type: error.list request_id: 981799ea-f19b-432d-828c-491a3b29ad29 errors: - code: company_not_found message: Company Not Found schema: "$ref": "#/components/schemas/error" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: 1f187e85-cd9a-4be4-964e-cdbb8c66334a errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" requestBody: content: application/json: schema: type: object required: - id properties: id: type: string description: The unique identifier for the company which is given by Intercom example: 58a430d35458202d41b1e65b examples: successful: summary: Successful value: id: 6762f09a1bb69f9f2193bb34 bad_request: summary: Bad Request value: company_not_found: summary: Company Not Found value: id: '123' get: summary: List attached companies for contact parameters: - name: contact_id in: path description: The unique identifier for the contact which is given by Intercom example: 63a07ddf05a32042dffac965 required: true schema: type: string - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" tags: - Contacts - Companies operationId: listCompaniesForAContact description: You can fetch a list of companies that are associated to a contact. responses: '200': description: successful content: application/json: examples: successful: value: type: list data: - type: company company_id: '1' id: 6762f0a61bb69f9f2193bb55 app_id: this_is_an_id213_that_should_be_at_least_ name: company12 remote_created_at: 1734537382 created_at: 1734537382 updated_at: 1734537382 last_request_at: 1734364582 monthly_spend: 0 session_count: 0 user_count: 1 tags: type: tag.list tags: [] segments: type: segment.list segments: [] plan: {} custom_attributes: {} pages: type: pages next: page: 1 per_page: 50 total_pages: 1 total_count: 1 schema: "$ref": "#/components/schemas/contact_attached_companies" '404': description: Contact not found content: application/json: examples: Contact not found: value: type: error.list request_id: 32c856ba-901b-49c4-8e8d-d43fc3ee6ea5 errors: - code: not_found message: User Not Found schema: "$ref": "#/components/schemas/error" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: 565a4f38-5fa9-451d-bcf0-32076f79517f errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" "/contacts/{contact_id}/companies/{company_id}": delete: summary: Detach a contact from a company parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: contact_id in: path required: true description: The unique identifier for the contact which is given by Intercom example: 58a430d35458202d41b1e65b schema: type: string - name: company_id in: path required: true description: The unique identifier for the company which is given by Intercom example: 58a430d35458202d41b1e65b schema: type: string tags: - Companies - Contacts operationId: detachContactFromACompany description: You can detach a company from a single contact. responses: '200': description: Successful content: application/json: examples: Successful: value: type: company company_id: '1' id: 6762f0a01bb69f9f2193bb44 app_id: this_is_an_id205_that_should_be_at_least_ name: company8 remote_created_at: 1734537376 created_at: 1734537376 updated_at: 1734537377 monthly_spend: 0 session_count: 0 user_count: 0 tags: type: tag.list tags: [] segments: type: segment.list segments: [] plan: {} custom_attributes: {} schema: "$ref": "#/components/schemas/company" '404': description: Contact Not Found content: application/json: examples: Company Not Found: value: type: error.list request_id: dcfc3465-8a51-4d78-b24c-2f215d48f339 errors: - code: company_not_found message: Company Not Found Contact Not Found: value: type: error.list request_id: b5a1f332-1bf1-44bd-a068-2634244b6051 errors: - code: not_found message: User Not Found schema: "$ref": "#/components/schemas/error" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: 9bc1e0cc-5cc4-412d-8037-57e073375ab0 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" "/contacts/{contact_id}/notes": get: summary: List all notes parameters: - name: contact_id in: path required: true description: The unique identifier of a contact. schema: type: string - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" tags: - Notes - Contacts operationId: listNotes description: You can fetch a list of notes that are associated to a contact. responses: '200': description: Successful response content: application/json: examples: Successful response: value: type: list data: - type: note id: '26' created_at: 1733932587 contact: type: contact id: 6762f0ab1bb69f9f2193bb60 author: type: admin id: '991267581' name: Ciaran122 Lee email: admin122@email.com away_mode_enabled: false away_mode_reassign: false body: "This is a note.
" - type: note id: '25' created_at: 1733846187 contact: type: contact id: 6762f0ab1bb69f9f2193bb60 author: type: admin id: '991267581' name: Ciaran122 Lee email: admin122@email.com away_mode_enabled: false away_mode_reassign: false body: "This is a note.
" - type: note id: '24' created_at: 1733846187 contact: type: contact id: 6762f0ab1bb69f9f2193bb60 author: type: admin id: '991267581' name: Ciaran122 Lee email: admin122@email.com away_mode_enabled: false away_mode_reassign: false body: "This is a note.
" total_count: 3 pages: type: pages next: page: 1 per_page: 50 total_pages: 1 schema: "$ref": "#/components/schemas/note_list" '404': description: Contact not found content: application/json: examples: Contact not found: value: type: error.list request_id: 57055cde-3d0d-4c67-b5c9-b20b80340bf0 errors: - code: not_found message: User Not Found schema: "$ref": "#/components/schemas/error" post: summary: Create a note parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: contact_id in: path required: true description: The unique identifier of a given contact. example: '123' schema: type: integer tags: - Notes - Contacts operationId: createNote description: You can add a note to a single contact. responses: '200': description: Successful response content: application/json: examples: Successful response: value: type: note id: '31' created_at: 1734537390 contact: type: contact id: 6762f0ad1bb69f9f2193bb62 author: type: admin id: '991267583' name: Ciaran124 Lee email: admin124@email.com away_mode_enabled: false away_mode_reassign: false body: "Hello
" schema: "$ref": "#/components/schemas/note" '404': description: Contact not found content: application/json: examples: Admin not found: value: type: error.list request_id: 168f1bc3-d198-4797-8422-9f93fe8af5ad errors: - code: not_found message: Resource Not Found Contact not found: value: type: error.list request_id: 6f372239-0259-428f-9943-91b8f7a92162 errors: - code: not_found message: User Not Found schema: "$ref": "#/components/schemas/error" requestBody: content: application/json: schema: type: object required: - body properties: body: type: string description: The text of the note. example: New note admin_id: type: string description: The unique identifier of a given admin. example: '123' examples: successful_response: summary: Successful response value: contact_id: 6762f0ad1bb69f9f2193bb62 admin_id: 991267583 body: Hello admin_not_found: summary: Admin not found value: contact_id: 6762f0af1bb69f9f2193bb63 admin_id: 123 body: Hello contact_not_found: summary: Contact not found value: contact_id: 123 admin_id: 991267585 body: Hello "/contacts/{contact_id}/segments": get: summary: List attached segments for contact parameters: - name: contact_id in: path description: The unique identifier for the contact which is given by Intercom example: 63a07ddf05a32042dffac965 required: true schema: type: string - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" tags: - Contacts - Segments operationId: listSegmentsForAContact description: You can fetch a list of segments that are associated to a contact. responses: '200': description: successful content: application/json: examples: successful: value: type: list data: - type: segment id: 6762f0b21bb69f9f2193bb65 name: segment created_at: 1734537394 updated_at: 1734537394 person_type: user schema: "$ref": "#/components/schemas/contact_segments" '404': description: Contact not found content: application/json: examples: Contact not found: value: type: error.list request_id: 61c119c7-b2f0-4158-8457-fd53e83f936a errors: - code: not_found message: User Not Found schema: "$ref": "#/components/schemas/error" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: 0273c219-51b7-4938-95d2-19996b2e2734 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" "/contacts/{contact_id}/subscriptions": get: summary: List subscriptions for a contact parameters: - name: contact_id in: path description: The unique identifier for the contact which is given by Intercom example: 63a07ddf05a32042dffac965 required: true schema: type: string - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" tags: - Contacts - Subscription Types operationId: listSubscriptionsForAContact description: | You can fetch a list of subscription types that are attached to a contact. These can be subscriptions that a user has 'opted-in' to or has 'opted-out' from, depending on the subscription type. This will return a list of Subscription Type objects that the contact is associated with. The data property will show a combined list of: 1.Opt-out subscription types that the user has opted-out from. 2.Opt-in subscription types that the user has opted-in to receiving. responses: '200': description: Successful content: application/json: examples: Successful: value: type: list data: - type: subscription id: '91' state: live consent_type: opt_out default_translation: name: Newsletters description: Lorem ipsum dolor sit amet locale: en translations: - name: Newsletters description: Lorem ipsum dolor sit amet locale: en content_types: - email - type: subscription id: '93' state: live consent_type: opt_in default_translation: name: Newsletters description: Lorem ipsum dolor sit amet locale: en translations: - name: Newsletters description: Lorem ipsum dolor sit amet locale: en content_types: - sms_message schema: "$ref": "#/components/schemas/subscription_type_list" '404': description: Contact not found content: application/json: examples: Contact not found: value: type: error.list request_id: c9b793ad-ff39-436c-80c9-db6f24d0d444 errors: - code: not_found message: User Not Found schema: "$ref": "#/components/schemas/error" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: 7323b97b-9ba4-4c54-946c-38cecea65b3c errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" post: summary: Add subscription to a contact tags: - Subscription Types - Contacts parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: contact_id in: path description: The unique identifier for the contact which is given by Intercom example: 63a07ddf05a32042dffac965 required: true schema: type: string operationId: attachSubscriptionTypeToContact description: | You can add a specific subscription to a contact. In Intercom, we have two different subscription types based on user consent - opt-out and opt-in: 1.Attaching a contact to an opt-out subscription type will opt that user out from receiving messages related to that subscription type. 2.Attaching a contact to an opt-in subscription type will opt that user in to receiving messages related to that subscription type. This will return a subscription type model for the subscription type that was added to the contact. responses: '200': description: Successful content: application/json: examples: Successful: value: type: subscription id: '106' state: live consent_type: opt_in default_translation: name: Newsletters description: Lorem ipsum dolor sit amet locale: en translations: - name: Newsletters description: Lorem ipsum dolor sit amet locale: en content_types: - sms_message schema: "$ref": "#/components/schemas/subscription_type" '404': description: Resource not found content: application/json: examples: Contact not found: value: type: error.list request_id: 0c2871af-abed-4bce-a5c5-77efbe721711 errors: - code: not_found message: User Not Found Resource not found: value: type: error.list request_id: 2774db46-34d9-4925-a24d-8203d4a39f65 errors: - code: not_found message: Resource Not Found schema: "$ref": "#/components/schemas/error" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: f615465d-fd5f-4d68-8498-389130b897e4 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" requestBody: content: application/json: schema: type: object required: - id - consent_type properties: id: type: string description: The unique identifier for the subscription which is given by Intercom example: '37846' consent_type: type: string description: The consent_type of a subscription, opt_out or opt_in. example: opt_in examples: successful: summary: Successful value: id: 106 consent_type: opt_in contact_not_found: summary: Contact not found value: id: 110 consent_type: opt_in resource_not_found: summary: Resource not found value: id: invalid_id consent_type: opt_in "/contacts/{contact_id}/subscriptions/{subscription_id}": delete: summary: Remove subscription from a contact tags: - Subscription Types - Contacts parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: contact_id in: path description: The unique identifier for the contact which is given by Intercom example: 63a07ddf05a32042dffac965 required: true schema: type: string - name: subscription_id in: path description: The unique identifier for the subscription type which is given by Intercom example: '37846' required: true schema: type: string operationId: detachSubscriptionTypeToContact description: You can remove a specific subscription from a contact. This will return a subscription type model for the subscription type that was removed from the contact. responses: '200': description: Successful content: application/json: examples: Successful: value: type: subscription id: '122' state: live consent_type: opt_in default_translation: name: Newsletters description: Lorem ipsum dolor sit amet locale: en translations: - name: Newsletters description: Lorem ipsum dolor sit amet locale: en content_types: - sms_message schema: "$ref": "#/components/schemas/subscription_type" '404': description: Resource not found content: application/json: examples: Contact not found: value: type: error.list request_id: 82b37940-b43f-46ee-a492-11543a317c97 errors: - code: not_found message: User Not Found Resource not found: value: type: error.list request_id: c18422ca-5454-42af-9e1d-dd92066e6e9d errors: - code: not_found message: Resource Not Found schema: "$ref": "#/components/schemas/error" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: c7de741d-dc8f-49b1-8cbe-791668ade76c errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" "/contacts/{contact_id}/tags": get: summary: List tags attached to a contact tags: - Contacts - Tags parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: contact_id in: path description: The unique identifier for the contact which is given by Intercom example: 63a07ddf05a32042dffac965 required: true schema: type: string operationId: listTagsForAContact description: You can fetch a list of all tags that are attached to a specific contact. responses: '200': description: successful content: application/json: examples: successful: value: type: list data: - type: tag id: '80' name: Manual tag applied_at: 1663597223 applied_by: type: admin id: '456' schema: "$ref": "#/components/schemas/tag_list" '404': description: Contact not found content: application/json: examples: Contact not found: value: type: error.list request_id: 302049fb-b8c1-4dc8-a327-a8f6e1923484 errors: - code: not_found message: User Not Found schema: "$ref": "#/components/schemas/error" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: ca3c5e6e-c743-428b-aa8a-ac371a50cc39 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" post: summary: Add tag to a contact tags: - Tags - Contacts parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: contact_id in: path description: The unique identifier for the contact which is given by Intercom example: 63a07ddf05a32042dffac965 required: true schema: type: string operationId: attachTagToContact description: You can tag a specific contact. This will return a tag object for the tag that was added to the contact. responses: '200': description: successful content: application/json: examples: successful: value: type: tag id: '81' name: Manual tag applied_at: 1663597223 applied_by: type: admin id: '456' schema: "$ref": "#/components/schemas/tag" '404': description: Tag not found content: application/json: examples: Contact not found: value: type: error.list request_id: f22a7847-ee33-449f-80c0-707efd295a53 errors: - code: not_found message: User Not Found Tag not found: value: type: error.list request_id: 8a3e4f88-ae65-433a-b4eb-46780ffc5402 errors: - code: not_found message: Resource Not Found schema: "$ref": "#/components/schemas/error" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: 9b1c9966-caeb-485a-8419-d707fd472c63 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" requestBody: content: application/json: schema: type: object required: - id properties: id: type: string description: The unique identifier for the tag which is given by Intercom example: '7522907' examples: successful: summary: successful value: id: 81 contact_not_found: summary: Contact not found value: id: 82 tag_not_found: summary: Tag not found value: id: '123' "/contacts/{contact_id}/tags/{tag_id}": delete: summary: Remove tag from a contact tags: - Tags - Contacts parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: contact_id in: path description: The unique identifier for the contact which is given by Intercom example: 63a07ddf05a32042dffac965 required: true schema: type: string - name: tag_id in: path description: The unique identifier for the tag which is given by Intercom example: '7522907' required: true schema: type: string operationId: detachTagFromContact description: You can remove tag from a specific contact. This will return a tag object for the tag that was removed from the contact. responses: '200': description: successful content: application/json: examples: successful: value: type: tag id: '84' name: Manual tag applied_at: 1663597223 applied_by: type: admin id: '456' schema: "$ref": "#/components/schemas/tag" '404': description: Tag not found content: application/json: examples: Contact not found: value: type: error.list request_id: b3d41080-5b35-42b8-8584-31e4660d355f errors: - code: not_found message: User Not Found Tag not found: value: type: error.list request_id: '02871f7a-860e-433a-8545-6a73fbbe5e22' errors: - code: not_found message: Resource Not Found schema: "$ref": "#/components/schemas/error" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: 491beaa4-a452-4940-85e0-498c0ca5528d errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" "/contacts/{contact_id}": put: summary: Update a contact parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: contact_id in: path description: id example: 63a07ddf05a32042dffac965 required: true schema: type: string tags: - Contacts - Custom Object Instances operationId: UpdateContact description: | You can update an existing contact (ie. user or lead). {% admonition type="info" %} This endpoint handles both **contact updates** and **custom object associations**. See _`update a contact with an association to a custom object instance`_ in the request/response examples to see the custom object association format. {% /admonition %} responses: '200': description: successful content: application/json: examples: successful: value: type: contact id: 6762f0cd1bb69f9f2193bb7c workspace_id: this_is_an_id279_that_should_be_at_least_ external_id: '70' role: user email: joebloggs@intercom.io phone: name: joe bloggs avatar: owner_id: social_profiles: type: list data: [] has_hard_bounced: false marked_email_as_spam: false unsubscribed_from_emails: false created_at: 1734537421 updated_at: 1734537422 signed_up_at: 1734537421 last_seen_at: last_replied_at: last_contacted_at: last_email_opened_at: last_email_clicked_at: language_override: browser: browser_version: browser_language: os: location: type: location country: region: city: country_code: continent_code: android_app_name: android_app_version: android_device: android_os_version: android_sdk_version: android_last_seen_at: ios_app_name: ios_app_version: ios_device: ios_os_version: ios_sdk_version: ios_last_seen_at: custom_attributes: {} tags: type: list data: [] url: "/contacts/6762f0cd1bb69f9f2193bb7c/tags" total_count: 0 has_more: false notes: type: list data: [] url: "/contacts/6762f0cd1bb69f9f2193bb7c/notes" total_count: 0 has_more: false companies: type: list data: [] url: "/contacts/6762f0cd1bb69f9f2193bb7c/companies" total_count: 0 has_more: false opted_out_subscription_types: type: list data: [] url: "/contacts/6762f0cd1bb69f9f2193bb7c/subscriptions" total_count: 0 has_more: false opted_in_subscription_types: type: list data: [] url: "/contacts/6762f0cd1bb69f9f2193bb7c/subscriptions" total_count: 0 has_more: false utm_campaign: utm_content: utm_medium: utm_source: utm_term: referrer: enabled_push_messaging: update a contact with an association to a custom object instance: value: type: contact id: 6762f0cd1bb69f9f2193bb7c workspace_id: this_is_an_id279_that_should_be_at_least_ external_id: '70' role: user email: joebloggs@intercom.io phone: name: joe bloggs avatar: owner_id: social_profiles: type: list data: [] has_hard_bounced: false marked_email_as_spam: false unsubscribed_from_emails: false created_at: 1734537421 updated_at: 1734537422 signed_up_at: 1734537421 last_seen_at: last_replied_at: last_contacted_at: last_email_opened_at: last_email_clicked_at: language_override: browser: browser_version: browser_language: os: location: type: location country: region: city: country_code: continent_code: android_app_name: android_app_version: android_device: android_os_version: android_sdk_version: android_last_seen_at: ios_app_name: ios_app_version: ios_device: ios_os_version: ios_sdk_version: ios_last_seen_at: custom_attributes: order: type: Order.list instances: - id: '21' external_id: '123' external_created_at: 1392036272 external_updated_at: 1392036272 custom_attributes: order_number: ORDER-12345 total_amount: 99.99 type: Order tags: type: list data: [] url: "/contacts/6762f0cd1bb69f9f2193bb7c/tags" total_count: 0 has_more: false notes: type: list data: [] url: "/contacts/6762f0cd1bb69f9f2193bb7c/notes" total_count: 0 has_more: false companies: type: list data: [] url: "/contacts/6762f0cd1bb69f9f2193bb7c/companies" total_count: 0 has_more: false opted_out_subscription_types: type: list data: [] url: "/contacts/6762f0cd1bb69f9f2193bb7c/subscriptions" total_count: 0 has_more: false opted_in_subscription_types: type: list data: [] url: "/contacts/6762f0cd1bb69f9f2193bb7c/subscriptions" total_count: 0 has_more: false utm_campaign: utm_content: utm_medium: utm_source: utm_term: referrer: enabled_push_messaging: schema: allOf: - "$ref": "#/components/schemas/contact" properties: enabled_push_messaging: type: boolean nullable: true description: If the user has enabled push messaging. example: true '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: 89ce96d9-aae9-4eec-ace2-d68cc4f74879 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" requestBody: content: application/json: schema: oneOf: - "$ref": "#/components/schemas/update_contact_request" examples: successful: summary: successful value: email: joebloggs@intercom.io name: joe bloggs update_a_contact_with_an_association_to_a_custom_object_instance: summary: update a contact with an association to a custom object instance value: custom_attributes: order: - '21' get: summary: Get a contact parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: contact_id in: path description: contact_id example: 63a07ddf05a32042dffac965 required: true schema: type: string tags: - Contacts operationId: ShowContact description: You can fetch the details of a single contact. responses: '200': description: successful content: application/json: examples: successful: value: type: contact id: 6762f0d01bb69f9f2193bb7d workspace_id: this_is_an_id283_that_should_be_at_least_ external_id: '70' role: user email: joe@bloggs.com phone: name: Joe Bloggs avatar: owner_id: social_profiles: type: list data: [] has_hard_bounced: false marked_email_as_spam: false unsubscribed_from_emails: false created_at: 1734537424 updated_at: 1734537424 signed_up_at: 1734537424 last_seen_at: last_replied_at: last_contacted_at: last_email_opened_at: last_email_clicked_at: language_override: browser: browser_version: browser_language: os: location: type: location country: region: city: country_code: continent_code: android_app_name: android_app_version: android_device: android_os_version: android_sdk_version: android_last_seen_at: ios_app_name: ios_app_version: ios_device: ios_os_version: ios_sdk_version: ios_last_seen_at: custom_attributes: {} tags: type: list data: [] url: "/contacts/6762f0d01bb69f9f2193bb7d/tags" total_count: 0 has_more: false notes: type: list data: [] url: "/contacts/6762f0d01bb69f9f2193bb7d/notes" total_count: 0 has_more: false companies: type: list data: [] url: "/contacts/6762f0d01bb69f9f2193bb7d/companies" total_count: 0 has_more: false opted_out_subscription_types: type: list data: [] url: "/contacts/6762f0d01bb69f9f2193bb7d/subscriptions" total_count: 0 has_more: false opted_in_subscription_types: type: list data: [] url: "/contacts/6762f0d01bb69f9f2193bb7d/subscriptions" total_count: 0 has_more: false utm_campaign: utm_content: utm_medium: utm_source: utm_term: referrer: enabled_push_messaging: schema: allOf: - "$ref": "#/components/schemas/contact" properties: enabled_push_messaging: type: boolean nullable: true description: If the user has enabled push messaging. example: true '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: 45b30bd1-75d2-40cc-bb39-74ac133a2836 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" delete: summary: Delete a contact parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: contact_id in: path description: contact_id required: true schema: type: string tags: - Contacts operationId: DeleteContact description: You can delete a single contact. responses: '200': description: successful content: application/json: schema: "$ref": "#/components/schemas/contact_deleted" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: a947b2f0-23d3-419d-9ec4-cdd191cea676 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" "/contacts/merge": post: summary: Merge a lead and a user parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" tags: - Contacts operationId: MergeContact description: You can merge a contact with a `role` of `lead` into a contact with a `role` of `user`. responses: '200': description: successful content: application/json: examples: successful: value: type: contact id: 6762f0d51bb69f9f2193bb80 workspace_id: this_is_an_id291_that_should_be_at_least_ external_id: '70' role: user email: joe@bloggs.com phone: name: Joe Bloggs avatar: owner_id: social_profiles: type: list data: [] has_hard_bounced: false marked_email_as_spam: false unsubscribed_from_emails: false created_at: 1734537429 updated_at: 1734537430 signed_up_at: 1734537429 last_seen_at: last_replied_at: last_contacted_at: last_email_opened_at: last_email_clicked_at: language_override: browser: browser_version: browser_language: os: location: type: location country: region: city: country_code: continent_code: android_app_name: android_app_version: android_device: android_os_version: android_sdk_version: android_last_seen_at: ios_app_name: ios_app_version: ios_device: ios_os_version: ios_sdk_version: ios_last_seen_at: custom_attributes: {} tags: type: list data: [] url: "/contacts/6762f0d51bb69f9f2193bb80/tags" total_count: 0 has_more: false notes: type: list data: [] url: "/contacts/6762f0d51bb69f9f2193bb80/notes" total_count: 0 has_more: false companies: type: list data: [] url: "/contacts/6762f0d51bb69f9f2193bb80/companies" total_count: 0 has_more: false opted_out_subscription_types: type: list data: [] url: "/contacts/6762f0d51bb69f9f2193bb80/subscriptions" total_count: 0 has_more: false opted_in_subscription_types: type: list data: [] url: "/contacts/6762f0d51bb69f9f2193bb80/subscriptions" total_count: 0 has_more: false utm_campaign: utm_content: utm_medium: utm_source: utm_term: referrer: enabled_push_messaging: schema: allOf: - "$ref": "#/components/schemas/contact" properties: enabled_push_messaging: type: boolean nullable: true description: If the user has enabled push messaging. example: true '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: ff328c7c-6140-48eb-84dd-bb8960b66cd0 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" requestBody: content: application/json: schema: "$ref": "#/components/schemas/merge_contacts_request" examples: successful: summary: successful value: from: 6762f0d51bb69f9f2193bb7f into: 6762f0d51bb69f9f2193bb80 "/contacts/search": post: summary: Search contacts parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" tags: - Contacts operationId: SearchContacts description: | You can search for multiple contacts by the value of their attributes in order to fetch exactly who you want. To search for contacts, you need to send a `POST` request to `https://api.intercom.io/contacts/search`. This will accept a query object in the body which will define your filters in order to search for contacts. {% admonition type="warning" name="Optimizing search queries" %} Search queries can be complex, so optimizing them can help the performance of your search. Use the `AND` and `OR` operators to combine multiple filters to get the exact results you need and utilize pagination to limit the number of results returned. The default is `50` results per page. See the [pagination section](https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis/pagination/#example-search-conversations-request) for more details on how to use the `starting_after` param. {% /admonition %} ### Contact Creation Delay If a contact has recently been created, there is a possibility that it will not yet be available when searching. This means that it may not appear in the response. This delay can take a few minutes. If you need to be instantly notified it is recommended to use webhooks and iterate to see if they match your search filters. ### Nesting & Limitations You can nest these filters in order to get even more granular insights that pinpoint exactly what you need. Example: (1 OR 2) AND (3 OR 4). There are some limitations to the amount of multiple's there can be: * There's a limit of max 2 nested filters * There's a limit of max 15 filters for each AND or OR group ### Searching for Timestamp Fields All timestamp fields (created_at, updated_at etc.) are indexed as Dates for Contact Search queries; Datetime queries are not currently supported. This means you can only query for timestamp fields by day - not hour, minute or second. For example, if you search for all Contacts with a created_at value greater (>) than 1577869200 (the UNIX timestamp for January 1st, 2020 9:00 AM), that will be interpreted as 1577836800 (January 1st, 2020 12:00 AM). The search results will then include Contacts created from January 2nd, 2020 12:00 AM onwards. If you'd like to get contacts created on January 1st, 2020 you should search with a created_at value equal (=) to 1577836800 (January 1st, 2020 12:00 AM). This behaviour applies only to timestamps used in search queries. The search results will still contain the full UNIX timestamp and be sorted accordingly. ### Accepted Fields Most key listed as part of the Contacts Model are searchable, whether writeable or not. The value you search for has to match the accepted type, otherwise the query will fail (ie. as `created_at` accepts a date, the `value` cannot be a string such as `"foorbar"`). | Field | Type | | ---------------------------------- | ------------------------------ | | id | String | | role | Stringthis is the message body
" author: type: admin id: '991267628' name: Ciaran166 Lee email: admin166@email.com attachments: [] url: redacted: false contacts: type: contact.list contacts: - type: contact id: 6762f0f31bb69f9f2193bb8b external_id: '70' first_contact_reply: admin_assignee_id: team_assignee_id: open: false state: closed read: false tags: type: tag.list tags: [] priority: not_priority sla_applied: statistics: conversation_rating: teammates: title: custom_attributes: {} topics: {} ticket: linked_objects: type: list data: [] total_count: 0 has_more: false ai_agent: ai_agent_participated: false schema: "$ref": "#/components/schemas/conversation_list" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: b14d75ab-7d26-4191-b33f-77ca0a4d4ede errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" '403': description: API plan restricted content: application/json: examples: API plan restricted: value: type: error.list request_id: 591a0c2f-78b3-41bb-bfa7-f1fae15107b9 errors: - code: api_plan_restricted message: Active subscription needed. schema: "$ref": "#/components/schemas/error" post: summary: Creates a conversation parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" tags: - Conversations operationId: createConversation description: |+ You can create a conversation that has been initiated by a contact (ie. user or lead). The conversation can be an in-app message only. {% admonition type="info" name="Sending for visitors" %} You can also send a message from a visitor by specifying their `user_id` or `id` value in the `from` field, along with a `type` field value of `contact`. This visitor will be automatically converted to a contact with a lead role once the conversation is created. {% /admonition %} This will return the Message model that has been created. responses: '200': description: conversation created content: application/json: examples: conversation created: value: type: user_message id: '403918330' created_at: 1734537501 body: Hello there message_type: inapp conversation_id: '499' schema: "$ref": "#/components/schemas/message" '404': description: Contact Not Found content: application/json: examples: Contact Not Found: value: type: error.list request_id: d7eb553e-74ae-4341-820b-5d38a94d4a99 errors: - code: not_found message: User Not Found schema: "$ref": "#/components/schemas/error" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: 68e42c33-8220-48ea-906f-75584c3ec440 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" '403': description: API plan restricted content: application/json: examples: API plan restricted: value: type: error.list request_id: dcf1b373-3e66-4026-a987-98c16f00a908 errors: - code: api_plan_restricted message: Active subscription needed. schema: "$ref": "#/components/schemas/error" requestBody: content: application/json: schema: "$ref": "#/components/schemas/create_conversation_request" examples: conversation_created: summary: conversation created value: from: type: user id: 6762f11b1bb69f9f2193bba3 body: Hello there contact_not_found: summary: Contact Not Found value: from: type: user id: 123_doesnt_exist body: Hello there "/conversations/{conversation_id}": get: summary: Retrieve a conversation parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: conversation_id in: path required: true description: The id of the conversation to target example: 123 schema: type: integer - name: display_as in: query required: false description: Set to plaintext to retrieve conversation messages in plain text. example: plaintext schema: type: string - name: include_translations in: query required: false description: If set to true, conversation parts will be translated to the detected language of the conversation. example: true schema: type: boolean tags: - Conversations operationId: retrieveConversation description: |2 You can fetch the details of a single conversation. This will return a single Conversation model with all its conversation parts. {% admonition type="warning" name="Hard limit of 500 parts" %} The maximum number of conversation parts that can be returned via the API is 500. If you have more than that we will return the 500 most recent conversation parts. {% /admonition %} For AI agent conversation metadata, please note that you need to have the agent enabled in your workspace, which is a [paid feature](https://www.intercom.com/help/en/articles/8205718-fin-resolutions#h_97f8c2e671). responses: '200': description: conversation found content: application/json: examples: conversation found: value: type: conversation id: '503' created_at: 1734537511 updated_at: 1734537511 waiting_since: snoozed_until: source: type: conversation id: '403918334' delivered_as: admin_initiated subject: '' body: "this is the message body
" author: type: admin id: '991267645' name: Ciaran176 Lee email: admin176@email.com attachments: [] url: redacted: false contacts: type: contact.list contacts: - type: contact id: 6762f1261bb69f9f2193bba7 external_id: '70' first_contact_reply: admin_assignee_id: team_assignee_id: open: false state: closed read: false tags: type: tag.list tags: - type: tag id: '123456' name: Test tag applied_at: 1663597223 applied_by: type: contact id: '1a2b3c' priority: not_priority sla_applied: statistics: conversation_rating: teammates: title: custom_attributes: {} topics: {} ticket: linked_objects: type: list data: [] total_count: 0 has_more: false ai_agent: ai_agent_participated: false conversation_parts: type: conversation_part.list conversation_parts: - type: conversation_part id: 1 part_type: comment body:Okay!
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: null state: open tags: - type: tag id: '123456' name: Test tag event_details: app_package_code: null - type: conversation_part id: 2 part_type: custom_action_started body: created_at: 1740141842 updated_at: 1740141842 notified_at: 1740141842 assigned_to: author: type: admin id: '274' name: Jamie Oliver email: jamie+abcd1234@intercom.io attachments: [] external_id: redacted: false email_message_metadata: null state: open tags: [] event_details: action: name: Jira Create Issue app_package_code: test-integration - type: conversation_part id: 3 part_type: conversation_attribute_updated_by_admin body: created_at: 1740141851 updated_at: 1740141851 notified_at: 1740141851 assigned_to: author: type: bot id: '278' name: Fin email: operator+abcd1234@intercom.io attachments: [] external_id: redacted: false email_message_metadata: null state: open tags: [] event_details: attribute: name: jira_issue_key value: name: PROJ-007 app_package_code: null - type: conversation_part id: 4 part_type: custom_action_finished body: created_at: 1740141857 updated_at: 1740141857 notified_at: 1740141857 assigned_to: author: type: admin id: '274' name: Jamie Oliver email: jamie+abcd1234@intercom.io attachments: [] external_id: redacted: false email_message_metadata: null state: closed tags: [] event_details: action: name: Jira Create Issue result: success app_package_code: null total_count: 4 schema: "$ref": "#/components/schemas/conversation" '404': description: Not found content: application/json: examples: Not found: value: type: error.list request_id: 8c288c4f-b699-4209-9de4-064398f02785 errors: - code: not_found message: Resource Not Found schema: "$ref": "#/components/schemas/error" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: 1350c241-0f22-48ca-bab9-169080340870 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" '403': description: API plan restricted content: application/json: examples: API plan restricted: value: type: error.list request_id: 8b3deed3-fd8b-43d6-b6a8-428c9e17aabb errors: - code: api_plan_restricted message: Active subscription needed. schema: "$ref": "#/components/schemas/error" put: summary: Update a conversation parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: conversation_id in: path required: true description: The id of the conversation to target example: 123 schema: type: integer - name: display_as in: query required: false description: Set to plaintext to retrieve conversation messages in plain text. example: plaintext schema: type: string tags: - Conversations - Custom Object Instances operationId: updateConversation description: |2+ You can update an existing conversation. {% admonition type="info" name="Replying and other actions" %} If you want to reply to a coveration or take an action such as assign, unassign, open, close or snooze, take a look at the reply and manage endpoints. {% /admonition %} {% admonition type="info" %} This endpoint handles both **conversation updates** and **custom object associations**. See _`update a conversation with an association to a custom object instance`_ in the request/response examples to see the custom object association format. {% /admonition %} responses: '200': description: update a conversation with an association to a custom object instance content: application/json: examples: conversation found: value: type: conversation id: '507' created_at: 1734537521 updated_at: 1734537523 waiting_since: snoozed_until: source: type: conversation id: '403918338' delivered_as: admin_initiated subject: '' body: "this is the message body
" author: type: admin id: '991267653' name: Ciaran180 Lee email: admin180@email.com attachments: [] url: redacted: false contacts: type: contact.list contacts: - type: contact id: 6762f1301bb69f9f2193bbab external_id: '70' first_contact_reply: admin_assignee_id: team_assignee_id: open: false state: closed read: true tags: type: tag.list tags: [] priority: not_priority sla_applied: statistics: conversation_rating: teammates: title: custom_attributes: issue_type: Billing priority: High topics: {} ticket: linked_objects: type: list data: [] total_count: 0 has_more: false ai_agent: ai_agent_participated: false conversation_parts: type: conversation_part.list conversation_parts: - type: conversation_part id: '129' part_type: conversation_attribute_updated_by_admin body: created_at: 1734537523 updated_at: 1734537523 notified_at: 1734537523 assigned_to: author: id: '991267654' type: bot name: Fin email: operator+this_is_an_id354_that_should_be_at_least_@intercom.io attachments: [] external_id: redacted: false metadata: {} email_message_metadata: app_package_code: null - type: conversation_part id: '130' part_type: conversation_attribute_updated_by_admin body: created_at: 1734537523 updated_at: 1734537523 notified_at: 1734537523 assigned_to: author: id: '991267654' type: bot name: Fin email: operator+this_is_an_id354_that_should_be_at_least_@intercom.io attachments: [] external_id: redacted: false metadata: {} email_message_metadata: app_package_code: null total_count: 2 update a conversation with an association to a custom object instance: value: type: conversation id: '508' created_at: 1734537525 updated_at: 1734537525 waiting_since: snoozed_until: source: type: conversation id: '403918339' delivered_as: admin_initiated subject: '' body: "this is the message body
" author: type: admin id: '991267659' name: Ciaran185 Lee email: admin185@email.com attachments: [] url: redacted: false contacts: type: contact.list contacts: - type: contact id: 6762f1341bb69f9f2193bbac external_id: '70' first_contact_reply: admin_assignee_id: team_assignee_id: open: false state: closed read: false tags: type: tag.list tags: [] priority: not_priority sla_applied: statistics: conversation_rating: teammates: title: custom_attributes: order: type: Order.list instances: - id: '21' external_id: '123' external_created_at: 1392036272 external_updated_at: 1392036272 custom_attributes: order_number: ORDER-12345 total_amount: 99.99 type: Order topics: {} ticket: linked_objects: type: list data: [] total_count: 0 has_more: false ai_agent: ai_agent_participated: false conversation_parts: type: conversation_part.list conversation_parts: [] total_count: 0 schema: "$ref": "#/components/schemas/conversation" '404': description: Not found content: application/json: examples: Not found: value: type: error.list request_id: de1be01d-a0d3-48a6-9ea6-9789931a6887 errors: - code: not_found message: Resource Not Found schema: "$ref": "#/components/schemas/error" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: de63ddb2-c525-4ebf-ad38-82ed8b44c896 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" '403': description: API plan restricted content: application/json: examples: API plan restricted: value: type: error.list request_id: 34072e07-6b70-4f59-96bf-3106a3563a24 errors: - code: api_plan_restricted message: Active subscription needed. schema: "$ref": "#/components/schemas/error" requestBody: content: application/json: schema: "$ref": "#/components/schemas/update_conversation_request" examples: conversation_found: summary: conversation found value: read: true title: new conversation title custom_attributes: issue_type: Billing priority: High update_a_conversation_with_an_association_to_a_custom_object_instance: summary: update a conversation with an association to a custom object instance value: custom_attributes: order: - '21' not_found: summary: Not found value: read: true title: new conversation title custom_attributes: issue_type: Billing priority: High delete: summary: Delete a conversation parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: conversation_id in: path description: id required: true schema: type: integer tags: - Conversations operationId: deleteConversation description: | {% admonition type="warning" name="Irreversible operation" %} Deleting a conversation is permanent and cannot be reversed. {% /admonition %} Deleting a conversation permanently removes it from the inbox. All sensitive data is deleted, including admin and user replies, conversation attributes, uploads, and related content. The conversation will still appear in reporting, though some data may be incomplete due to the deletion. responses: '200': description: successful content: application/json: examples: successful: value: id: '512' object: conversation deleted: true schema: "$ref": "#/components/schemas/conversation_deleted" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: 310f55b0-2660-43e8-bed4-7e82b2f40920 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" '403': description: API plan restricted content: application/json: examples: API plan restricted: value: type: error.list request_id: 7a80b950-b392-499f-85db-ea7c6c424d37 errors: - code: api_plan_restricted message: Active subscription needed. schema: "$ref": "#/components/schemas/error" "/conversations/search": post: summary: Search conversations parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" tags: - Conversations operationId: searchConversations description: | You can search for multiple conversations by the value of their attributes in order to fetch exactly which ones you want. To search for conversations, you need to send a `POST` request to `https://api.intercom.io/conversations/search`. This will accept a query object in the body which will define your filters in order to search for conversations. {% admonition type="warning" name="Optimizing search queries" %} Search queries can be complex, so optimizing them can help the performance of your search. Use the `AND` and `OR` operators to combine multiple filters to get the exact results you need and utilize pagination to limit the number of results returned. The default is `20` results per page and maximum is `150`. See the [pagination section](https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis/pagination/#example-search-conversations-request) for more details on how to use the `starting_after` param. {% /admonition %} ### Nesting & Limitations You can nest these filters in order to get even more granular insights that pinpoint exactly what you need. Example: (1 OR 2) AND (3 OR 4). There are some limitations to the amount of multiple's there can be: - There's a limit of max 2 nested filters - There's a limit of max 15 filters for each AND or OR group ### Accepted Fields Most keys listed in the conversation model are searchable, whether writeable or not. The value you search for has to match the accepted type, otherwise the query will fail (ie. as `created_at` accepts a date, the `value` cannot be a string such as `"foorbar"`). The `source.body` field is unique as the search will not be performed against the entire value, but instead against every element of the value separately. For example, when searching for a conversation with a `"I need support"` body - the query should contain a `=` operator with the value `"support"` for such conversation to be returned. A query with a `=` operator and a `"need support"` value will not yield a result. | Field | Type | | :---------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- | | id | String | | created_at | Date (UNIX timestamp) | | updated_at | Date (UNIX timestamp) | | source.type | Stringthis is the message body
" author: type: admin id: '991267691' name: Ciaran210 Lee email: admin210@email.com attachments: [] url: redacted: false contacts: type: contact.list contacts: - type: contact id: 6762f14a1bb69f9f2193bbb3 external_id: '70' first_contact_reply: admin_assignee_id: team_assignee_id: open: false state: closed read: false tags: type: tag.list tags: [] priority: not_priority sla_applied: statistics: conversation_rating: teammates: title: custom_attributes: {} topics: {} ticket: linked_objects: type: list data: [] total_count: 0 has_more: false ai_agent: ai_agent_participated: false schema: "$ref": "#/components/schemas/conversation_list" requestBody: content: application/json: schema: "$ref": "#/components/schemas/search_request" examples: successful: summary: successful value: query: operator: AND value: - field: created_at operator: ">" value: '1306054154' pagination: per_page: 5 "/conversations/{conversation_id}/reply": post: summary: Reply to a conversation parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: conversation_id in: path required: true description: The Intercom provisioned identifier for the conversation or the string "last" to reply to the last part of the conversation example: 123 or "last" schema: type: string tags: - Conversations operationId: replyConversation description: You can reply to a conversation with a message from an admin or on behalf of a contact, or with a note for admins. responses: '200': description: User last conversation reply content: application/json: examples: User reply: value: type: conversation id: '524' created_at: 1734537559 updated_at: 1734537561 waiting_since: 1734537561 snoozed_until: source: type: conversation id: '403918349' delivered_as: admin_initiated subject: '' body: "this is the message body
" author: type: admin id: '991267694' name: Ciaran212 Lee email: admin212@email.com attachments: [] url: redacted: false contacts: type: contact.list contacts: - type: contact id: 6762f1571bb69f9f2193bbbb external_id: '70' first_contact_reply: created_at: 1734537561 type: conversation url: admin_assignee_id: team_assignee_id: open: true state: open read: false tags: type: tag.list tags: [] priority: not_priority sla_applied: statistics: conversation_rating: teammates: title: custom_attributes: {} topics: {} ticket: linked_objects: type: list data: [] total_count: 0 has_more: false ai_agent: ai_agent_participated: false conversation_parts: type: conversation_part.list conversation_parts: - type: conversation_part id: '132' part_type: open body: "Thanks again :)
" created_at: 1734537561 updated_at: 1734537561 notified_at: 1734537561 assigned_to: author: id: 6762f1571bb69f9f2193bbbb type: user name: Joe Bloggs email: joe@bloggs.com attachments: [] external_id: redacted: false metadata: {} email_message_metadata: app_package_code: null total_count: 1 Admin Reply with a Note: value: type: conversation id: '525' created_at: 1734537563 updated_at: 1734537565 waiting_since: snoozed_until: source: type: conversation id: '403918350' delivered_as: admin_initiated subject: '' body: "this is the message body
" author: type: admin id: '991267696' name: Ciaran213 Lee email: admin213@email.com attachments: [] url: redacted: false contacts: type: contact.list contacts: - type: contact id: 6762f15b1bb69f9f2193bbbc external_id: '70' first_contact_reply: admin_assignee_id: team_assignee_id: open: false state: closed read: false tags: type: tag.list tags: [] priority: not_priority sla_applied: statistics: conversation_rating: teammates: title: custom_attributes: {} topics: {} ticket: linked_objects: type: list data: [] total_count: 0 has_more: false ai_agent: ai_agent_participated: false conversation_parts: type: conversation_part.list conversation_parts: - type: conversation_part id: '133' part_type: note body: |-this is the message body
" author: type: admin id: '991267698' name: Ciaran214 Lee email: admin214@email.com attachments: [] url: redacted: false contacts: type: contact.list contacts: - type: contact id: 6762f15e1bb69f9f2193bbbd external_id: '70' first_contact_reply: admin_assignee_id: team_assignee_id: open: false state: closed read: false tags: type: tag.list tags: [] priority: not_priority sla_applied: statistics: conversation_rating: teammates: title: custom_attributes: {} topics: {} ticket: linked_objects: type: list data: [] total_count: 0 has_more: false ai_agent: ai_agent_participated: false conversation_parts: type: conversation_part.list conversation_parts: - type: conversation_part id: '134' part_type: quick_reply body: created_at: 1734537568 updated_at: 1734537568 notified_at: 1734537568 assigned_to: author: id: '991267698' type: admin name: Ciaran214 Lee email: admin214@email.com attachments: [] external_id: redacted: false metadata: {} email_message_metadata: app_package_code: null total_count: 1 User last conversation reply: value: type: conversation id: '527' created_at: 1734537571 updated_at: 1734537572 waiting_since: 1734537572 snoozed_until: source: type: conversation id: '403918352' delivered_as: admin_initiated subject: '' body: "this is the message body
" author: type: admin id: '991267700' name: Ciaran215 Lee email: admin215@email.com attachments: [] url: redacted: false contacts: type: contact.list contacts: - type: contact id: 6762f1621bb69f9f2193bbbe external_id: '70' first_contact_reply: created_at: 1734537572 type: conversation url: admin_assignee_id: team_assignee_id: open: true state: open read: false tags: type: tag.list tags: [] priority: not_priority sla_applied: statistics: conversation_rating: teammates: title: custom_attributes: {} topics: {} ticket: linked_objects: type: list data: [] total_count: 0 has_more: false ai_agent: ai_agent_participated: false conversation_parts: type: conversation_part.list conversation_parts: - type: conversation_part id: '135' part_type: open body: "Thanks again :)
" created_at: 1734537572 updated_at: 1734537572 notified_at: 1734537572 assigned_to: author: id: 6762f1621bb69f9f2193bbbe type: user name: Joe Bloggs email: joe@bloggs.com attachments: [] external_id: redacted: false metadata: {} email_message_metadata: app_package_code: null total_count: 1 schema: "$ref": "#/components/schemas/conversation" '404': description: Not found content: application/json: examples: Not found: value: type: error.list request_id: '06234918-c245-4caa-a2cc-90247983c6ff' errors: - code: not_found message: Resource Not Found schema: "$ref": "#/components/schemas/error" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: 50f1e8d1-cf1a-450c-a7b5-87a264076241 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" '403': description: API plan restricted content: application/json: examples: API plan restricted: value: type: error.list request_id: 48ad16d0-525c-40bf-b733-89239feb70e3 errors: - code: api_plan_restricted message: Active subscription needed. schema: "$ref": "#/components/schemas/error" requestBody: content: application/json: schema: "$ref": "#/components/schemas/reply_conversation_request" examples: user_reply: summary: User reply value: message_type: comment type: user intercom_user_id: 6762f1571bb69f9f2193bbbb body: Thanks again :) admin_note_reply: summary: Admin Reply with a Note value: message_type: note type: admin admin_id: 991267696 body: "this is the message body
" author: type: admin id: '991267708' name: Ciaran219 Lee email: admin219@email.com attachments: [] url: redacted: false contacts: type: contact.list contacts: - type: contact id: 6762f16e1bb69f9f2193bbc2 external_id: '70' first_contact_reply: admin_assignee_id: team_assignee_id: open: false state: closed read: false tags: type: tag.list tags: [] priority: not_priority sla_applied: statistics: conversation_rating: teammates: title: custom_attributes: {} topics: {} ticket: linked_objects: type: list data: [] total_count: 0 has_more: false ai_agent: ai_agent_participated: false conversation_parts: type: conversation_part.list conversation_parts: - type: conversation_part id: '136' part_type: close body: "Goodbye :)
" created_at: 1734537584 updated_at: 1734537584 notified_at: 1734537584 assigned_to: author: id: '991267708' type: admin name: Ciaran219 Lee email: admin219@email.com attachments: [] external_id: redacted: false metadata: {} email_message_metadata: app_package_code: null total_count: 1 Snooze a conversation: value: type: conversation id: '532' created_at: 1734537586 updated_at: 1734537587 waiting_since: snoozed_until: 1734541187 source: type: conversation id: '403918357' delivered_as: admin_initiated subject: '' body: "this is the message body
" author: type: admin id: '991267710' name: Ciaran220 Lee email: admin220@email.com attachments: [] url: redacted: false contacts: type: contact.list contacts: - type: contact id: 6762f1711bb69f9f2193bbc3 external_id: '70' first_contact_reply: admin_assignee_id: team_assignee_id: open: true state: snoozed read: false tags: type: tag.list tags: [] priority: not_priority sla_applied: statistics: conversation_rating: teammates: title: custom_attributes: {} topics: {} ticket: linked_objects: type: list data: [] total_count: 0 has_more: false ai_agent: ai_agent_participated: false conversation_parts: type: conversation_part.list conversation_parts: - type: conversation_part id: '137' part_type: snoozed body: created_at: 1734537587 updated_at: 1734537587 notified_at: 1734537587 assigned_to: author: id: '991267710' type: admin name: Ciaran220 Lee email: admin220@email.com attachments: [] external_id: redacted: false metadata: {} email_message_metadata: app_package_code: null total_count: 1 Open a conversation: value: type: conversation id: '537' created_at: 1734537587 updated_at: 1734537601 waiting_since: snoozed_until: source: type: conversation id: '403918358' delivered_as: admin_initiated subject: '' body: "this is the message body
" author: type: admin id: '991267712' name: Ciaran221 Lee email: admin221@email.com attachments: [] url: redacted: false contacts: type: contact.list contacts: - type: contact id: 6762f1781bb69f9f2193bbc8 external_id: '74' first_contact_reply: admin_assignee_id: team_assignee_id: open: true state: open read: true tags: type: tag.list tags: [] priority: not_priority sla_applied: statistics: conversation_rating: teammates: title: '' custom_attributes: {} topics: {} ticket: linked_objects: type: list data: [] total_count: 0 has_more: false ai_agent: ai_agent_participated: false conversation_parts: type: conversation_part.list conversation_parts: - type: conversation_part id: '139' part_type: open body: created_at: 1734537601 updated_at: 1734537601 notified_at: 1734537601 assigned_to: author: id: '991267712' type: admin name: Ciaran221 Lee email: admin221@email.com attachments: [] external_id: redacted: false metadata: {} email_message_metadata: app_package_code: null total_count: 1 Assign a conversation: value: type: conversation id: '542' created_at: 1734537603 updated_at: 1734537605 waiting_since: snoozed_until: source: type: conversation id: '403918361' delivered_as: admin_initiated subject: '' body: "this is the message body
" author: type: admin id: '991267715' name: Ciaran223 Lee email: admin223@email.com attachments: [] url: redacted: false contacts: type: contact.list contacts: - type: contact id: 6762f1831bb69f9f2193bbcc external_id: '70' first_contact_reply: admin_assignee_id: 991267715 team_assignee_id: open: true state: open read: false tags: type: tag.list tags: [] priority: not_priority sla_applied: statistics: conversation_rating: teammates: title: custom_attributes: {} topics: {} ticket: linked_objects: type: list data: [] total_count: 0 has_more: false ai_agent: ai_agent_participated: false conversation_parts: type: conversation_part.list conversation_parts: - type: conversation_part id: '140' part_type: assign_and_reopen body: created_at: 1734537605 updated_at: 1734537605 notified_at: 1734537605 assigned_to: type: admin id: '991267715' author: id: '991267715' type: admin name: Ciaran223 Lee email: admin223@email.com attachments: [] external_id: redacted: false metadata: {} email_message_metadata: app_package_code: null total_count: 1 schema: "$ref": "#/components/schemas/conversation" '404': description: Not found content: application/json: examples: Not found: value: type: error.list request_id: e056b3c3-fae3-4a3c-9bcf-836b84efa331 errors: - code: not_found message: Resource Not Found schema: "$ref": "#/components/schemas/error" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: 623bbbb8-f6fb-45f3-a2e2-4106ff3a4349 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" '403': description: API plan restricted content: application/json: examples: API plan restricted: value: type: error.list request_id: a57737d0-63a7-42bd-aa65-8380ef828124 errors: - code: api_plan_restricted message: Active subscription needed. schema: "$ref": "#/components/schemas/error" requestBody: content: application/json: schema: oneOf: - "$ref": "#/components/schemas/close_conversation_request" - "$ref": "#/components/schemas/snooze_conversation_request" - "$ref": "#/components/schemas/open_conversation_request" - "$ref": "#/components/schemas/assign_conversation_request" examples: close_a_conversation: summary: Close a conversation value: message_type: close type: admin admin_id: 991267708 body: Goodbye :) snooze_a_conversation: summary: Snooze a conversation value: message_type: snoozed admin_id: 991267710 snoozed_until: 1734541187 open_a_conversation: summary: Open a conversation value: message_type: open admin_id: 991267712 assign_a_conversation: summary: Assign a conversation value: message_type: assignment type: admin admin_id: 991267715 assignee_id: 991267715 not_found: summary: Not found value: message_type: close type: admin admin_id: 991267717 body: Goodbye :) "/conversations/{conversation_id}/customers": post: summary: Attach a contact to a conversation parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: conversation_id in: path required: true description: The identifier for the conversation as given by Intercom. example: '123' schema: type: string tags: - Conversations operationId: attachContactToConversation description: |+ You can add participants who are contacts to a conversation, on behalf of either another contact or an admin. {% admonition type="warning" name="Contacts without an email" %} If you add a contact via the email parameter and there is no user/lead found on that workspace with he given email, then we will create a new contact with `role` set to `lead`. {% /admonition %} responses: '200': description: Attach a contact to a conversation content: application/json: examples: Attach a contact to a conversation: value: customers: - type: user id: 6762f19b1bb69f9f2193bbd4 schema: "$ref": "#/components/schemas/conversation" '404': description: Not found content: application/json: examples: Not found: value: type: error.list request_id: 86fd8b2e-7048-4fbd-9fb0-d73085d7210b errors: - code: not_found message: Resource Not Found schema: "$ref": "#/components/schemas/error" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: 9dc7c1a0-b818-472c-adf6-3e327f22f541 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" '403': description: API plan restricted content: application/json: examples: API plan restricted: value: type: error.list request_id: 99f72599-ac98-4b1e-af96-808654b6383e errors: - code: api_plan_restricted message: Active subscription needed. schema: "$ref": "#/components/schemas/error" requestBody: content: application/json: schema: "$ref": "#/components/schemas/attach_contact_to_conversation_request" examples: attach_a_contact_to_a_conversation: summary: Attach a contact to a conversation value: admin_id: 991267731 customer: intercom_user_id: 6762f19b1bb69f9f2193bbd4 not_found: summary: Not found value: admin_id: 991267733 customer: intercom_user_id: 6762f19e1bb69f9f2193bbd5 "/conversations/{conversation_id}/customers/{contact_id}": delete: summary: Detach a contact from a group conversation parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: conversation_id in: path required: true description: The identifier for the conversation as given by Intercom. example: '123' schema: type: string - name: contact_id in: path required: true description: The identifier for the contact as given by Intercom. example: '123' schema: type: string tags: - Conversations operationId: detachContactFromConversation description: |+ You can add participants who are contacts to a conversation, on behalf of either another contact or an admin. {% admonition type="warning" name="Contacts without an email" %} If you add a contact via the email parameter and there is no user/lead found on that workspace with he given email, then we will create a new contact with `role` set to `lead`. {% /admonition %} responses: '200': description: Detach a contact from a group conversation content: application/json: examples: Detach a contact from a group conversation: value: customers: - type: user id: 6762f1b41bb69f9f2193bbe0 schema: "$ref": "#/components/schemas/conversation" '404': description: Contact not found content: application/json: examples: Conversation not found: value: type: error.list request_id: 89835b60-6756-4d2a-b148-26ca0cb49f9f errors: - code: not_found message: Resource Not Found Contact not found: value: type: error.list request_id: ab1b9371-3185-417f-a53a-dcae35892980 errors: - code: not_found message: User Not Found schema: "$ref": "#/components/schemas/error" '422': description: Last customer content: application/json: examples: Last customer: value: type: error.list request_id: 8275e92f-66b7-40f9-82a8-9647ca8d7eb4 errors: - code: parameter_invalid message: Removing the last customer is not allowed schema: "$ref": "#/components/schemas/error" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: 89ef64b2-d1f9-40c3-89e9-d39175d3d647 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" '403': description: API plan restricted content: application/json: examples: API plan restricted: value: type: error.list request_id: 6fe4106b-967a-46ba-b1c9-9996aff6e8c3 errors: - code: api_plan_restricted message: Active subscription needed. schema: "$ref": "#/components/schemas/error" requestBody: content: application/json: schema: "$ref": "#/components/schemas/detach_contact_from_conversation_request" examples: detach_a_contact_from_a_group_conversation: summary: Detach a contact from a group conversation value: admin_id: 991267739 customer: intercom_user_id: 6762f1a61bb69f9f2193bbd8 conversation_not_found: summary: Conversation not found value: admin_id: 991267742 customer: intercom_user_id: 6762f1b61bb69f9f2193bbe1 contact_not_found: summary: Contact not found value: admin_id: 991267745 customer: intercom_user_id: 6762f1c41bb69f9f2193bbe9 last_customer: summary: Last customer value: admin_id: 991267748 customer: intercom_user_id: 6762f1d11bb69f9f2193bbf1 "/conversations/redact": post: summary: Redact a conversation part parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" tags: - Conversations operationId: redactConversation description: |+ You can redact a conversation part or the source message of a conversation (as seen in the source object). {% admonition type="info" name="Redacting parts and messages" %} If you are redacting a conversation part, it must have a `body`. If you are redacting a source message, it must have been created by a contact. We will return a `conversation_part_not_redactable` error if these criteria are not met. {% /admonition %} responses: '200': description: Redact a conversation part content: application/json: examples: Redact a conversation part: value: type: conversation id: '608' created_at: 1734537721 updated_at: 1734537724 waiting_since: 1734537722 snoozed_until: source: type: conversation id: '403918391' delivered_as: admin_initiated subject: '' body: "this is the message body
" author: type: admin id: '991267757' name: Ciaran247 Lee email: admin247@email.com attachments: [] url: redacted: false contacts: type: contact.list contacts: - type: contact id: 6762f1f81bb69f9f2193bc09 external_id: '70' first_contact_reply: created_at: 1734537722 type: conversation url: admin_assignee_id: team_assignee_id: open: true state: open read: true tags: type: tag.list tags: [] priority: not_priority sla_applied: statistics: conversation_rating: teammates: title: custom_attributes: {} topics: {} ticket: linked_objects: type: list data: [] total_count: 0 has_more: false ai_agent: ai_agent_participated: false conversation_parts: type: conversation_part.list conversation_parts: - type: conversation_part id: '149' part_type: open body: "This message was deleted
" created_at: 1734537722 updated_at: 1734537724 notified_at: 1734537722 assigned_to: author: id: 6762f1f81bb69f9f2193bc09 type: user name: Joe Bloggs email: joe@bloggs.com attachments: [] external_id: redacted: true metadata: {} email_message_metadata: app_package_code: null total_count: 1 schema: "$ref": "#/components/schemas/conversation" '404': description: Not found content: application/json: examples: Not found: value: type: error.list request_id: 5b7bb755-4031-4bfe-8897-54d0f1872bbc errors: - code: conversation_part_or_message_not_found message: Conversation part or message not found schema: "$ref": "#/components/schemas/error" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: 4814668f-5d31-4bf7-8f66-b426aac054db errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" requestBody: content: application/json: schema: "$ref": "#/components/schemas/redact_conversation_request" examples: redact_a_conversation_part: summary: Redact a conversation part value: type: conversation_part conversation_id: 608 conversation_part_id: 149 not_found: summary: Not found value: type: conversation_part conversation_id: really_123_doesnt_exist conversation_part_id: really_123_doesnt_exist "/conversations/{conversation_id}/convert": post: summary: Convert a conversation to a ticket parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: conversation_id in: path required: true description: The id of the conversation to target example: 123 schema: type: integer tags: - Conversations description: You can convert a conversation to a ticket. operationId: convertConversationToTicket responses: '200': description: successful content: application/json: examples: successful: value: type: ticket id: '611' ticket_id: '22' ticket_attributes: {} ticket_state: type: ticket_state id: '7493' category: submitted internal_label: Submitted external_label: Submitted ticket_type: type: ticket_type id: '53' name: my-ticket-type-1 description: my ticket type description is awesome. icon: "\U0001F981" workspace_id: this_is_an_id442_that_should_be_at_least_ archived: false created_at: 1734537737 updated_at: 1734537737 is_internal: false ticket_type_attributes: type: list data: [] category: Customer contacts: type: contact.list contacts: - type: contact id: 6762f2041bb69f9f2193bc0c external_id: '70' admin_assignee_id: '0' team_assignee_id: '0' created_at: 1734537732 updated_at: 1734537737 ticket_parts: type: ticket_part.list ticket_parts: - type: ticket_part id: '151' part_type: comment body: "Comment for message
" created_at: 1734537732 updated_at: 1734537732 author: id: 6762f2041bb69f9f2193bc0c type: user name: Joe Bloggs email: joe@bloggs.com attachments: [] redacted: false app_package_code: test-integration - type: ticket_part id: '152' part_type: ticket_state_updated_by_admin ticket_state: submitted previous_ticket_state: submitted created_at: 1734537737 updated_at: 1734537737 author: id: '991267767' type: bot name: Fin email: operator+this_is_an_id442_that_should_be_at_least_@intercom.io attachments: [] redacted: false app_package_code: test-integration total_count: 2 open: true linked_objects: type: list data: [] total_count: 0 has_more: false category: Customer is_shared: true schema: "$ref": "#/components/schemas/ticket" '400': description: Bad request content: application/json: examples: Bad request: value: type: error.list request_id: 450e0b22-ccc2-40dd-bf54-bc0faaa28f57 errors: - code: parameter_invalid message: Ticket type is not a customer ticket type schema: "$ref": "#/components/schemas/error" requestBody: content: application/json: schema: "$ref": "#/components/schemas/convert_conversation_to_ticket_request" examples: successful: summary: successful value: ticket_type_id: '53' bad_request: summary: Bad request value: ticket_type_id: '54' "/custom_channel_events/notify_new_conversation": post: summary: Notify Intercom of a new conversation created in a custom channel tags: - Custom Channel Events operationId: notifyNewConversation description: | Notifies Intercom that a new conversation was created in your custom channel/platform. This triggers conversation creation and workflow automations within Intercom for your custom channel integration. > **Note:** This endpoint is currently under managed availability. Please reach out to your accounts team to discuss access and tailored, hands-on support. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/custom_channel_base_event' examples: example-1: summary: Example request value: event_id: "evt_12345" external_conversation_id: "conv_67890" contact: type: "user" external_id: "user_001" name: "Jane Doe" email: "jane.doe@example.com" responses: '200': $ref: '#/components/responses/CustomChannelNotificationSuccess' '400': $ref: '#/components/responses/BadRequest' '401': $ref: "#/components/responses/Unauthorized" '404': $ref: '#/components/responses/ObjectNotFound' '422': $ref: '#/components/responses/ValidationError' "/custom_channel_events/notify_new_message": post: summary: Notify Intercom of a new message in a custom channel conversation tags: - Custom Channel Events operationId: notifyNewMessage description: | Notifies Intercom that a new message was sent in a conversation on your custom channel/platform. This allows Intercom to process the message and trigger any relevant workflow automations. > **Note:** This endpoint is currently under managed availability. Please reach out to your accounts team to discuss access and tailored, hands-on support. requestBody: required: true content: application/json: schema: allOf: - $ref: '#/components/schemas/custom_channel_base_event' - type: object properties: body: type: string description: The message content sent by the user. required: - body examples: example-1: summary: Example request value: event_id: "evt_54321" external_conversation_id: "conv_98765" contact: type: "user" external_id: "user_002" name: "John Smith" email: "john.smith@example.com" body: "Hello, I need help with my order." responses: '200': $ref: '#/components/responses/CustomChannelNotificationSuccess' '400': $ref: '#/components/responses/BadRequest' '401': $ref: "#/components/responses/Unauthorized" '404': $ref: '#/components/responses/ObjectNotFound' '422': $ref: '#/components/responses/ValidationError' "/custom_channel_events/notify_quick_reply_selected": post: summary: Notify Intercom of a quick reply response in a custom channel conversation tags: - Custom Channel Events operationId: notifyQuickReplySelected description: | Notifies Intercom that a user selected a quick reply option in your custom channel/platform. This allows Intercom to process the response and trigger any relevant workflow automations. > **Note:** This endpoint is currently under managed availability. Please reach out to your accounts team to discuss access and tailored, hands-on support. requestBody: required: true content: application/json: schema: allOf: - $ref: '#/components/schemas/custom_channel_base_event' - type: object properties: quick_reply_option_id: type: string description: Id of the selected quick reply option. required: - quick_reply_option_id examples: example-1: summary: Example request value: event_id: "evt_67890" external_conversation_id: "conv_13579" contact: type: "user" external_id: "user_003" name: "Alice Example" email: "alice@example.com" quick_reply_option_id: "1234" responses: '200': $ref: '#/components/responses/CustomChannelNotificationSuccess' '400': $ref: '#/components/responses/BadRequest' '401': $ref: "#/components/responses/Unauthorized" '404': $ref: '#/components/responses/ObjectNotFound' '422': $ref: '#/components/responses/ValidationError' "/custom_channel_events/notify_attribute_collected": post: summary: Notify Intercom of an attribute collector response in a custom channel conversation tags: - Custom Channel Events operationId: notifyAttributeCollected description: | Notifies Intercom that a user provided a response to an attribute collector in your custom channel/platform. This allows Intercom to process the attribute and trigger any relevant workflow automations. > **Note:** This endpoint is currently under managed availability. Please reach out to your accounts team to discuss access and tailored, hands-on support. requestBody: required: true content: application/json: schema: allOf: - $ref: '#/components/schemas/custom_channel_base_event' - type: object properties: attribute: $ref: '#/components/schemas/custom_channel_attribute' required: - attribute examples: example-1: summary: Example request value: event_id: "evt_24680" external_conversation_id: "conv_11223" contact: type: "user" external_id: "user_004" name: "Bob Example" email: "bob@example.com" attribute: id: "shipping_address" value: "123 Main St, Springfield" responses: '200': $ref: '#/components/responses/CustomChannelNotificationSuccess' '400': $ref: '#/components/responses/BadRequest' '401': $ref: "#/components/responses/Unauthorized" '404': $ref: '#/components/responses/ObjectNotFound' '422': $ref: '#/components/responses/ValidationError' "/custom_object_instances/{custom_object_type_identifier}": parameters: - name: custom_object_type_identifier in: path description: The unique identifier of the custom object type that defines the structure of the custom object instance. example: Order required: true schema: type: string post: summary: Create or Update a Custom Object Instance parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" tags: - Custom Object Instances operationId: createCustomObjectInstances description: Create or update a custom object instance responses: '200': description: successful content: application/json: examples: successful: value: id: '22' type: Order custom_attributes: order_number: ORDER-12345 total_amount: 99.99 external_id: '123' external_created_at: 1392036272 external_updated_at: 1392036272 created_at: 1734537745 updated_at: 1734537745 schema: "$ref": "#/components/schemas/custom_object_instance" '401': $ref: "#/components/responses/Unauthorized" '404': $ref: "#/components/responses/TypeNotFound" requestBody: content: application/json: schema: "$ref": "#/components/schemas/create_or_update_custom_object_instance_request" examples: successful: summary: successful value: external_id: '123' external_created_at: 1392036272 external_updated_at: 1392036272 custom_attributes: order_number: ORDER-12345 total_amount: 99.99 get: summary: Get Custom Object Instance by External ID parameters: - name: external_id in: query style: form required: true schema: type: string description: The unique identifier for the instance in the external system it originated from. title: Find by external_id properties: external_id: type: string required: - external_id - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" tags: - Custom Object Instances operationId: getCustomObjectInstancesByExternalId description: Fetch a Custom Object Instance by external_id. responses: '200': description: successful content: application/json: examples: successful: value: id: '24' type: Order custom_attributes: order_number: ORDER-12345 total_amount: 99.99 external_id: '123' external_created_at: external_updated_at: created_at: 1734537748 updated_at: 1734537748 schema: "$ref": "#/components/schemas/custom_object_instance" '401': $ref: "#/components/responses/Unauthorized" '404': $ref: "#/components/responses/ObjectNotFound" delete: summary: Delete a Custom Object Instance by External ID parameters: - name: external_id in: query style: form required: true schema: type: string description: The unique identifier for the instance in the external system it originated from. title: Find by external_id properties: external_id: type: string required: - external_id - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" tags: - Custom Object Instances operationId: deleteCustomObjectInstancesById description: Delete a single Custom Object instance by external_id. responses: '200': description: successful content: application/json: examples: successful: value: id: '26' object: Order deleted: true schema: "$ref": "#/components/schemas/custom_object_instance_deleted" '401': $ref: "#/components/responses/Unauthorized" '404': $ref: "#/components/responses/ObjectNotFound" "/custom_object_instances/{custom_object_type_identifier}/{custom_object_instance_id}": parameters: - name: custom_object_type_identifier in: path description: The unique identifier of the custom object type that defines the structure of the custom object instance. example: Order required: true schema: type: string get: summary: Get Custom Object Instance by ID parameters: - name: custom_object_instance_id in: path description: The id or external_id of the custom object instance required: true schema: type: string - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" tags: - Custom Object Instances operationId: getCustomObjectInstancesById description: Fetch a Custom Object Instance by id. responses: '200': description: successful content: application/json: examples: successful: value: id: '25' type: Order custom_attributes: order_number: ORDER-12345 total_amount: 99.99 external_id: '123' external_created_at: external_updated_at: created_at: 1734537750 updated_at: 1734537750 schema: "$ref": "#/components/schemas/custom_object_instance" '401': $ref: "#/components/responses/Unauthorized" '404': $ref: "#/components/responses/ObjectNotFound" delete: summary: Delete a Custom Object Instance by ID parameters: - name: custom_object_instance_id in: path description: The Intercom defined id of the custom object instance required: true schema: type: string - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" tags: - Custom Object Instances operationId: deleteCustomObjectInstancesByExternalId description: Delete a single Custom Object instance using the Intercom defined id. responses: '200': description: successful content: application/json: examples: successful: value: id: '26' object: Order deleted: true schema: "$ref": "#/components/schemas/custom_object_instance_deleted" '401': $ref: "#/components/responses/Unauthorized" '404': $ref: "#/components/responses/ObjectNotFound" "/data_attributes": get: summary: List all data attributes parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: model in: query required: false description: Specify the data attribute model to return. schema: type: string enum: - contact - company - conversation example: company - name: include_archived in: query required: false description: Include archived attributes in the list. By default we return only non archived data attributes. example: false schema: type: boolean tags: - Data Attributes operationId: lisDataAttributes description: You can fetch a list of all data attributes belonging to a workspace for contacts, companies or conversations. responses: '200': description: Successful response content: application/json: examples: Successful response: value: type: list data: - type: data_attribute name: name full_name: name label: Company name description: The name of a company data_type: string api_writable: true ui_writable: false messenger_writable: true custom: false archived: false model: company - type: data_attribute name: company_id full_name: company_id label: Company ID description: A number identifying a company data_type: string api_writable: false ui_writable: false messenger_writable: true custom: false archived: false model: company - type: data_attribute name: last_request_at full_name: last_request_at label: Company last seen description: The last day anyone from a company visited your site or app data_type: date api_writable: false ui_writable: false messenger_writable: true custom: false archived: false model: company - type: data_attribute name: remote_created_at full_name: remote_created_at label: Company created at description: The day a company was added to Intercom data_type: date api_writable: true ui_writable: false messenger_writable: true custom: false archived: false model: company - type: data_attribute name: user_count full_name: user_count label: People description: The number of people in a company data_type: integer api_writable: false ui_writable: false messenger_writable: true custom: false archived: false model: company - type: data_attribute name: session_count full_name: session_count label: Company web sessions description: All visits from anyone in a company to your product's site or app data_type: integer api_writable: false ui_writable: false messenger_writable: true custom: false archived: false model: company - type: data_attribute name: name full_name: plan.name label: Plan description: A specific plan or level within your product that companies have signed up to data_type: string api_writable: false ui_writable: false messenger_writable: true custom: false archived: false model: company - type: data_attribute name: monthly_spend full_name: monthly_spend label: Monthly Spend description: The monthly revenue you receive from a company data_type: float api_writable: true ui_writable: false messenger_writable: true custom: false archived: false model: company - type: data_attribute name: size full_name: size label: Company size description: The number of people employed in this company, expressed as a single number data_type: integer api_writable: true ui_writable: false messenger_writable: true custom: false archived: false model: company - type: data_attribute name: industry full_name: industry label: Company industry description: The category or domain this company belongs to e.g. 'ecommerce' or 'SaaS' data_type: string api_writable: true ui_writable: false messenger_writable: true custom: false archived: false model: company - type: data_attribute name: website full_name: website label: Company website description: The web address for the company's primary marketing site data_type: string api_writable: true ui_writable: false messenger_writable: true custom: false archived: false model: company - id: 34 type: data_attribute name: The One Ring full_name: custom_attributes.The One Ring label: The One Ring description: One ring to rule them all, one ring to find them, One ring to bring them all and in the darkness bind them. data_type: string api_writable: true ui_writable: false messenger_writable: true custom: true archived: false admin_id: '991267784' created_at: 1734537753 updated_at: 1734537753 model: company - type: data_attribute name: id full_name: id label: ID description: The Intercom defined id representing the company data_type: string api_writable: false ui_writable: false messenger_writable: true custom: false archived: false model: company - type: data_attribute name: created_at full_name: created_at label: Created at description: The time the company was added to Intercom data_type: date api_writable: false ui_writable: false messenger_writable: true custom: false archived: false model: company - type: data_attribute name: updated_at full_name: updated_at label: Updated at description: The last time the company was updated data_type: date api_writable: false ui_writable: false messenger_writable: true custom: false archived: false model: company - type: data_attribute name: id full_name: plan.id label: Plan ID description: The Intercom defined id representing the plan data_type: string api_writable: false ui_writable: false messenger_writable: true custom: false archived: false model: company - type: data_attribute name: app_id full_name: app_id label: App ID description: The Intercom defined id representing the app data_type: string api_writable: false ui_writable: false messenger_writable: true custom: false archived: false model: company schema: "$ref": "#/components/schemas/data_attribute_list" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: 6d231766-b44b-4e78-bc9e-9c268ff19671 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" post: summary: Create a data attribute parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" tags: - Data Attributes operationId: createDataAttribute description: You can create a data attributes for a `contact` or a `company`. responses: '200': description: Successful content: application/json: examples: Successful: value: id: 37 type: data_attribute name: Mithril Shirt full_name: custom_attributes.Mithril Shirt label: Mithril Shirt data_type: string api_writable: true ui_writable: false messenger_writable: false custom: true archived: false admin_id: '991267786' created_at: 1734537756 updated_at: 1734537756 model: company schema: "$ref": "#/components/schemas/data_attribute" '400': description: Too few options for list content: application/json: examples: Same name already exists: value: type: error.list request_id: da2a7037-11f4-4fcc-8d19-27da3b3a4336 errors: - code: parameter_invalid message: You already have 'The One Ring' in your company data. To save this as new people data, use a different name. Invalid name: value: type: error.list request_id: 1c45cfd9-ffd1-4e3e-9f7a-2ac99abdf03d errors: - code: parameter_invalid message: Your name for this attribute must only contain alphanumeric characters, currency symbols, and hyphens Attribute already exists: value: type: error.list request_id: 55999605-a170-4894-a3d0-090c4fee8d11 errors: - code: parameter_invalid message: You already have 'The One Ring' in your company data. To save this as new company data, use a different name. Invalid Data Type: value: type: error.list request_id: e0a9ccc7-a540-4ef0-8ffc-28ab86658b04 errors: - code: parameter_invalid message: Data Type isn't an option Too few options for list: value: type: error.list request_id: 6544ccf8-435d-49e1-91ed-e49356f14255 errors: - code: parameter_invalid message: The Data Attribute model field must be either contact or company schema: "$ref": "#/components/schemas/error" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: fa71b91c-4a25-4fe6-88a9-884f6950860e errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" requestBody: content: application/json: schema: "$ref": "#/components/schemas/create_data_attribute_request" examples: successful: summary: Successful value: name: Mithril Shirt model: company data_type: string same_name_already_exists: summary: Same name already exists value: name: The One Ring model: contact data_type: integer invalid_name: summary: Invalid name value: name: "!nv@l!d n@me" model: company data_type: string attribute_already_exists: summary: Attribute already exists value: name: The One Ring model: company data_type: string invalid_data_type: summary: Invalid Data Type value: name: The Second Ring model: company data_type: mithril too_few_options_for_list: summary: Too few options for list value: description: Just a plain old ring options: - value: 1-10 archived: false "/data_attributes/{data_attribute_id}": put: summary: Update a data attribute parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: data_attribute_id in: path required: true description: The data attribute id example: 1 schema: type: integer tags: - Data Attributes operationId: updateDataAttribute description: "\nYou can update a data attribute.\n\n> \U0001F6A7 Updating the data type is not possible\n>\n> It is currently a dangerous action to execute changing a data attribute's type via the API. You will need to update the type via the UI instead.\n" responses: '200': description: Successful content: application/json: examples: Successful: value: id: 44 type: data_attribute name: The One Ring full_name: custom_attributes.The One Ring label: The One Ring description: Just a plain old ring data_type: string options: - 1-10 - 11-20 api_writable: true ui_writable: false messenger_writable: true custom: true archived: false admin_id: '991267793' created_at: 1734537762 updated_at: 1734537763 model: company schema: "$ref": "#/components/schemas/data_attribute" '400': description: Too few options in list content: application/json: examples: Too few options in list: value: type: error.list request_id: 37cff4c5-5e1a-4958-a2ba-149b09d1915c errors: - code: parameter_invalid message: Options isn't an array schema: "$ref": "#/components/schemas/error" '404': description: Attribute Not Found content: application/json: examples: Attribute Not Found: value: type: error.list request_id: eee16d31-0b0a-4b5f-b95a-25d37528c80f errors: - code: field_not_found message: We couldn't find that data attribute to update schema: "$ref": "#/components/schemas/error" '422': description: Has Dependant Object content: application/json: examples: Has Dependant Object: value: type: error.list request_id: f04b6b14-1c5b-46e1-9c95-4a914557062c errors: - code: data_invalid message: The Data Attribute you are trying to archive has a dependant object schema: "$ref": "#/components/schemas/error" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: c60ce63d-1c74-4fe2-8e21-31d1f817a0c2 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" requestBody: content: application/json: schema: "$ref": "#/components/schemas/update_data_attribute_request" examples: successful: summary: Successful value: description: Just a plain old ring options: - value: 1-10 - value: 11-20 archived: false too_few_options_in_list: summary: Too few options in list value: description: Too few options options: value: 1-10 archived: false attribute_not_found: summary: Attribute Not Found value: description: Just a plain old ring options: - value: 1-10 - value: 11-20 archived: false has_dependant_object: summary: Has Dependant Object value: description: Trying to archieve archived: true "/events": post: summary: Submit a data event parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" tags: - Data Events operationId: createDataEvent description: |2+ You will need an Access Token that has write permissions to send Events. Once you have a key you can submit events via POST to the Events resource, which is located at https://api.intercom.io/events, or you can send events using one of the client libraries. When working with the HTTP API directly a client should send the event with a `Content-Type` of `application/json`. When using the JavaScript API, [adding the code to your app](http://docs.intercom.io/configuring-Intercom/tracking-user-events-in-your-app) makes the Events API available. Once added, you can submit an event using the `trackEvent` method. This will associate the event with the Lead or currently logged-in user or logged-out visitor/lead and send it to Intercom. The final parameter is a map that can be used to send optional metadata about the event. With the Ruby client you pass a hash describing the event to `Intercom::Event.create`, or call the `track_user` method directly on the current user object (e.g. `user.track_event`). **NB: For the JSON object types, please note that we do not currently support nested JSON structure.** | Type | Description | Example | | :-------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------- | | String | The value is a JSON String | `"source":"desktop"` | | Number | The value is a JSON Number | `"load": 3.67` | | Date | The key ends with the String `_date` and the value is a [Unix timestamp](http://en.wikipedia.org/wiki/Unix_time), assumed to be in the [UTC](http://en.wikipedia.org/wiki/Coordinated_Universal_Time) timezone. | `"contact_date": 1392036272` | | Link | The value is a HTTP or HTTPS URI. | `"article": "https://example.org/ab1de.html"` | | Rich Link | The value is a JSON object that contains `url` and `value` keys. | `"article": {"url": "https://example.org/ab1de.html", "value":"the dude abides"}` | | Monetary Amount | The value is a JSON object that contains `amount` and `currency` keys. The `amount` key is a positive integer representing the amount in cents. The price in the example to the right denotes €349.99. | `"price": {"amount": 34999, "currency": "eur"}` | **Lead Events** When submitting events for Leads, you will need to specify the Lead's `id`. **Metadata behaviour** - We currently limit the number of tracked metadata keys to 10 per event. Once the quota is reached, we ignore any further keys we receive. The first 10 metadata keys are determined by the order in which they are sent in with the event. - It is not possible to change the metadata keys once the event has been sent. A new event will need to be created with the new keys and you can archive the old one. - There might be up to 24 hrs delay when you send a new metadata for an existing event. **Event de-duplication** The API may detect and ignore duplicate events. Each event is uniquely identified as a combination of the following data - the Workspace identifier, the Contact external identifier, the Data Event name and the Data Event created time. As a result, it is **strongly recommended** to send a second granularity Unix timestamp in the `created_at` field. Duplicated events are responded to using the normal `202 Accepted` code - an error is not thrown, however repeat requests will be counted against any rate limit that is in place. ### HTTP API Responses - Successful responses to submitted events return `202 Accepted` with an empty body. - Unauthorised access will be rejected with a `401 Unauthorized` or `403 Forbidden` response code. - Events sent about users that cannot be found will return a `404 Not Found`. - Event lists containing duplicate events will have those duplicates ignored. - Server errors will return a `500` response code and may contain an error message in the body. responses: '202': description: successful '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: 212c8206-e7a6-44c8-8f27-5f0ad7f1d243 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" requestBody: content: application/json: schema: "$ref": "#/components/schemas/create_data_event_request" get: summary: List all data events parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - in: query name: filter required: true style: form explode: true schema: type: object oneOf: - title: user_id query parameter properties: user_id: type: string required: - user_id additionalProperties: false - title: intercom_user_id query parameter properties: intercom_user_id: type: string required: - intercom_user_id additionalProperties: false - title: email query parameter properties: email: type: string required: - email additionalProperties: false - name: type in: query required: true description: The value must be user schema: type: string - name: summary in: query required: false description: summary flag schema: type: boolean tags: - Data Events operationId: lisDataEvents description: "\n> \U0001F6A7\n>\n> Please note that you can only 'list' events that are less than 90 days old. Event counts and summaries will still include your events older than 90 days but you cannot 'list' these events individually if they are older than 90 days\n\nThe events belonging to a customer can be listed by sending a GET request to `https://api.intercom.io/events` with a user or lead identifier along with a `type` parameter. The identifier parameter can be one of `user_id`, `email` or `intercom_user_id`. The `type` parameter value must be `user`.\n\n- `https://api.intercom.io/events?type=user&user_id={user_id}`\n- `https://api.intercom.io/events?type=user&email={email}`\n- `https://api.intercom.io/events?type=user&intercom_user_id={id}` (this call can be used to list leads)\n\nThe `email` parameter value should be [url encoded](http://en.wikipedia.org/wiki/Percent-encoding) when sending.\n\nYou can optionally define the result page size as well with the `per_page` parameter.\n" responses: '200': description: Successful response content: application/json: examples: Successful response: value: type: event.summary events: [] pages: next: http://api.intercom.test/events?next page email: user26@email.com intercom_user_id: 6762f22b1bb69f9f2193bc12 user_id: 3ecf64d0-9ed1-4e9f-88e1-da7d6e6782f3 schema: "$ref": "#/components/schemas/data_event_summary" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: e6f50446-be4a-40ac-8c8d-6fb91e1040fd errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" "/events/summaries": post: summary: Create event summaries parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" tags: - Data Events operationId: dataEventSummaries description: "Create event summaries for a user. Event summaries are used to track the number of times an event has occurred, the first time it occurred and the last time it occurred.\n\n" responses: '200': description: successful '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: 7a7d8425-2c1b-46ab-8133-c043fc1e5711 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" requestBody: content: application/json: schema: "$ref": "#/components/schemas/create_data_event_summaries_request" "/export/content/data": post: summary: Create content data export parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" tags: - Data Export operationId: createDataExport description: "To create your export job, you need to send a `POST` request to the export endpoint `https://api.intercom.io/export/content/data`.\n\nThe only parameters you need to provide are the range of dates that you want exported.\n\n>\U0001F6A7 Limit of one active job\n>\n> You can only have one active job per workspace. You will receive a HTTP status code of 429 with the message Exceeded rate limit of 1 pending message data export jobs if you attempt to create a second concurrent job.\n\n>❗️ Updated_at not included\n>\n> It should be noted that the timeframe only includes messages sent during the time period and not messages that were only updated during this period. For example, if a message was updated yesterday but sent two days ago, you would need to set the created_at_after date before the message was sent to include that in your retrieval job.\n\n>\U0001F4D8 Date ranges are inclusive\n>\n> Requesting data for 2018-06-01 until 2018-06-30 will get all data for those days including those specified - e.g. 2018-06-01 00:00:00 until 2018-06-30 23:59:99.\n" responses: '200': description: successful content: application/json: examples: successful: value: job_identifier: al9w983lwu88w1fd status: pending download_url: '' download_expires_at: '' schema: "$ref": "#/components/schemas/data_export" requestBody: content: application/json: schema: "$ref": "#/components/schemas/create_data_exports_request" examples: successful: summary: successful value: created_at_after: 1734519776 created_at_before: 1734537776 "/export/content/data/{job_identifier}": get: summary: Show content data export parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: job_identifier in: path description: job_identifier required: true schema: type: string tags: - Data Export operationId: getDataExport description: "You can view the status of your job by sending a `GET` request to the URL\n`https://api.intercom.io/export/content/data/{job_identifier}` - the `{job_identifier}` is the value returned in the response when you first created the export job. More on it can be seen in the Export Job Model.\n\n> \U0001F6A7 Jobs expire after two days\n> All jobs that have completed processing (and are thus available to download from the provided URL) will have an expiry limit of two days from when the export ob completed. After this, the data will no longer be available.\n" responses: '200': description: successful content: application/json: examples: successful: value: job_identifier: braxwk3j039t6txy status: pending download_url: '' download_expires_at: '' schema: "$ref": "#/components/schemas/data_export" "/export/cancel/{job_identifier}": post: summary: Cancel content data export parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: job_identifier in: path description: job_identifier required: true schema: type: string tags: - Data Export operationId: cancelDataExport description: You can cancel your job responses: '200': description: successful content: application/json: examples: successful: value: job_identifier: v134nyc2bku9hj91 status: canceled download_url: '' download_expires_at: '' schema: "$ref": "#/components/schemas/data_export" "/download/content/data/{job_identifier}": get: summary: Download content data export parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: job_identifier in: path description: job_identifier required: true schema: type: string tags: - Data Export operationId: downloadDataExport description: "When a job has a status of complete, and thus a filled download_url, you can download your data by hitting that provided URL, formatted like so: https://api.intercom.io/download/content/data/xyz1234.\n\nYour exported message data will be streamed continuously back down to you in a gzipped CSV format.\n\n> \U0001F4D8 Octet header required\n>\n> You will have to specify the header Accept: `application/octet-stream` when hitting this endpoint.\n" responses: '200': description: successful "/jobs/status/{job_id}": get: summary: Retrieve job status parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: job_id in: path required: true description: The unique identifier for the job which is given by Intercom schema: type: string tags: - Jobs operationId: jobsStatus description: Retrieve the status of job execution. responses: '200': description: Job execution status content: application/json: examples: job status retrieved: value: type: job id: '2' status: success resource_type: ticket resource_id: '20' resource_url: 'https://api.intercom.io/tickets/20' schema: "$ref": "#/components/schemas/jobs" '404': description: Job not found content: application/json: examples: Job not found: value: type: error.list request_id: 123e4567-e89b-12d3-a456-426614174000 errors: - code: job_not_found message: Job Not Found schema: "$ref": "#/components/schemas/error" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: 2c8a20ee-ed09-42c0-a31d-a1b4f5d2742d errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" "/messages": post: summary: Create a message parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" tags: - Messages operationId: createMessage description: "You can create a message that has been initiated by an admin. The conversation can be either an in-app message or an email.\n\n> \U0001F6A7 Sending for visitors\n>\n> There can be a short delay between when a contact is created and when a contact becomes available to be messaged through the API. A 404 Not Found error will be returned in this case.\n\nThis will return the Message model that has been created.\n\n> \U0001F6A7 Retrieving Associated Conversations\n>\n> As this is a message, there will be no conversation present until the contact responds. Once they do, you will have to search for a contact's conversations with the id of the message.\n" responses: '200': description: admin message created content: application/json: examples: user message created: value: type: user_message id: '403918396' created_at: 1734537780 body: heyy message_type: inapp conversation_id: '613' lead message created: value: type: user_message id: '403918397' created_at: 1734537783 body: heyy message_type: inapp conversation_id: '614' admin message created: value: type: admin_message id: '19' created_at: 1734537786 subject: heyy body: heyy message_type: inapp owner: type: admin id: '991267816' name: Ciaran299 Lee email: admin299@email.com away_mode_enabled: false away_mode_reassign: false schema: "$ref": "#/components/schemas/message" '400': description: No body supplied for email message content: application/json: examples: No body supplied for message: value: type: error.list request_id: 3f3e74cc-65af-4408-9bf5-9e71b55c8166 errors: - code: parameter_invalid message: Body is required No body supplied for email message: value: type: error.list request_id: 2d6abc61-1441-4860-9ef0-777852f8b24f errors: - code: parameter_invalid message: Body is required schema: "$ref": "#/components/schemas/error" '422': description: No subject supplied for email message content: application/json: examples: No subject supplied for email message: value: type: error.list request_id: 97db463e-7070-4ac9-9846-9a5d31933772 errors: - code: parameter_not_found message: No subject supplied for email message schema: "$ref": "#/components/schemas/error" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: 2c8a20ee-ed09-42c0-a31d-a1b4f5d2742d errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" '403': description: API plan restricted content: application/json: examples: API plan restricted: value: type: error.list request_id: 72b6821e-54ff-4a25-adf9-abdfef5fe72b errors: - code: api_plan_restricted message: Active subscription needed. schema: "$ref": "#/components/schemas/error" requestBody: content: application/json: schema: "$ref": "#/components/schemas/create_message_request" examples: user_message_created: summary: user message created value: from: type: user id: 6762f2341bb69f9f2193bc17 body: heyy referer: https://twitter.com/bob lead_message_created: summary: lead message created value: from: type: lead id: 6762f2371bb69f9f2193bc18 body: heyy referer: https://twitter.com/bob admin_message_created: summary: admin message created value: from: type: admin id: '991267816' to: - type: user id: 6762f2391bb69f9f2193bc19 - type: lead id: 6762f23c1bb69f9f2193bc1b - type: user id: 6762f23d1bb69f9f2193bc1c cc: - type: user id: 6762f23e1bb69f9f2193bc1d - type: user id: 6762f23f1bb69f9f2193bc1e bcc: - type: user id: 6762f23e1bb69f9f2193bc2f message_type: conversation body: heyy no_body_supplied_for_message: summary: No body supplied for message value: from: type: admin id: '991267818' to: type: user id: 6762f23b1bb69f9f2193bc1a message_type: inapp body: subject: heyy no_subject_supplied_for_email_message: summary: No subject supplied for email message value: from: type: admin id: '991267819' to: type: user user_id: '70' message_type: email body: hey there no_body_supplied_for_email_message: summary: No body supplied for email message value: from: type: admin id: '991267820' to: type: user id: 6762f23d1bb69f9f2193bc1c message_type: email body: subject: heyy "/news/news_items": get: summary: List all news items parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" tags: - News operationId: listNewsItems description: You can fetch a list of all news items responses: '200': description: successful content: application/json: examples: successful: value: type: list pages: page: 1 per_page: 10 total_pages: 1 type: pages data: - id: '29' type: news-item workspace_id: this_is_an_id530_that_should_be_at_least_ title: We have news body: "Hello there,
" sender_id: 991267825 state: draft labels: [] cover_image_url: reactions: - - - - deliver_silently: false created_at: 1734537793 updated_at: 1734537793 newsfeed_assignments: [] - id: '30' type: news-item workspace_id: this_is_an_id530_that_should_be_at_least_ title: We have news body: "Hello there,
" sender_id: 991267827 state: draft labels: [] cover_image_url: reactions: - - - - deliver_silently: false created_at: 1734537793 updated_at: 1734537793 newsfeed_assignments: [] total_count: 2 schema: "$ref": "#/components/schemas/paginated_response" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: d7997515-cd92-4fe4-966c-cb1f4bdda1d4 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" post: summary: Create a news item parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" tags: - News operationId: createNewsItem description: You can create a news item responses: '200': description: successful content: application/json: examples: successful: value: id: '33' type: news-item workspace_id: this_is_an_id534_that_should_be_at_least_ title: Halloween is here! body: "New costumes in store for this spooky season
" sender_id: 991267834 state: live labels: - New - Product - Update cover_image_url: reactions: - "\U0001F606" - "\U0001F605" deliver_silently: true created_at: 1734537797 updated_at: 1734537797 newsfeed_assignments: - newsfeed_id: 53 published_at: 1664638214 schema: "$ref": "#/components/schemas/news_item" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: 5142ad8e-883e-4b71-9adb-6494851e9b77 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" requestBody: content: application/json: schema: "$ref": "#/components/schemas/news_item_request" examples: successful: summary: successful value: title: Halloween is here! body: "New costumes in store for this spooky season
" labels: - Product - Update - New sender_id: 991267834 deliver_silently: true reactions: - "\U0001F606" - "\U0001F605" state: live newsfeed_assignments: - newsfeed_id: 53 published_at: 1664638214 "/news/news_items/{news_item_id}": get: summary: Retrieve a news item parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: news_item_id in: path required: true description: The unique identifier for the news item which is given by Intercom. example: 123 schema: type: integer tags: - News operationId: retrieveNewsItem description: You can fetch the details of a single news item. responses: '200': description: successful content: application/json: examples: successful: value: id: '34' type: news-item workspace_id: this_is_an_id538_that_should_be_at_least_ title: We have news body: "Hello there,
" sender_id: 991267837 state: live labels: [] cover_image_url: reactions: - - - - deliver_silently: false created_at: 1734537800 updated_at: 1734537800 newsfeed_assignments: - newsfeed_id: 55 published_at: 1734537800 schema: "$ref": "#/components/schemas/news_item" '404': description: News Item Not Found content: application/json: examples: News Item Not Found: value: type: error.list request_id: da84e250-8626-47e8-815c-62b33f0f2c36 errors: - code: not_found message: Resource Not Found schema: "$ref": "#/components/schemas/error" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: 33ff62c6-ceb7-4bde-93d6-301bed6f24b2 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" put: summary: Update a news item parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: news_item_id in: path required: true description: The unique identifier for the news item which is given by Intercom. example: 123 schema: type: integer tags: - News operationId: updateNewsItem responses: '200': description: successful content: application/json: examples: successful: value: id: '37' type: news-item workspace_id: this_is_an_id544_that_should_be_at_least_ title: Christmas is here! body: "New gifts in store for the jolly season
" sender_id: 991267845 state: live labels: [] cover_image_url: reactions: - "\U0001F61D" - "\U0001F602" deliver_silently: false created_at: 1734537803 updated_at: 1734537804 newsfeed_assignments: [] schema: "$ref": "#/components/schemas/news_item" '404': description: News Item Not Found content: application/json: examples: News Item Not Found: value: type: error.list request_id: 2014d867-b634-495a-9b4f-ce56c4d657a9 errors: - code: not_found message: Resource Not Found schema: "$ref": "#/components/schemas/error" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: 5838c54e-dd15-460b-82dd-794c4d0e12c5 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" requestBody: content: application/json: schema: "$ref": "#/components/schemas/news_item_request" examples: successful: summary: successful value: title: Christmas is here! body: "New gifts in store for the jolly season
" sender_id: 991267845 reactions: - "\U0001F61D" - "\U0001F602" news_item_not_found: summary: News Item Not Found value: title: Christmas is here! body: "New gifts in store for the jolly season
" sender_id: 991267848 reactions: - "\U0001F61D" - "\U0001F602" delete: summary: Delete a news item parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: news_item_id in: path required: true description: The unique identifier for the news item which is given by Intercom. example: 123 schema: type: integer tags: - News operationId: deleteNewsItem description: You can delete a single news item. responses: '200': description: successful content: application/json: examples: successful: value: id: '40' object: news-item deleted: true schema: "$ref": "#/components/schemas/deleted_object" '404': description: News Item Not Found content: application/json: examples: News Item Not Found: value: type: error.list request_id: 23728e22-7b9f-44a9-9b8d-5028811b9cd0 errors: - code: not_found message: Resource Not Found schema: "$ref": "#/components/schemas/error" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: e5357876-89be-4a04-80c3-16735b7f53ff errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" "/news/newsfeeds/{newsfeed_id}/items": get: summary: List all live newsfeed items parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: newsfeed_id in: path required: true description: The unique identifier for the news feed item which is given by Intercom. example: '123' schema: type: string tags: - News operationId: listLiveNewsfeedItems description: You can fetch a list of all news items that are live on a given newsfeed responses: '200': description: successful content: application/json: examples: successful: value: type: list pages: page: 1 per_page: 20 total_pages: 0 type: pages data: [] total_count: 0 schema: "$ref": "#/components/schemas/paginated_response" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: 022ff8b0-d16f-437c-8217-754c13e16dee errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" "/news/newsfeeds": get: summary: List all newsfeeds parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" tags: - News operationId: listNewsfeeds description: You can fetch a list of all newsfeeds responses: '200': description: successful content: application/json: examples: successful: value: type: list pages: page: 1 per_page: 10 total_pages: 1 type: pages data: - id: '68' type: newsfeed name: Visitor Feed created_at: 1734537813 updated_at: 1734537813 - id: '69' type: newsfeed name: Visitor Feed created_at: 1734537813 updated_at: 1734537813 total_count: 2 schema: "$ref": "#/components/schemas/paginated_response" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: caa26d8b-6512-445d-9418-9fc5849ca304 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" "/news/newsfeeds/{newsfeed_id}": get: summary: Retrieve a newsfeed parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: newsfeed_id in: path required: true description: The unique identifier for the news feed item which is given by Intercom. example: '123' schema: type: string tags: - News operationId: retrieveNewsfeed description: You can fetch the details of a single newsfeed responses: '200': description: successful content: application/json: examples: successful: value: id: '72' type: newsfeed name: Visitor Feed created_at: 1734537815 updated_at: 1734537815 schema: "$ref": "#/components/schemas/newsfeed" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: 6d9a1bf5-aa08-4c93-a61a-5a21130b6553 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" "/notes/{note_id}": get: summary: Retrieve a note parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: note_id in: path required: true description: The unique identifier of a given note example: 1 schema: type: integer tags: - Notes operationId: retrieveNote description: You can fetch the details of a single note. responses: '200': description: Note found content: application/json: examples: Note found: value: type: note id: '34' created_at: 1733846617 contact: type: contact id: 6762f2591bb69f9f2193bc1f author: type: admin id: '991267864' name: Ciaran346 Lee email: admin346@email.com away_mode_enabled: false away_mode_reassign: false body: "This is a note.
" schema: "$ref": "#/components/schemas/note" '404': description: Note not found content: application/json: examples: Note not found: value: type: error.list request_id: bc300b1a-492a-405f-924e-a5881cb72e3a errors: - code: not_found message: Resource Not Found schema: "$ref": "#/components/schemas/error" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: 81384687-5818-4df9-b421-fba77edd6c17 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" "/segments": get: summary: List all segments parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: include_count in: query required: false description: It includes the count of contacts that belong to each segment. example: true schema: type: boolean tags: - Segments operationId: listSegments description: You can fetch a list of all segments. responses: '200': description: Successful response content: application/json: examples: Successful response: value: type: segment.list segments: - type: segment id: 6762f25c1bb69f9f2193bc22 name: John segment created_at: 1734537820 updated_at: 1734537820 person_type: user - type: segment id: 6762f25c1bb69f9f2193bc23 name: Jane segment created_at: 1734537820 updated_at: 1734537820 person_type: user schema: "$ref": "#/components/schemas/segment_list" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: b1939528-98f0-4a63-a442-2cc9203fc8c7 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" "/segments/{segment_id}": get: summary: Retrieve a segment parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: segment_id in: path required: true description: The unique identified of a given segment. example: '123' schema: type: string tags: - Segments operationId: retrieveSegment description: You can fetch the details of a single segment. responses: '200': description: Successful response content: application/json: examples: Successful response: value: type: segment id: 6762f25f1bb69f9f2193bc26 name: John segment created_at: 1734537823 updated_at: 1734537823 person_type: user schema: "$ref": "#/components/schemas/segment" '404': description: Segment not found content: application/json: examples: Segment not found: value: type: error.list request_id: bd697cc6-7757-488c-a89f-16e6feaf7585 errors: - code: not_found message: Resource Not Found schema: "$ref": "#/components/schemas/error" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: be0d5309-d722-4d2a-aae9-77f4bc0a2cd0 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" "/subscription_types": get: summary: List subscription types parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" tags: - Subscription Types operationId: listSubscriptionTypes description: You can list all subscription types. A list of subscription type objects will be returned. responses: '200': description: Successful content: application/json: examples: Successful: value: type: list data: - type: subscription id: '135' state: live consent_type: opt_out default_translation: name: Newsletters description: Lorem ipsum dolor sit amet locale: en translations: - name: Newsletters description: Lorem ipsum dolor sit amet locale: en content_types: - email schema: "$ref": "#/components/schemas/subscription_type_list" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: 06d15b1f-19b0-42cc-aff9-a9d9db39402b errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" "/phone_call_redirects": post: summary: Create a phone Switch parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" tags: - Switch operationId: createPhoneSwitch description: | You can use the API to deflect phone calls to the Intercom Messenger. Calling this endpoint will send an SMS with a link to the Messenger to the phone number specified. If custom attributes are specified, they will be added to the user or lead's custom data attributes. responses: '200': description: successful content: application/json: examples: successful: value: url: http://via.intercom.io/msgr/1add3dd1-a75e-4a96-96fd-984d16aba059 type: phone_call_redirect schema: "$ref": "#/components/schemas/phone_switch" '400': description: bad request - invalid number content: application/json: examples: bad request - exception sending sms: value: error_key: sms_failed message: SMS was not sent due to an unknown error bad request - invalid number: value: error_key: invalid_phone_number message: Invalid phone number '422': description: unprocessable entity content: application/json: examples: unprocessable entity: value: error_key: some_error '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: e1ed4f34-9477-492a-8ddb-22f10af39734 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" requestBody: content: application/json: schema: "$ref": "#/components/schemas/create_phone_switch_request" examples: successful: summary: successful value: phone: "+353832345678" custom_attributes: issue_type: Billing priority: High bad_request_-_exception_sending_sms: summary: bad request - exception sending sms value: phone: "+353832345678" custom_attributes: issue_type: Billing priority: High bad_request_-_invalid_number: summary: bad request - invalid number value: phone: "+353832345678" custom_attributes: issue_type: Billing priority: High unprocessable_entity: summary: unprocessable entity value: phone: "+40241100100" custom_attributes: issue_type: Billing priority: High "/calls": get: summary: List all calls parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: page in: query required: false description: The page of results to fetch. Defaults to first page example: 1 schema: type: integer - name: per_page in: query required: false description: How many results to display per page. Defaults to 25. Max 25. example: 25 schema: type: integer tags: - Calls operationId: listCalls description: | Retrieve a paginated list of calls. responses: '200': description: successful content: application/json: examples: successful: value: type: list data: [] total_count: 0 pages: type: pages page: 1 per_page: 25 total_pages: 0 schema: "$ref": "#/components/schemas/call_list" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: e097e446-9ae6-44a8-8e13-2bf3008b87ef errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" "/calls/{call_id}": get: summary: Get a call parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: call_id in: path required: true description: The id of the call to retrieve schema: type: string tags: - Calls operationId: showCall description: Retrieve a single call by id. responses: '200': description: successful content: application/json: examples: successful: value: type: call id: "123" conversation_id: "456" admin_id: "789" contact_id: "6762f0dd1bb69f9f2193bb83" state: completed initiated_at: 1734537437 answered_at: 1734537440 ended_at: 1734537530 created_at: 1734537437 updated_at: 1734537531 recording_url: "https://api.intercom.io/calls/123/recording" transcription_url: "https://api.intercom.io/calls/123/transcript" call_type: phone direction: outbound ended_reason: answered phone: "+15551234567" fin_recording_url: "https://api.intercom.io/calls/124/recording" fin_transcription_url: "https://api.intercom.io/calls/124/transcript" schema: "$ref": "#/components/schemas/call" '404': description: Not Found content: application/json: examples: Not Found: value: type: error.list request_id: 9bc4fc62-7cdf-4f72-a56e-02af4836d499 errors: - code: not_found message: Not Found schema: "$ref": "#/components/schemas/error" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: e097e446-9ae6-44a8-8e13-2bf3008b87ef errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" "/calls/{call_id}/recording": get: summary: Get call recording by call id parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: call_id in: path required: true description: The id of the call schema: type: string tags: - Calls operationId: showCallRecording description: Redirects to a signed URL for the call's recording if it exists. responses: '302': description: Redirect to signed recording URL headers: Location: description: The signed recording URL schema: type: string format: uri '404': description: Recording not found content: application/json: examples: Not Found: value: type: error.list request_id: 9bc4fc62-7cdf-4f72-a56e-02af4836d499 errors: - code: not_found message: Recording Not Found schema: "$ref": "#/components/schemas/error" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: e097e446-9ae6-44a8-8e13-2bf3008b87ef errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" "/calls/{call_id}/transcript": get: summary: Get call transcript by call id parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: call_id in: path required: true description: The id of the call schema: type: string tags: - Calls operationId: showCallTranscript description: | Returns the transcript for the specified call as a downloadable text file. responses: '200': description: successful headers: Content-Disposition: description: File attachment directive and suggested filename for the transcript schema: type: string example: "attachment; filename=transcription_data-2025-07-17.txt" content: text/plain: schema: type: string description: Transcript text examples: transcript_txt: value: |- [00:00:03] Teammate 1: "Hello, thanks for calling. How can I help today?" [00:00:09] User: "I need help recovering access to my account." [00:00:15] Teammate 1: "I can help with that. For security, I’ll ask a few generic verification questions." [00:00:22] User: "Okay." [00:00:28] Teammate 1: "Please confirm general details on the account (no sensitive data over this call)." [00:00:35] User: "I can provide non-sensitive info." [00:00:41] Teammate 1: "Thank you. I’ll initiate a standard account recovery process and send the next steps." [00:00:48] User: "Great, thanks." [00:00:53] Teammate 1: "You should receive a message shortly with instructions to complete recovery." '404': description: Not Found content: application/json: examples: Not Found: value: type: error.list request_id: 9bc4fc62-7cdf-4f72-a56e-02af4836d499 errors: - code: not_found message: Not Found schema: "$ref": "#/components/schemas/error" "/calls/search": post: summary: List calls with transcripts parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" tags: - Calls operationId: listCallsWithTranscripts description: | Retrieve calls by a list of conversation ids and include transcripts when available. A maximum of 20 `conversation_ids` can be provided. If none are provided or more than 20 are provided, a 400 error is returned. requestBody: required: true content: application/json: schema: type: object required: - conversation_ids properties: conversation_ids: type: array description: A list of conversation ids to fetch calls for. Maximum 20. minItems: 1 maxItems: 20 items: type: string examples: example: value: conversation_ids: - "64619700005694" - "64619700005695" responses: '200': description: successful content: application/json: examples: successful: value: type: list data: - type: call id: "123" conversation_id: "64619700005694" transcript: - {} transcript_status: completed schema: type: object properties: type: type: string example: list data: type: array items: allOf: - "$ref": "#/components/schemas/call" - type: object properties: transcript: type: array description: The call transcript if available, otherwise an empty array. items: type: object additionalProperties: true transcript_status: type: string nullable: true description: The status of the transcript if available. '400': description: Bad Request content: application/json: examples: too_many_ids: value: type: error.list errors: - code: conversation_id_limit_exceeded message: "A list of up to 20 conversation IDs is required" schema: "$ref": "#/components/schemas/error" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" "/tags": get: summary: List all tags parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" tags: - Tags operationId: listTags description: "You can fetch a list of all tags for a given workspace.\n\n" responses: '200': description: successful content: application/json: examples: successful: value: type: list data: - type: tag id: '102' name: Manual tag 1 schema: "$ref": "#/components/schemas/tag_list" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: 2859da57-c83f-405c-8166-240a312442a3 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" post: summary: Create or update a tag, Tag or untag companies, Tag contacts parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" tags: - Tags operationId: createTag description: | You can use this endpoint to perform the following operations: **1. Create a new tag:** You can create a new tag by passing in the tag name as specified in "Create or Update Tag Request Payload" described below. **2. Update an existing tag:** You can update an existing tag by passing the id of the tag as specified in "Create or Update Tag Request Payload" described below. **3. Tag Companies:** You can tag single company or a list of companies. You can tag a company by passing in the tag name and the company details as specified in "Tag Company Request Payload" described below. Also, if the tag doesn't exist then a new one will be created automatically. **4. Untag Companies:** You can untag a single company or a list of companies. You can untag a company by passing in the tag id and the company details as specified in "Untag Company Request Payload" described below. **5. Tag Multiple Users:** You can tag a list of users. You can tag the users by passing in the tag name and the user details as specified in "Tag Users Request Payload" described below. Each operation will return a tag object. responses: '200': description: Action successful content: application/json: examples: Action successful: value: type: tag id: '105' name: test schema: "$ref": "#/components/schemas/tag_basic" '400': description: Invalid parameters content: application/json: examples: Invalid parameters: value: type: error.list request_id: 33a05108-3bf7-411f-a270-72db40b5a31c errors: - code: parameter_invalid message: invalid tag parameters schema: "$ref": "#/components/schemas/error" '404': description: User not found content: application/json: examples: Company not found: value: type: error.list request_id: 23c998cc-32b8-435d-9653-932c15809460 errors: - code: company_not_found message: Company Not Found User not found: value: type: error.list request_id: 7358f78d-f122-45dd-a2e1-c2261300c38a errors: - code: not_found message: User Not Found schema: "$ref": "#/components/schemas/error" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: f230e3a7-00a9-456b-bf1c-2ad4b7dc49f6 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" requestBody: content: application/json: schema: oneOf: - "$ref": "#/components/schemas/create_or_update_tag_request" - "$ref": "#/components/schemas/tag_company_request" - "$ref": "#/components/schemas/untag_company_request" - "$ref": "#/components/schemas/tag_multiple_users_request" examples: action_successful: summary: Action successful value: name: test invalid_parameters: summary: Invalid parameters value: test: invalid company_not_found: summary: Company not found value: name: test companies: - company_id: '123' user_not_found: summary: User not found value: name: test users: - id: '123' "/tags/{tag_id}": get: summary: Find a specific tag parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: tag_id in: path description: The unique identifier of a given tag example: '123' required: true schema: type: string tags: - Tags operationId: findTag description: | You can fetch the details of tags that are on the workspace by their id. This will return a tag object. responses: '200': description: Tag found content: application/json: examples: Tag found: value: type: tag id: '113' name: Manual tag schema: "$ref": "#/components/schemas/tag_basic" '404': description: Tag not found content: application/json: examples: Tag not found: value: type: error.list request_id: e20c89d2-29c6-4abb-aa3d-c860e1cec1ca errors: - code: not_found message: Resource Not Found schema: "$ref": "#/components/schemas/error" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: c1c0477c-5b80-4874-be65-01ec8a9ffe14 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" delete: summary: Delete tag parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: tag_id in: path description: The unique identifier of a given tag example: '123' required: true schema: type: string tags: - Tags operationId: deleteTag description: You can delete the details of tags that are on the workspace by passing in the id. responses: '200': description: Successful '404': description: Resource not found content: application/json: examples: Resource not found: value: type: error.list request_id: 49536975-bbc5-4a2f-ab8b-7928275cb4d3 errors: - code: not_found message: Resource Not Found schema: "$ref": "#/components/schemas/error" '400': description: Tag has dependent objects content: application/json: examples: Tag has dependent objects: value: type: error.list request_id: 28960d1e-a056-46c0-bf18-a0d798eb889f errors: - code: tag_has_dependent_objects message: 'Unable to delete Tag with dependent objects. Segments: Seg 1.' schema: "$ref": "#/components/schemas/error" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: 90a369be-14bb-48d1-8ed6-6287976f6a64 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" "/teams": get: summary: List all teams parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" tags: - Teams operationId: listTeams description: This will return a list of team objects for the App. responses: '200': description: successful content: application/json: examples: successful: value: type: team.list teams: [] schema: "$ref": "#/components/schemas/team_list" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: a77dadbc-1f1e-4875-bac3-f0d09bbc214a errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" "/teams/{team_id}": get: summary: Retrieve a team parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: team_id in: path required: true description: The unique identifier of a given team. example: '123' schema: type: string tags: - Teams operationId: retrieveTeam description: You can fetch the details of a single team, containing an array of admins that belong to this team. responses: '200': description: successful content: application/json: examples: successful: value: type: team id: '991267902' name: team 1 admin_ids: [] assignment_limit: 10 distribution_method: round_robin schema: "$ref": "#/components/schemas/team" '404': description: Team not found content: application/json: examples: Team not found: value: type: error.list request_id: 3ff156ba-a66e-40d4-93ff-cb6e6afc3c9d errors: - code: team_not_found message: Team not found schema: "$ref": "#/components/schemas/error" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: fc4b741b-b9f1-4ef9-92c7-eb71e9811df3 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" "/ticket_states": get: summary: List all ticket states parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" tags: - Ticket States operationId: listTicketStates description: You can get a list of all ticket states for a workspace. responses: '200': description: successful content: application/json: examples: successful: value: type: list data: - type: ticket_state id: '8269' category: submitted internal_label: Submitted external_label: Submitted ticket_types: type: list data: - type: ticket_type id: '55' name: my-ticket-type-3 description: my ticket type description is awesome. icon: "\U0001F981" archived: false is_internal: false category: Back-office - type: ticket_type id: '56' name: my-ticket-type-4 description: my ticket type description is awesome. icon: "\U0001F981" archived: false is_internal: false category: Back-office - type: ticket_type id: '58' name: my-ticket-type-6 description: my ticket type description is awesome. icon: "\U0001F981" archived: false is_internal: false category: Back-office archived: false - type: ticket_state id: '8270' category: in_progress internal_label: In progress external_label: In progress ticket_types: type: list data: - type: ticket_type id: '55' name: my-ticket-type-3 description: my ticket type description is awesome. icon: "\U0001F981" archived: false is_internal: false category: Back-office - type: ticket_type id: '56' name: my-ticket-type-4 description: my ticket type description is awesome. icon: "\U0001F981" archived: false is_internal: false category: Back-office - type: ticket_type id: '58' name: my-ticket-type-6 description: my ticket type description is awesome. icon: "\U0001F981" archived: false is_internal: false category: Back-office archived: false - type: ticket_state id: '8271' category: waiting_on_customer internal_label: Waiting on customer external_label: Waiting on you ticket_types: type: list data: - type: ticket_type id: '55' name: my-ticket-type-3 description: my ticket type description is awesome. icon: "\U0001F981" archived: false is_internal: false category: Back-office - type: ticket_type id: '56' name: my-ticket-type-4 description: my ticket type description is awesome. icon: "\U0001F981" archived: false is_internal: false category: Back-office - type: ticket_type id: '58' name: my-ticket-type-6 description: my ticket type description is awesome. icon: "\U0001F981" archived: false is_internal: false category: Back-office archived: false - type: ticket_state id: '8272' category: resolved internal_label: Resolved external_label: Resolved ticket_types: type: list data: - type: ticket_type id: '55' name: my-ticket-type-3 description: my ticket type description is awesome. icon: "\U0001F981" archived: false is_internal: false category: Back-office - type: ticket_type id: '56' name: my-ticket-type-4 description: my ticket type description is awesome. icon: "\U0001F981" archived: false is_internal: false category: Back-office - type: ticket_type id: '58' name: my-ticket-type-6 description: my ticket type description is awesome. icon: "\U0001F981" archived: false is_internal: false category: Back-office archived: false - type: ticket_state id: '8273' category: submitted internal_label: Admin label 1 external_label: User label ticket_types: type: list data: - type: ticket_type id: '55' name: my-ticket-type-3 description: my ticket type description is awesome. icon: "\U0001F981" archived: false is_internal: false category: Back-office - type: ticket_type id: '56' name: my-ticket-type-4 description: my ticket type description is awesome. icon: "\U0001F981" archived: false is_internal: false category: Back-office archived: false - type: ticket_state id: '8274' category: submitted internal_label: Admin label 2 external_label: User label ticket_types: type: list data: - type: ticket_type id: '58' name: my-ticket-type-6 description: my ticket type description is awesome. icon: "\U0001F981" archived: false is_internal: false category: Back-office archived: false schema: "$ref": "#/components/schemas/ticket_state_list" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: 5e0bd231-7307-42e6-a6ee-babf05bd163b errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" "/ticket_types/{ticket_type_id}/attributes": post: summary: Create a new attribute for a ticket type parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: ticket_type_id in: path required: true description: The unique identifier for the ticket type which is given by Intercom. schema: type: string tags: - Ticket Type Attributes description: You can create a new attribute for a ticket type. operationId: createTicketTypeAttribute responses: '200': description: Ticket Type Attribute created content: application/json: examples: Ticket Type Attribute created: value: type: ticket_type_attribute id: '157' workspace_id: this_is_an_id640_that_should_be_at_least_ name: Attribute Title description: Attribute Description data_type: string input_options: multiline: false order: 2 required_to_create: false required_to_create_for_contacts: false visible_on_create: true visible_to_contacts: true default: false ticket_type_id: 63 archived: false created_at: 1734537862 updated_at: 1734537862 schema: "$ref": "#/components/schemas/ticket_type_attribute" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: 6c9836ed-8485-4f1d-929d-b9d7e153daed errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" requestBody: content: application/json: schema: "$ref": "#/components/schemas/create_ticket_type_attribute_request" examples: ticket_type_attribute_created: summary: Ticket Type Attribute created value: name: Attribute Title description: Attribute Description data_type: string required_to_create: false "/ticket_types/{ticket_type_id}/attributes/{attribute_id}": put: summary: Update an existing attribute for a ticket type parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: ticket_type_id in: path required: true description: The unique identifier for the ticket type which is given by Intercom. schema: type: string - name: attribute_id in: path required: true description: The unique identifier for the ticket type attribute which is given by Intercom. schema: type: string tags: - Ticket Type Attributes description: You can update an existing attribute for a ticket type. operationId: updateTicketTypeAttribute responses: '200': description: Ticket Type Attribute updated content: application/json: examples: Ticket Type Attribute updated: value: type: ticket_type_attribute id: '162' workspace_id: this_is_an_id644_that_should_be_at_least_ name: name description: New Attribute Description data_type: string order: 0 required_to_create: false required_to_create_for_contacts: false visible_on_create: false visible_to_contacts: false default: false ticket_type_id: 65 archived: false created_at: 1734537864 updated_at: 1734537864 schema: "$ref": "#/components/schemas/ticket_type_attribute" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: cd303186-b33e-4409-8bfc-5814b176d6e1 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" requestBody: content: application/json: schema: "$ref": "#/components/schemas/update_ticket_type_attribute_request" examples: ticket_type_attribute_updated: summary: Ticket Type Attribute updated value: description: New Attribute Description "/ticket_types": get: summary: List all ticket types parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" tags: - Ticket Types operationId: listTicketTypes description: You can get a list of all ticket types for a workspace. responses: '200': description: successful content: application/json: examples: successful: value: type: list data: - type: ticket_type id: '67' name: Bug Report description: Bug Report Template icon: "\U0001F39F️" workspace_id: this_is_an_id648_that_should_be_at_least_ archived: false created_at: 1734537866 updated_at: 1734537866 is_internal: false ticket_type_attributes: type: list data: - type: ticket_type_attribute id: '165' workspace_id: this_is_an_id648_that_should_be_at_least_ name: _default_title_ description: '' data_type: string input_options: multiline: false order: 0 required_to_create: false required_to_create_for_contacts: false visible_on_create: true visible_to_contacts: true default: true ticket_type_id: 67 archived: false created_at: 1734537866 updated_at: 1734537866 - type: ticket_type_attribute id: '167' workspace_id: this_is_an_id648_that_should_be_at_least_ name: name description: description data_type: string input_options: order: 0 required_to_create: false required_to_create_for_contacts: false visible_on_create: false visible_to_contacts: false default: false ticket_type_id: 67 archived: false created_at: 1734537866 updated_at: 1734537866 - type: ticket_type_attribute id: '166' workspace_id: this_is_an_id648_that_should_be_at_least_ name: _default_description_ description: '' data_type: string input_options: multiline: true order: 1 required_to_create: false required_to_create_for_contacts: false visible_on_create: true visible_to_contacts: true default: true ticket_type_id: 67 archived: false created_at: 1734537866 updated_at: 1734537866 category: Customer ticket_states: type: list data: - type: ticket_state id: '8321' category: submitted internal_label: Submitted external_label: Submitted - type: ticket_state id: '8322' category: in_progress internal_label: In progress external_label: In progress - type: ticket_state id: '8323' category: waiting_on_customer internal_label: Waiting on customer external_label: Waiting on you - type: ticket_state id: '8324' category: resolved internal_label: Resolved external_label: Resolved schema: "$ref": "#/components/schemas/ticket_type_list" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: a63507c2-3b3b-4a1a-aafa-f08b87eb2c12 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" post: summary: Create a ticket type parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" tags: - Ticket Types operationId: createTicketType description: "You can create a new ticket type.\n> \U0001F4D8 Creating ticket types.\n>\n> Every ticket type will be created with two default attributes: _default_title_ and _default_description_.\n> For the `icon` propery, use an emoji from [Twemoji Cheatsheet](https://twemoji-cheatsheet.vercel.app/)\n" responses: '200': description: Ticket type created content: application/json: examples: Ticket type created: value: type: ticket_type id: '70' name: Customer Issue description: Customer Report Template icon: "\U0001F39F️" workspace_id: this_is_an_id652_that_should_be_at_least_ archived: false created_at: 1734537869 updated_at: 1734537869 is_internal: false ticket_type_attributes: type: list data: - type: ticket_type_attribute id: '174' workspace_id: this_is_an_id652_that_should_be_at_least_ name: _default_title_ description: '' data_type: string input_options: multiline: false order: 0 required_to_create: false required_to_create_for_contacts: false visible_on_create: true visible_to_contacts: true default: true ticket_type_id: 70 archived: false created_at: 1734537869 updated_at: 1734537869 - type: ticket_type_attribute id: '175' workspace_id: this_is_an_id652_that_should_be_at_least_ name: _default_description_ description: '' data_type: string input_options: multiline: true order: 1 required_to_create: false required_to_create_for_contacts: false visible_on_create: true visible_to_contacts: true default: true ticket_type_id: 70 archived: false created_at: 1734537869 updated_at: 1734537869 category: Customer ticket_states: type: list data: - type: ticket_state id: '8337' category: submitted internal_label: Submitted external_label: Submitted - type: ticket_state id: '8338' category: in_progress internal_label: In progress external_label: In progress - type: ticket_state id: '8339' category: waiting_on_customer internal_label: Waiting on customer external_label: Waiting on you - type: ticket_state id: '8340' category: resolved internal_label: Resolved external_label: Resolved schema: "$ref": "#/components/schemas/ticket_type" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: 36b79d0c-b78f-4e1d-bd6d-bfc3dcc71f53 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" requestBody: content: application/json: schema: "$ref": "#/components/schemas/create_ticket_type_request" examples: ticket_type_created: summary: Ticket type created value: name: Customer Issue description: Customer Report Template icon: "\U0001F39F️" category: Customer "/ticket_types/{ticket_type_id}": get: summary: Retrieve a ticket type parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: ticket_type_id in: path required: true description: The unique identifier for the ticket type which is given by Intercom. schema: type: string tags: - Ticket Types operationId: getTicketType description: You can fetch the details of a single ticket type. responses: '200': description: Ticket type found content: application/json: examples: Ticket type found: value: type: ticket_type id: '72' name: Bug Report description: Bug Report Template icon: "\U0001F39F️" workspace_id: this_is_an_id656_that_should_be_at_least_ archived: false created_at: 1734537870 updated_at: 1734537870 is_internal: false ticket_type_attributes: type: list data: - type: ticket_type_attribute id: '179' workspace_id: this_is_an_id656_that_should_be_at_least_ name: _default_title_ description: '' data_type: string input_options: multiline: false order: 0 required_to_create: false required_to_create_for_contacts: false visible_on_create: true visible_to_contacts: true default: true ticket_type_id: 72 archived: false created_at: 1734537871 updated_at: 1734537871 - type: ticket_type_attribute id: '181' workspace_id: this_is_an_id656_that_should_be_at_least_ name: name description: description data_type: string input_options: order: 0 required_to_create: false required_to_create_for_contacts: false visible_on_create: false visible_to_contacts: false default: false ticket_type_id: 72 archived: false created_at: 1734537871 updated_at: 1734537871 - type: ticket_type_attribute id: '180' workspace_id: this_is_an_id656_that_should_be_at_least_ name: _default_description_ description: '' data_type: string input_options: multiline: true order: 1 required_to_create: false required_to_create_for_contacts: false visible_on_create: true visible_to_contacts: true default: true ticket_type_id: 72 archived: false created_at: 1734537871 updated_at: 1734537871 category: Customer ticket_states: type: list data: - type: ticket_state id: '8353' category: submitted internal_label: Submitted external_label: Submitted - type: ticket_state id: '8354' category: in_progress internal_label: In progress external_label: In progress - type: ticket_state id: '8355' category: waiting_on_customer internal_label: Waiting on customer external_label: Waiting on you - type: ticket_state id: '8356' category: resolved internal_label: Resolved external_label: Resolved schema: "$ref": "#/components/schemas/ticket_type" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: c9a2c3da-7536-4eba-bde7-c38c2d9e2942 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" put: summary: Update a ticket type parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: ticket_type_id in: path required: true description: The unique identifier for the ticket type which is given by Intercom. schema: type: string tags: - Ticket Types operationId: updateTicketType description: "\nYou can update a ticket type.\n\n> \U0001F4D8 Updating a ticket type.\n>\n> For the `icon` propery, use an emoji from [Twemoji Cheatsheet](https://twemoji-cheatsheet.vercel.app/)\n" responses: '200': description: Ticket type updated content: application/json: examples: Ticket type updated: value: type: ticket_type id: '74' name: Bug Report 2 description: Bug Report Template icon: "\U0001F39F️" workspace_id: this_is_an_id660_that_should_be_at_least_ archived: false created_at: 1734537873 updated_at: 1734537874 is_internal: false ticket_type_attributes: type: list data: - type: ticket_type_attribute id: '185' workspace_id: this_is_an_id660_that_should_be_at_least_ name: _default_title_ description: '' data_type: string input_options: multiline: false order: 0 required_to_create: false required_to_create_for_contacts: false visible_on_create: true visible_to_contacts: true default: true ticket_type_id: 74 archived: false created_at: 1734537873 updated_at: 1734537873 - type: ticket_type_attribute id: '187' workspace_id: this_is_an_id660_that_should_be_at_least_ name: name description: description data_type: string input_options: order: 0 required_to_create: false required_to_create_for_contacts: false visible_on_create: false visible_to_contacts: false default: false ticket_type_id: 74 archived: false created_at: 1734537873 updated_at: 1734537873 - type: ticket_type_attribute id: '186' workspace_id: this_is_an_id660_that_should_be_at_least_ name: _default_description_ description: '' data_type: string input_options: multiline: true order: 1 required_to_create: false required_to_create_for_contacts: false visible_on_create: true visible_to_contacts: true default: true ticket_type_id: 74 archived: false created_at: 1734537873 updated_at: 1734537873 category: Customer ticket_states: type: list data: - type: ticket_state id: '8369' category: submitted internal_label: Submitted external_label: Submitted - type: ticket_state id: '8370' category: in_progress internal_label: In progress external_label: In progress - type: ticket_state id: '8371' category: waiting_on_customer internal_label: Waiting on customer external_label: Waiting on you - type: ticket_state id: '8372' category: resolved internal_label: Resolved external_label: Resolved schema: "$ref": "#/components/schemas/ticket_type" '401': description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: 2fc2ae95-64ec-4581-80f0-79ecfdc2e759 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" requestBody: content: application/json: schema: "$ref": "#/components/schemas/update_ticket_type_request" examples: ticket_type_updated: summary: Ticket type updated value: name: Bug Report 2 "/tickets/{ticket_id}/reply": post: summary: Reply to a ticket operationId: replyTicket description: You can reply to a ticket with a message from an admin or on behalf of a contact, or with a note for admins. parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - name: ticket_id in: path required: true schema: title: Ticket ID type: string description: | The id of the ticket to target. {% admonition type="info" name="Not the Inbox ticket ID" %} This is the internal `id` field from the API response, not the `ticket_id` displayed in the Intercom Inbox (e.g., #12345). Use the `id` value from the ticket object returned by the API. {% /admonition %} example: '123' tags: - Tickets responses: '400': description: User reply content: application/json: examples: User reply: value: type: error.list request_id: 603ce1da-f2bf-4641-a1ee-d1f13ebf9172 errors: - code: parameter_mismatch message: User replies are not allowed on Backoffice tickets schema: "$ref": "#/components/schemas/error" '200': description: Admin Reply to send Quick Reply Options content: application/json: examples: Admin note reply: value: type: ticket_part id: '156' part_type: note body: |-Text for the note.
" company_list: title: Companies type: object description: This will return a list of companies for the App. properties: type: type: string description: The type of object - `list`. enum: - list example: list pages: "$ref": "#/components/schemas/cursor_pages" total_count: type: integer description: The total number of companies. example: 100 data: type: array description: An array containing Company Objects. items: "$ref": "#/components/schemas/company" company_scroll: title: Company Scroll type: object description: 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. nullable: true properties: type: type: string description: The type of object - `list` enum: - list example: list data: type: array items: "$ref": "#/components/schemas/company" pages: "$ref": "#/components/schemas/cursor_pages" total_count: type: integer description: The total number of companies nullable: true example: 100 scroll_param: type: string description: The scroll parameter to use in the next request to fetch the next page of results. example: 25b649f7-4d33-4ef6-88f5-60e5b8244309 contact: title: Contact type: object x-tags: - Contacts x-fern-sdk-group-name: contacts description: Contacts represent your leads and users in Intercom. properties: type: type: string description: The type of object. example: contact id: type: string description: The unique identifier for the contact which is given by Intercom. example: 5ba682d23d7cf92bef87bfd4 external_id: type: string nullable: true description: The unique identifier for the contact which is provided by the Client. example: f3b87a2e09d514c6c2e79b9a workspace_id: type: string description: The id of the workspace which the contact belongs to. example: ecahpwf5 role: type: string description: The role of the contact. example: user email: type: string description: The contact's email. example: joe@example.com email_domain: type: string description: The contact's email domain. example: example.com phone: type: string nullable: true description: The contacts phone. example: "+1123456789" name: type: string nullable: true description: The contacts name. example: John Doe owner_id: type: integer nullable: true description: The id of an admin that has been assigned account ownership of the contact. example: 123 has_hard_bounced: type: boolean description: Whether the contact has had an email sent to them hard bounce. example: true marked_email_as_spam: type: boolean description: Whether the contact has marked an email sent to them as spam. example: true unsubscribed_from_emails: type: boolean description: Whether the contact is unsubscribed from emails. example: true created_at: type: integer format: date-time description: "(UNIX timestamp) The time when the contact was created." example: 1571672154 updated_at: type: integer format: date-time description: "(UNIX timestamp) The time when the contact was last updated." example: 1571672154 signed_up_at: type: integer format: date-time nullable: true description: "(UNIX timestamp) The time specified for when a contact signed up." example: 1571672154 last_seen_at: type: integer format: date-time nullable: true description: "(UNIX timestamp) The time when the contact was last seen (either where the Intercom Messenger was installed or when specified manually)." example: 1571672154 last_replied_at: type: integer format: date-time nullable: true description: "(UNIX timestamp) The time when the contact last messaged in." example: 1571672154 last_contacted_at: type: integer format: date-time nullable: true description: "(UNIX timestamp) The time when the contact was last messaged." example: 1571672154 last_email_opened_at: type: integer format: date-time nullable: true description: "(UNIX timestamp) The time when the contact last opened an email." example: 1571672154 last_email_clicked_at: type: integer format: date-time nullable: true description: "(UNIX timestamp) The time when the contact last clicked a link in an email." example: 1571672154 language_override: type: string nullable: true description: A preferred language setting for the contact, used by the Intercom Messenger even if their browser settings change. example: en browser: type: string nullable: true description: The name of the browser which the contact is using. example: Chrome browser_version: type: string nullable: true description: The version of the browser which the contact is using. example: 80.0.3987.132 browser_language: type: string nullable: true description: The language set by the browser which the contact is using. example: en-US os: type: string nullable: true description: The operating system which the contact is using. example: Mac OS X android_app_name: type: string nullable: true description: The name of the Android app which the contact is using. example: Intercom android_app_version: type: string nullable: true description: The version of the Android app which the contact is using. example: 5.0.0 android_device: type: string nullable: true description: The Android device which the contact is using. example: Pixel 3 android_os_version: type: string nullable: true description: The version of the Android OS which the contact is using. example: '10' android_sdk_version: type: string nullable: true description: The version of the Android SDK which the contact is using. example: '28' android_last_seen_at: type: integer nullable: true format: date-time description: "(UNIX timestamp) The time when the contact was last seen on an Android device." example: 1571672154 ios_app_name: type: string nullable: true description: The name of the iOS app which the contact is using. example: Intercom ios_app_version: type: string nullable: true description: The version of the iOS app which the contact is using. example: 5.0.0 ios_device: type: string nullable: true description: The iOS device which the contact is using. example: iPhone 11 ios_os_version: type: string nullable: true description: The version of iOS which the contact is using. example: 13.3.1 ios_sdk_version: type: string nullable: true description: The version of the iOS SDK which the contact is using. example: 13.3.1 ios_last_seen_at: type: integer nullable: true format: date-time description: "(UNIX timestamp) The last time the contact used the iOS app." example: 1571672154 custom_attributes: type: object description: The custom attributes which are set for the contact. avatar: type: object nullable: true properties: type: type: string description: The type of object example: avatar image_url: type: string format: uri nullable: true description: An image URL containing the avatar of a contact. example: https://example.org/128Wash.jpg tags: "$ref": "#/components/schemas/contact_tags" notes: "$ref": "#/components/schemas/contact_notes" companies: "$ref": "#/components/schemas/contact_companies" location: "$ref": "#/components/schemas/contact_location" social_profiles: "$ref": "#/components/schemas/contact_social_profiles" contact_attached_companies: title: Contact Attached Companies type: object description: A list of Company Objects properties: type: type: string description: The type of object enum: - list example: list companies: type: array description: An array containing Company Objects items: "$ref": "#/components/schemas/company" total_count: type: integer description: The total number of companies associated to this contact example: 100 pages: "$ref": "#/components/schemas/pages_link" contact_companies: title: Contact companies type: object nullable: false description: An object with metadata about companies attached to a contact . Up to 10 will be displayed here. Use the url to get more. properties: data: type: array description: An array of company data objects attached to the contact. items: "$ref": "#/components/schemas/company_data" url: type: string format: uri description: Url to get more company resources for this contact example: "/contacts/5ba682d23d7cf92bef87bfd4/companies" total_count: type: integer description: Integer representing the total number of companies attached to this contact example: 100 has_more: type: boolean description: Whether there's more Addressable Objects to be viewed. If true, use the url to view all example: true company_data: title: Company Data type: object description: An object containing data about the companies that a contact is associated with. properties: id: type: string description: The unique identifier for the company which is given by Intercom. example: 5ba682d23d7cf92bef87bfd4 type: type: string description: The type of the object. Always company. enum: - company example: company url: type: string format: uri description: The relative URL of the company. example: "/companies/5ba682d23d7cf92bef87bfd4" contact_deleted: title: Contact Deleted description: deleted contact object allOf: - "$ref": "#/components/schemas/contact_reference" properties: deleted: type: boolean description: Whether the contact is deleted or not. example: true contact_list: title: Contact List type: object description: Contacts are your users in Intercom. properties: type: type: string description: Always list enum: - list example: list data: type: array description: The list of contact objects items: "$ref": "#/components/schemas/contact" total_count: type: integer description: A count of the total number of objects. example: 100 pages: "$ref": "#/components/schemas/cursor_pages" contact_location: title: Contact Location type: object nullable: false description: An object containing location meta data about a Intercom contact. properties: type: type: string nullable: true description: Always location example: location country: type: string nullable: true description: The country that the contact is located in example: Ireland region: type: string nullable: true description: The overal region that the contact is located in example: Dublin city: type: string nullable: true description: The city that the contact is located in example: Dublin contact_notes: title: Contact notes type: object nullable: false description: 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. properties: data: type: array description: This object represents the notes attached to a contact. items: "$ref": "#/components/schemas/addressable_list" url: type: string format: uri description: Url to get more company resources for this contact example: "/contacts/5ba682d23d7cf92bef87bfd4/notes" total_count: type: integer description: Int representing the total number of companyies attached to this contact example: 100 has_more: type: boolean description: Whether there's more Addressable Objects to be viewed. If true, use the url to view all example: true contact_reference: title: Contact Reference type: object description: reference to contact object properties: type: type: string description: always contact enum: - contact example: contact id: type: string description: The unique identifier for the contact which is given by Intercom. example: 5ba682d23d7cf92bef87bfd4 external_id: type: string nullable: true description: The unique identifier for the contact which is provided by the Client. example: "70" contact_reply_base_request: title: Contact Reply Base Object type: object properties: message_type: type: string enum: - comment type: type: string enum: - user body: type: string description: The text body of the comment. created_at: type: integer description: The time the reply was created. If not provided, the current time will be used. example: 1590000000 attachment_urls: title: Attachment URLs type: array description: A list of image URLs that will be added as attachments. You can include up to 10 URLs. items: type: string format: uri maxItems: 10 reply_options: title: Contact Quick Reply type: array description: The quick reply selection the contact wishes to respond with. These map to buttons displayed in the Messenger UI if sent by a bot, or the reply options sent by an Admin via the API. items: title: Quick Reply Option type: object properties: text: type: string description: The text of the chosen reply option. uuid: type: string format: uuid description: The unique identifier for the quick reply option selected. required: - text - uuid required: - message_type - type - body contact_reply_conversation_request: title: Contact Reply oneOf: - "$ref": "#/components/schemas/contact_reply_intercom_user_id_request" - "$ref": "#/components/schemas/contact_reply_email_request" - "$ref": "#/components/schemas/contact_reply_user_id_request" contact_reply_email_request: title: Email type: object description: Payload of the request to reply on behalf of a contact using their `email` properties: email: type: string description: The email you have defined for the user. attachment_files: type: array description: A list of files that will be added as attachments. items: "$ref": "#/components/schemas/conversation_attachment_files" allOf: - "$ref": "#/components/schemas/contact_reply_base_request" required: - email contact_reply_intercom_user_id_request: title: Intercom User ID type: object description: Payload of the request to reply on behalf of a contact using their `intercom_user_id` allOf: - "$ref": "#/components/schemas/contact_reply_base_request" properties: intercom_user_id: type: string description: The identifier for the contact as given by Intercom. attachment_files: type: array description: A list of files that will be added as attachments. items: "$ref": "#/components/schemas/conversation_attachment_files" required: - intercom_user_id contact_reply_ticket_email_request: title: Email type: object description: Payload of the request to reply on behalf of a contact using their `email` properties: email: type: string description: The email you have defined for the user. allOf: - "$ref": "#/components/schemas/contact_reply_base_request" required: - email contact_reply_ticket_intercom_user_id_request: title: Intercom User ID type: object description: Payload of the request to reply on behalf of a contact using their `intercom_user_id` allOf: - "$ref": "#/components/schemas/contact_reply_base_request" properties: intercom_user_id: type: string description: The identifier for the contact as given by Intercom. required: - intercom_user_id contact_reply_ticket_request: title: Contact Reply on ticket oneOf: - "$ref": "#/components/schemas/contact_reply_ticket_intercom_user_id_request" - "$ref": "#/components/schemas/contact_reply_ticket_user_id_request" - "$ref": "#/components/schemas/contact_reply_ticket_email_request" contact_reply_ticket_user_id_request: title: User ID type: object description: Payload of the request to reply on behalf of a contact using their `user_id` allOf: - "$ref": "#/components/schemas/contact_reply_base_request" properties: user_id: type: string description: The external_id you have defined for the contact. required: - user_id contact_reply_user_id_request: title: User ID type: object description: Payload of the request to reply on behalf of a contact using their `user_id` allOf: - "$ref": "#/components/schemas/contact_reply_base_request" properties: user_id: type: string description: The external_id you have defined for the contact. attachment_files: type: array description: A list of files that will be added as attachments. You can include up to 10 files. items: "$ref": "#/components/schemas/conversation_attachment_files" maxItems: 10 required: - user_id contact_segments: title: Segments type: object description: A list of segments objects attached to a specific contact. properties: type: type: string description: The type of the object enum: - list example: list data: type: array description: Segment objects associated with the contact. items: "$ref": "#/components/schemas/segment" contact_social_profiles: title: Social Profile type: object nullable: false description: An object containing social profiles that a contact has. properties: data: type: array description: A list of social profiles objects associated with the contact. items: "$ref": "#/components/schemas/social_profile" contact_subscription_types: title: Contact Subscription Types type: object nullable: false description: An object containing Subscription Types meta data about the SubscriptionTypes that a contact has. properties: data: type: array description: This object represents the subscriptions attached to a contact. items: "$ref": "#/components/schemas/addressable_list" url: type: string format: uri description: Url to get more subscription type resources for this contact example: "/contacts/5ba682d23d7cf92bef87bfd4/subscriptions" total_count: type: integer description: Int representing the total number of subscription types attached to this contact example: 100 has_more: type: boolean description: Whether there's more Addressable Objects to be viewed. If true, use the url to view all example: true contact_tags: title: Contact Tags type: object nullable: true description: 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. properties: data: type: array description: This object represents the tags attached to a contact. items: "$ref": "#/components/schemas/addressable_list" url: type: string format: uri description: url to get more tag resources for this contact example: "/contacts/5ba682d23d7cf92bef87bfd4/tags" total_count: type: integer description: Int representing the total number of tags attached to this contact example: 100 has_more: type: boolean description: Whether there's more Addressable Objects to be viewed. If true, use the url to view all example: true contact_archived: title: Contact Archived description: archived contact object allOf: - "$ref": "#/components/schemas/contact_reference" properties: archived: type: boolean description: Whether the contact is archived or not. example: true contact_unarchived: title: Contact Unarchived description: unarchived contact object allOf: - "$ref": "#/components/schemas/contact_reference" properties: archived: type: boolean description: Whether the contact is archived or not. example: false contact_blocked: title: Contact Blocked type: object description: blocked contact object allOf: - "$ref": "#/components/schemas/contact_reference" properties: blocked: type: boolean description: Always true. example: true content_import_source: title: Content Import Source type: object x-tags: - AI Content description: An external source for External Pages that you add to your Fin Content Library. nullable: false properties: type: type: string description: Always external_page enum: - content_import_source default: content_import_source example: content_import_source id: type: integer description: The unique identifier for the content import source which is given by Intercom. example: 1234 last_synced_at: type: integer format: date-time description: The time when the content import source was last synced. example: 1672928610 sync_behavior: type: string description: If you intend to create or update External Pages via the API, this should be set to `api`. enum: - api - automatic - manual example: api status: type: string description: The status of the content import source. enum: - active - deactivated default: active example: active url: type: string description: The URL of the root of the external source. example: https://help.example.com/ created_at: type: integer format: date-time description: The time when the content import source was created. example: 1672928359 updated_at: type: integer format: date-time description: The time when the content import source was last updated. example: 1672928610 required: - id - type - url - sync_behavior - status - created_at - updated_at - last_synced_at content_import_sources_list: title: Content Import Sources type: object x-tags: - AI Content description: This will return a list of the content import sources for the App. nullable: false properties: type: type: string description: The type of the object - `list`. enum: - list example: list pages: "$ref": "#/components/schemas/pages_link" total_count: type: integer description: A count of the total number of content import sources. example: 1 data: type: array description: An array of Content Import Source objects items: "$ref": "#/components/schemas/content_import_source" content_source: title: Content Source type: object x-tags: - AI Content Source description: The content source used by AI Agent in the conversation. properties: content_type: type: string description: The type of the content source. example: content_snippet enum: - file - article - external_content - content_snippet - workflow_connector_action url: type: string description: The internal URL linking to the content source for teammates. example: "/fin-ai-agent/content?content=content_snippet&id=3234924" title: type: string description: The title of the content source. example: My internal content snippet locale: type: string description: The ISO 639 language code of the content source. example: en content_sources_list: title: Content Source List nullable: false properties: type: type: string enum: - content_source.list example: content_source.list total_count: type: integer description: The total number of content sources used by AI Agent in the conversation. example: 1 content_sources: type: array description: The content sources used by AI Agent in the conversation. items: "$ref": "#/components/schemas/content_source" conversation: title: Conversation type: object x-tags: - Conversations description: 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. properties: type: type: string description: Always conversation. example: conversation id: type: string description: The id representing the conversation. example: '1295' title: type: string nullable: true description: The title given to the conversation. example: Conversation Title created_at: type: integer format: date-time description: The time the conversation was created. example: 1663597223 updated_at: type: integer format: date-time description: The last time the conversation was updated. example: 1663597260 waiting_since: type: integer format: date-time nullable: true description: The last time a Contact responded to an Admin. In other words, the time a customer started waiting for a response. Set to null if last reply is from an Admin. example: 1663597260 snoozed_until: type: integer format: date-time nullable: true description: If set this is the time in the future when this conversation will be marked as open. i.e. it will be in a snoozed state until this time. i.e. it will be in a snoozed state until this time. example: 1663597260 open: type: boolean description: Indicates whether a conversation is open (true) or closed (false). example: true state: type: string enum: - open - closed - snoozed description: Can be set to "open", "closed" or "snoozed". example: open read: type: boolean description: Indicates whether a conversation has been read. example: true priority: type: string enum: - priority - not_priority description: If marked as priority, it will return priority or else not_priority. example: priority admin_assignee_id: type: integer nullable: true description: The id of the admin assigned to the conversation. If it's not assigned to an admin it will return null. example: 0 team_assignee_id: type: string nullable: true description: The id of the team assigned to the conversation. If it's not assigned to a team it will return null. example: '5017691' company: "$ref": "#/components/schemas/company" nullable: true description: The company associated with the conversation. tags: "$ref": "#/components/schemas/tags" conversation_rating: "$ref": "#/components/schemas/conversation_rating" source: "$ref": "#/components/schemas/conversation_source" contacts: "$ref": "#/components/schemas/conversation_contacts" teammates: "$ref": "#/components/schemas/conversation_teammates" custom_attributes: "$ref": "#/components/schemas/custom_attributes" first_contact_reply: "$ref": "#/components/schemas/conversation_first_contact_reply" sla_applied: "$ref": "#/components/schemas/sla_applied" statistics: "$ref": "#/components/schemas/conversation_statistics" conversation_parts: "$ref": "#/components/schemas/conversation_parts" linked_objects: "$ref": "#/components/schemas/linked_object_list" ai_agent_participated: type: boolean description: Indicates whether the AI Agent participated in the conversation. example: true ai_agent: "$ref": "#/components/schemas/ai_agent" nullable: true conversation_attachment_files: title: Conversation attachment files type: object description: Properties of the attachment files in a conversation part properties: content_type: type: string description: The content type of the file example: application/json data: type: string description: The base64 encoded file data. example: ewogICJ0ZXN0IjogMQp9 name: type: string description: The name of the file. example: test.json conversation_contacts: title: Contacts type: object description: 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. properties: type: type: string description: '' enum: - contact.list example: contact.list contacts: type: array description: 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. items: "$ref": "#/components/schemas/contact_reference" conversation_deleted: title: Conversation Deleted type: object description: deleted conversation object properties: id: type: string description: The unique identifier for the conversation. example: 5ba682d23d7cf92bef87bfd4 object: type: string description: always conversation enum: - conversation example: conversation deleted: type: boolean description: Whether the conversation is deleted or not. example: true conversation_first_contact_reply: title: First contact reply type: object nullable: true description: An object containing information on the first users message. For a contact initiated message this will represent the users original message. properties: created_at: type: integer format: date-time description: '' example: 1663597223 type: type: string description: '' example: conversation url: type: string nullable: true description: '' example: https://developers.intercom.com/ conversation_list: title: Conversation List type: object description: 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. properties: type: type: string description: Always conversation.list enum: - conversation.list example: conversation.list conversations: type: array description: The list of conversation objects items: "$ref": "#/components/schemas/conversation" total_count: type: integer description: A count of the total number of objects. example: 12345 pages: "$ref": "#/components/schemas/cursor_pages" conversation_part: title: Conversation Part type: object description: A Conversation Part represents a message in the conversation. properties: type: type: string description: Always conversation_part example: conversation_part id: type: string description: The id representing the conversation part. example: '3' part_type: type: string description: The type of conversation part. example: comment body: type: string nullable: true description: The message body, which may contain HTML. For Twitter, this will show a generic message regarding why the body is obscured. In webhook payloads for API version 2.15+, this field returns plain text. example: "Okay!
" created_at: type: integer format: date-time description: The time the conversation part was created. example: 1663597223 updated_at: type: integer format: date-time description: The last time the conversation part was updated. example: 1663597260 notified_at: type: integer format: date-time description: The time the user was notified with the conversation part. example: 1663597260 assigned_to: "$ref": "#/components/schemas/reference" nullable: true description: The id of the admin that was assigned the conversation by this conversation_part (null if there has been no change in assignment.) author: "$ref": "#/components/schemas/conversation_part_author" attachments: title: Conversation part attachments type: array description: A list of attachments for the part. items: "$ref": "#/components/schemas/part_attachment" external_id: type: string nullable: true description: The external id of the conversation part example: abcd1234 redacted: type: boolean description: Whether or not the conversation part has been redacted. example: false email_message_metadata: "$ref": "#/components/schemas/email_message_metadata" nullable: true metadata: "$ref": "#/components/schemas/conversation_part_metadata" nullable: true state: type: string enum: - open - closed - snoozed description: Indicates the current state of conversation when the conversation part was created. example: open tags: type: array description: A list of tags objects associated with the conversation part. items: "$ref": "#/components/schemas/tag_basic" nullable: true event_details: "$ref": "#/components/schemas/event_details" nullable: true app_package_code: type: string nullable: true example: "test-integration" description: The app package code if this part was created via API. null if the part was not created via API. conversation_part_author: title: Conversation part author type: object description: 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. properties: type: type: string description: The type of the author example: admin id: type: string description: The id of the author example: '274' name: type: string nullable: true description: The name of the author example: Operator email: type: string format: email description: The email of the author example: operator+abcd1234@intercom.io from_ai_agent: type: boolean description: If this conversation part was sent by the AI Agent example: true is_ai_answer: type: boolean description: If this conversation part body was generated by the AI Agent example: false conversation_parts: title: Conversation Parts type: object description: 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. properties: type: type: string description: '' enum: - conversation_part.list example: conversation_part.list conversation_parts: title: Conversation Parts type: array description: 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. items: "$ref": "#/components/schemas/conversation_part" total_count: type: integer description: '' example: 1 conversation_part_metadata: title: Conversation Part Metadata description: Metadata for a conversation part type: object properties: quick_reply_options: type: array description: The quick reply options sent by the Admin or bot, presented in this conversation part. items: allOf: - "$ref": "#/components/schemas/quick_reply_option" properties: translations: type: object nullable: true description: The translations for the quick reply option. example: { "en": "Hello", "fr": "Bonjour" } quick_reply_uuid: type: string format: uuid description: The unique identifier for the quick reply option that was clicked by the end user. example: '123e4567-e89b-12d3-a456-426614174000' conversation_rating: title: Conversation Rating type: object nullable: true description: The Conversation Rating object which contains information on the rating and/or remark added by a Contact and the Admin assigned to the conversation. properties: rating: type: integer description: The rating, between 1 and 5, for the conversation. example: 5 remark: type: string description: An optional field to add a remark to correspond to the number rating example: '' created_at: type: integer format: date-time description: The time the rating was requested in the conversation being rated. example: 1671028894 updated_at: type: integer format: date-time description: The time the rating was last updated. example: 1671028894 contact: "$ref": "#/components/schemas/contact_reference" teammate: "$ref": "#/components/schemas/reference" conversation_response_time: title: Conversation response time type: object description: Details of first response time of assigned team in seconds. properties: team_id: type: integer description: Id of the assigned team. example: 100 team_name: type: string description: Name of the assigned Team, null if team does not exist, Unassigned if no team is assigned. example: Team One response_time: type: integer description: First response time of assigned team in seconds. example: 2310 conversation_source: title: Conversation source type: object description: The type of the conversation part that started this conversation. Can be Contact, Admin, Campaign, Automated or Operator initiated. properties: type: type: string description: This includes conversation, email, facebook, instagram, phone_call, phone_switch, push, sms, twitter and whatsapp. example: conversation enum: - conversation - email - facebook - instagram - phone_call - phone_switch - push - sms - twitter - whatsapp id: type: string description: The id representing the message. example: '3' delivered_as: type: string description: 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 subject: type: string description: Optional. The message subject. For Twitter, this will show a generic message regarding why the subject is obscured. In webhook payloads for API version 2.15+, this field returns plain text. example: '' body: type: string description: The message body, which may contain HTML. For Twitter, this will show a generic message regarding why the body is obscured. In webhook payloads for API version 2.15+, this field returns plain text. example: "Hey there!
" author: "$ref": "#/components/schemas/conversation_part_author" attachments: type: array description: A list of attachments for the part. items: "$ref": "#/components/schemas/part_attachment" url: type: string nullable: true description: The URL where the conversation was started. For Twitter, Email, and Bots, this will be blank. example: redacted: type: boolean description: Whether or not the source message has been redacted. Only applicable for contact initiated messages. example: false conversation_statistics: title: Conversation statistics type: object nullable: true description: A Statistics object containing all information required for reporting, with timestamps and calculated metrics. properties: type: type: string description: '' example: conversation_statistics time_to_assignment: type: integer description: Duration until last assignment before first admin reply. In seconds. example: 2310 time_to_admin_reply: type: integer description: Duration until first admin reply. Subtracts out of business hours. In seconds. example: 2310 time_to_first_close: type: integer description: Duration until conversation was closed first time. Subtracts out of business hours. In seconds. example: 2310 time_to_last_close: type: integer description: Duration until conversation was closed last time. Subtracts out of business hours. In seconds. example: 2310 median_time_to_reply: type: integer description: Median based on all admin replies after a contact reply. Subtracts out of business hours. In seconds. example: 2310 first_contact_reply_at: type: integer format: date-time description: Time of first text conversation part from a contact. example: 1663597233 first_assignment_at: type: integer format: date-time description: Time of first assignment after first_contact_reply_at. example: 1663597233 first_admin_reply_at: type: integer format: date-time description: Time of first admin reply after first_contact_reply_at. example: 1663597233 first_close_at: type: integer format: date-time description: Time of first close after first_contact_reply_at. example: 1663597233 last_assignment_at: type: integer format: date-time description: Time of last assignment after first_contact_reply_at. example: 1663597233 last_assignment_admin_reply_at: type: integer format: date-time description: Time of first admin reply since most recent assignment. example: 1663597233 last_contact_reply_at: type: integer format: date-time description: Time of the last conversation part from a contact. example: 1663597233 last_admin_reply_at: type: integer format: date-time description: Time of the last conversation part from an admin. example: 1663597233 last_close_at: type: integer format: date-time description: Time of the last conversation close. example: 1663597233 last_closed_by_id: type: string description: The last admin who closed the conversation. Returns a reference to an Admin object. example: c3po count_reopens: type: integer description: Number of reopens after first_contact_reply_at. example: 1 count_assignments: type: integer description: Number of assignments after first_contact_reply_at. example: 1 count_conversation_parts: type: integer description: Total number of conversation parts. example: 1 assigned_team_first_response_time_by_team: type: array description: An array of conversation response time objects items: "$ref": "#/components/schemas/conversation_response_time" assigned_team_first_response_time_in_office_hours: type: array description: An array of conversation response time objects within office hours items: "$ref": "#/components/schemas/conversation_response_time" handling_time: type: integer description: Time from conversation assignment to conversation close in seconds. example: 2310 adjusted_handling_time: type: integer nullable: true description: Adjusted handling time for conversation in seconds. This is the active handling time excluding idle periods when teammates are not actively working on the conversation. example: 1800 conversation_teammates: title: Conversation teammates type: object nullable: true description: The list of teammates who participated in the conversation (wrote at least one conversation part). properties: type: type: string description: The type of the object - `admin.list`. example: admin.list teammates: type: array description: The list of teammates who participated in the conversation (wrote at least one conversation part). items: "$ref": "#/components/schemas/reference" convert_conversation_to_ticket_request: description: You can convert a Conversation to a Ticket type: object title: Convert Ticket Request Payload properties: ticket_type_id: type: string description: The ID of the type of ticket you want to convert the conversation to example: '1234' attributes: "$ref": "#/components/schemas/ticket_request_custom_attributes" required: - ticket_type_id convert_visitor_request: description: You can merge a Visitor to a Contact of role type lead or user. type: object title: Convert Visitor Request Payload properties: type: type: string description: Represents the role of the Contact model. Accepts `lead` or `user`. example: user user: type: object description: The unique identifiers retained after converting or merging. properties: id: type: string description: The unique identifier for the contact which is given by Intercom. example: 8a88a590-e1c3-41e2-a502-e0649dbf721c user_id: type: string description: A unique identifier for the contact which is given to Intercom, which will be represented as external_id. example: 8a88a590-e1c3-41e2-a502-e0649dbf721c email: type: string description: The contact's email, retained by default if one is present. example: winstonsmith@truth.org anyOf: - required: - id - required: - user_id visitor: type: object description: The unique identifiers to convert a single Visitor. properties: id: type: string description: The unique identifier for the contact which is given by Intercom. example: 8a88a590-e1c3-41e2-a502-e0649dbf721c user_id: type: string description: A unique identifier for the contact which is given to Intercom. example: 8a88a590-e1c3-41e2-a502-e0649dbf721c email: type: string description: The visitor's email. example: winstonsmith@truth.org anyOf: - required: - id - required: - user_id - required: - email required: - type - user - visitor create_article_request: description: You can create an Article type: object title: Create Article Request Payload nullable: true properties: title: type: string description: The title of the article.For multilingual articles, this will be the title of the default language's content. example: Thanks for everything description: type: string description: The description of the article. For multilingual articles, this will be the description of the default language's content. example: Description of the Article body: type: string description: The content of the article. For multilingual articles, this will be the body of the default language's content. example: "This is the body in html
" author_id: type: integer description: 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 state: type: string description: 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_id: type: integer description: The id of the article's parent collection or section. An article without this field stands alone. example: 18 parent_type: type: string description: The type of parent, which can either be a `collection` or `section`. example: collection translated_content: "$ref": "#/components/schemas/article_translated_content" required: - title - author_id create_internal_article_request: description: You can create an Internal Article type: object title: Create Internal Article Request Payload nullable: true properties: title: type: string description: The title of the article. example: Thanks for everything body: type: string description: The content of the article. example: "This is the body in html
" author_id: type: integer description: The id of the author of the article. example: 1295 owner_id: type: integer description: The id of the owner of the article. example: 1295 required: - title - owner_id - author_id create_collection_request: description: You can create a collection type: object title: Create Collection Request Payload properties: name: type: string description: The name of the collection. For multilingual collections, this will be the name of the default language's content. example: collection 51 description: type: string description: The description of the collection. For multilingual collections, this will be the description of the default language's content. example: English description translated_content: nullable: true "$ref": "#/components/schemas/group_translated_content" parent_id: type: string nullable: true description: The id of the parent collection. If `null` then it will be created as the first level collection. example: '6871118' help_center_id: type: integer nullable: true description: 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' required: - name create_contact_request: description: Payload to create a contact type: object title: Create Contact Request Payload properties: role: type: string description: The role of the contact. external_id: type: string description: A unique identifier for the contact which is given to Intercom email: type: string description: The contacts email example: jdoe@example.com phone: type: string nullable: true description: The contacts phone example: "+353871234567" name: type: string nullable: true description: The contacts name example: John Doe avatar: type: string nullable: true description: An image URL containing the avatar of a contact example: https://www.example.com/avatar_image.jpg signed_up_at: type: integer format: date-time nullable: true description: The time specified for when a contact signed up example: 1571672154 last_seen_at: type: integer format: date-time nullable: true description: The time when the contact was last seen (either where the Intercom Messenger was installed or when specified manually) example: 1571672154 owner_id: type: integer nullable: true description: The id of an admin that has been assigned account ownership of the contact example: 123 unsubscribed_from_emails: type: boolean nullable: true description: Whether the contact is unsubscribed from emails example: true custom_attributes: type: object nullable: true description: The custom attributes which are set for the contact anyOf: - required: - email title: Create contact with email - required: - external_id title: Create contact with external_id - required: - role title: Create contact with role create_content_import_source_request: title: Create Content Import Source Payload type: object description: You can add an Content Import Source to your Fin Content Library. nullable: false properties: sync_behavior: type: string description: If you intend to create or update External Pages via the API, this should be set to `api`. enum: - api example: api status: type: string description: The status of the content import source. enum: - active - deactivated default: active example: active url: type: string description: The URL of the content import source. example: https://help.example.com required: - sync_behavior - url create_conversation_request: description: 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. type: object title: Create Conversation Request Payload properties: from: type: object properties: type: type: string enum: - lead - user - contact description: The role associated to the contact - user or lead. example: user id: type: string description: The identifier for the contact which is given by Intercom. format: uuid minLength: 24 maxLength: 24 example: 536e564f316c83104c000020 required: - type - id body: type: string description: The content of the message. HTML is not supported. example: Hello created_at: type: integer format: date-time description: The time the conversation was created as a UTC Unix timestamp. If not provided, the current time will be used. This field is only recommneded for migrating past conversations from another source into Intercom. example: 1671028894 required: - from - body create_data_attribute_request: description: '' type: object title: Create Data Attribute Request properties: name: type: string description: The name of the data attribute. example: My Data Attribute model: type: string description: The model that the data attribute belongs to. enum: - contact - company example: contact description: type: string description: The readable description you see in the UI for the attribute. example: My Data Attribute Description messenger_writable: type: boolean description: Can this attribute be updated by the Messenger example: false required: - name - model - data_type oneOf: - properties: data_type: enum: - options options: type: array description: Array of objects representing the options of the list, with `value` as the key and the option as the value. At least two options are required. items: type: object properties: value: type: string example: - value: 1-10 - value: 11-50 required: - options title: 'list attribute' - properties: data_type: enum: - string - integer - float - boolean - datetime - date title: 'other type' create_data_event_request: description: '' type: object title: Create Data Event Request properties: event_name: type: string description: 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_at: type: integer format: date-time description: The time the event occurred as a UTC Unix timestamp example: 1671028894 user_id: type: string description: Your identifier for the user. example: '314159' id: type: string description: The unique identifier for the contact (lead or user) which is given by Intercom. example: 8a88a590-e1c3-41e2-a502-e0649dbf721c email: type: string description: 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 metadata: type: object description: Optional metadata about the event. additionalProperties: type: string example: invite_code: ADDAFRIEND anyOf: - title: id required required: - event_name - created_at - id - title: user_id required required: - event_name - created_at - user_id - title: email required required: - event_name - created_at - email create_data_event_summaries_request: description: 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`. type: object title: Create Data Event Summaries Request properties: user_id: type: string description: Your identifier for the user. example: '314159' event_summaries: type: object description: 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`. properties: event_name: type: string description: The name of the event that occurred. A good event name is typically a past tense 'verb-noun' combination, to improve readability, for example `updated-plan`. example: invited-friend count: type: integer description: The number of times the event occurred. example: 1 first: type: integer format: date-time description: The first time the event was sent example: 1671028894 last: type: integer format: date-time description: The last time the event was sent example: 1671028894 create_data_exports_request: description: Request for creating a data export type: object title: Create Data Export Request properties: created_at_after: type: integer description: The start date that you request data for. It must be formatted as a unix timestamp. example: 1527811200 created_at_before: type: integer description: The end date that you request data for. It must be formatted as a unix timestamp. example: 1527811200 required: - created_at_after - created_at_before create_external_page_request: title: Create External Page Payload type: object description: You can add an External Page to your Fin Content Library. nullable: false properties: title: type: string description: The title of the external page. example: Getting started with... html: type: string description: The body of the external page in HTML. example: "Hello world!
" url: type: string description: The URL of the external page. This will be used by Fin to link end users to the page it based its answer on. When a URL is not present, Fin will not reference the source. example: https://help.example.com/en/articles/1234-getting-started ai_agent_availability: type: boolean description: Whether the external page should be used to answer questions by AI Agent. Will not default when updating an existing external page. default: false example: true ai_copilot_availability: type: boolean description: Whether the external page should be used to answer questions by AI Copilot. Will not default when updating an existing external page. default: false example: true locale: type: string description: Always en enum: - en default: en example: en source_id: type: integer description: 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. example: 1234 external_id: type: string description: The identifier for the external page which was given by the source. Must be unique for the source. example: '5678' required: - title - html - locale - source_id - external_id create_message_request: description: You can create a message type: object title: Create Message Request Payload nullable: true properties: message_type: type: string description: 'The kind of message being created. Values: `in_app` or `email`.' enum: - in_app - email example: in_app subject: type: string description: The title of the email. example: Thanks for everything body: type: string description: The content of the message. HTML and plaintext are supported. example: Hello there template: type: string description: The style of the outgoing message. Possible values `plain` or `personal`. example: plain from: type: object description: The sender of the message. If not provided, the default sender will be used. properties: type: type: string description: Always `admin`. enum: - admin example: admin id: type: integer description: The identifier for the admin which is given by Intercom. example: 394051 required: - type - id to: oneOf: - $ref: '#/components/schemas/recipient' - type: array description: The recipients of the message. items: $ref: '#/components/schemas/recipient' example: - type: user id: 536e564f316c83104c000020 - type: lead id: 536e564f316c83104c000021 cc: oneOf: - $ref: '#/components/schemas/recipient' - type: array description: The CC recipients of the message. items: $ref: '#/components/schemas/recipient' example: - type: user id: 536e564f316c83104c000023 bcc: oneOf: - $ref: '#/components/schemas/recipient' - type: array description: The BCC recipients of the message. items: $ref: '#/components/schemas/recipient' example: - type: user id: 536e564f316c83104c000022 created_at: type: integer description: The time the message was created. If not provided, the current time will be used. example: 1590000000 create_conversation_without_contact_reply: type: boolean description: 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 anyOf: - title: 'message_type: `email`.' required: - message_type - subject - body - template - from - to - title: 'message_type: `inapp`.' required: - message_type - body - from - to recipient: type: object title: Recipient description: A recipient of a message properties: type: type: string description: The role associated to the contact - `user` or `lead`. enum: - user - lead example: user id: type: string description: The identifier for the contact which is given by Intercom. example: 536e564f316c83104c000020 required: - type - id create_or_update_company_request: type: object title: Create Or Update Company Request Payload description: You can create or update a Company nullable: true properties: name: type: string description: The name of the Company example: Intercom company_id: type: string description: The company id you have defined for the company. Can't be updated example: 625e90fc55ab113b6d92175f plan: type: string description: The name of the plan you have associated with the company. example: Enterprise size: type: integer description: The number of employees in this company. example: '100' website: type: string description: 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 industry: type: string description: The industry that this company operates in. example: Manufacturing custom_attributes: type: object description: A hash of key/value pairs containing any other data about the company you want Intercom to store. additionalProperties: type: string example: paid_subscriber: true monthly_spend: 155.5 team_mates: 9 remote_created_at: type: integer description: The time the company was created by you. example: 1394531169 monthly_spend: type: integer description: 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 update_company_request: type: object title: Update Company Request Payload description: You can update a Company nullable: true properties: name: type: string description: The name of the Company example: Intercom plan: type: string description: The name of the plan you have associated with the company. example: Enterprise size: type: integer description: The number of employees in this company. example: '100' website: type: string description: 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 industry: type: string description: The industry that this company operates in. example: Manufacturing custom_attributes: type: object description: A hash of key/value pairs containing any other data about the company you want Intercom to store. additionalProperties: type: string example: paid_subscriber: true monthly_spend: 155.5 team_mates: 9 monthly_spend: type: integer description: 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 create_or_update_custom_object_instance_request: description: Payload to create or update a Custom Object instance type: object title: Create Or Update Custom Object Instance Request Payload properties: external_id: type: string description: A unique identifier for the Custom Object instance in the external system it originated from. external_created_at: type: integer format: date-time nullable: true description: The time when the Custom Object instance was created in the external system it originated from. example: 1571672154 external_updated_at: type: integer format: date-time nullable: true description: The time when the Custom Object instance was last updated in the external system it originated from. example: 1571672154 custom_attributes: type: object nullable: true description: The custom attributes which are set for the Custom Object instance. additionalProperties: type: string create_or_update_tag_request: description: You can create or update an existing tag. type: object title: Create or Update Tag Request Payload properties: name: type: string description: 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 id: type: string description: The id of tag to updates. example: '656452352' required: - name create_phone_switch_request: description: You can create an phone switch type: object title: Create Phone Switch Request Payload nullable: true properties: phone: type: string description: Phone number in E.164 format, that will receive the SMS to continue the conversation in the Messenger. example: "+1 1234567890" custom_attributes: "$ref": "#/components/schemas/custom_attributes" required: - phone create_ticket_reply_with_comment_request: title: Create Ticket Reply Request Payload oneOf: - "$ref": "#/components/schemas/contact_reply_ticket_request" - "$ref": "#/components/schemas/admin_reply_ticket_request" create_ticket_request: description: You can create a Ticket type: object title: Create Ticket Request Payload properties: ticket_type_id: type: string description: The ID of the type of ticket you want to create example: '1234' contacts: type: array description: The list of contacts (users or leads) affected by this ticket. Currently only one is allowed items: type: object oneOf: - title: ID properties: id: type: string description: The identifier for the contact as given by Intercom. required: - id - title: External ID properties: external_id: type: string description: The external_id you have defined for the contact who is being added as a participant. required: - external_id - title: Email properties: email: type: string description: The email you have defined for the contact who is being added as a participant. If a contact with this email does not exist, one will be created. required: - email example: - id: '1234' conversation_to_link_id: type: string description: "The ID of the conversation you want to link to the ticket. Here are the valid ways of linking two tickets:\n - conversation | back-office ticket\n - customer tickets | non-shared back-office ticket\n - conversation | tracker ticket\n - customer ticket | tracker ticket" example: '1234' company_id: type: string description: The ID of the company that the ticket is associated with. The unique identifier for the company which is given by Intercom example: 5f4d3c1c-7b1b-4d7d-a97e-6095715c6632 created_at: type: integer description: The time the ticket was created. If not provided, the current time will be used. example: 1590000000 ticket_attributes: "$ref": "#/components/schemas/ticket_request_custom_attributes" assignment: type: object properties: admin_assignee_id: type: string description: The ID of the admin to which the ticket is assigned. If not provided, the ticket will be unassigned. example: '123' team_assignee_id: type: string description: The ID of the team to which the ticket is assigned. If not provided, the ticket will be unassigned. example: '8' required: - ticket_type_id - contacts create_ticket_type_attribute_request: description: You can create a Ticket Type Attribute type: object title: Create Ticket Type Attribute Request Payload properties: name: type: string description: The name of the ticket type attribute example: Bug Priority description: type: string description: The description of the attribute presented to the teammate or contact example: Priority level of the bug data_type: type: string description: The data type of the attribute enum: - string - list - integer - decimal - boolean - datetime - files example: string required_to_create: type: boolean description: 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_contacts: type: boolean description: Whether the attribute is required to be filled in when contacts are creating the ticket in Messenger. default: false example: false visible_on_create: type: boolean description: Whether the attribute is visible to teammates when creating a ticket in Inbox. default: true example: true visible_to_contacts: type: boolean description: Whether the attribute is visible to contacts when creating a ticket in Messenger. default: true example: true multiline: type: boolean description: Whether the attribute allows multiple lines of text (only applicable to string attributes) example: false list_items: type: string description: A comma delimited list of items for the attribute value (only applicable to list attributes) example: Low Priority,Medium Priority,High Priority allow_multiple_values: type: boolean description: Whether the attribute allows multiple files to be attached to it (only applicable to file attributes) example: false required: - name - description - data_type create_ticket_type_request: description: | The request payload for creating a ticket type. You can copy the `icon` property for your ticket type from [Twemoji Cheatsheet](https://twemoji-cheatsheet.vercel.app/) type: object title: Create Ticket Type Request Payload nullable: true properties: name: type: string description: The name of the ticket type. example: Bug description: type: string description: The description of the ticket type. example: Used for tracking bugs category: type: string description: Category of the Ticket Type. enum: - Customer - Back-office - Tracker example: Customer icon: type: string description: The icon of the ticket type. example: "\U0001F41E" default: "\U0001F39F️" is_internal: type: boolean description: 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. example: false default: false required: - name cursor_pages: title: Cursor based pages type: object description: | 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. nullable: true properties: type: type: string description: the type of object `pages`. example: pages enum: - pages page: type: integer description: The current page example: 1 next: "$ref": "#/components/schemas/starting_after_paging" per_page: type: integer description: Number of results per page example: 2 total_pages: type: integer description: Total number of pages example: 13 call: title: Call type: object x-tags: - Calls description: Represents a phone call in Intercom properties: type: type: string description: String representing the object's type. Always has the value `call`. example: call id: type: string description: The id of the call. example: "123" conversation_id: type: string nullable: true description: The id of the conversation associated with the call, if any. example: "456" admin_id: type: string nullable: true description: The id of the admin associated with the call, if any. example: "789" contact_id: type: string nullable: true description: The id of the contact associated with the call, if any. example: "6762f0dd1bb69f9f2193bb83" state: type: string description: The current state of the call. example: completed initiated_at: "$ref": "#/components/schemas/datetime" answered_at: "$ref": "#/components/schemas/datetime" ended_at: "$ref": "#/components/schemas/datetime" created_at: "$ref": "#/components/schemas/datetime" updated_at: "$ref": "#/components/schemas/datetime" recording_url: type: string format: uri nullable: true description: API URL to download or redirect to the call recording if available. example: "https://api.intercom.io/calls/123/recording" transcription_url: type: string format: uri nullable: true description: API URL to download or redirect to the call transcript if available. example: "https://api.intercom.io/calls/123/transcript" call_type: type: string description: The type of call. example: phone direction: type: string description: The direction of the call. example: outbound ended_reason: type: string nullable: true description: The reason for the call end, if applicable. example: completed phone: type: string nullable: true description: The phone number involved in the call, in E.164 format. example: "+15551234567" fin_recording_url: type: string format: uri nullable: true description: API URL to the AI Agent (Fin) call recording if available. fin_transcription_url: type: string format: uri nullable: true description: API URL to the AI Agent (Fin) call transcript if available. call_list: title: Calls type: object description: A paginated list of calls. properties: type: type: string description: String representing the object's type. Always has the value `list`. example: list data: type: array description: A list of calls. items: "$ref": "#/components/schemas/call" total_count: type: integer description: Total number of items available. example: 0 pages: "$ref": "#/components/schemas/cursor_pages" custom_attributes: title: Custom Attributes type: object description: 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. additionalProperties: anyOf: - type: string - type: integer - $ref: "#/components/schemas/datetime" - "$ref": "#/components/schemas/custom_object_instance_list" example: paid_subscriber: true monthly_spend: 155.5 team_mates: 9 start_date_iso8601: "2023-03-04T09:46:14Z" end_date_timestamp: 1677923174 custom_object_instance: title: Custom Object Instance type: object x-tags: - Custom Object Instances nullable: true description: A Custom Object Instance represents an instance of a custom object type. This allows you to create and set custom attributes to store data about your customers that is not already captured by Intercom. The parent object includes recommended default attributes and you can add your own custom attributes. properties: id: type: string description: The Intercom defined id representing the custom object instance. example: 16032025 external_id: type: string description: The id you have defined for the custom object instance. example: 0001d1c1e65a7a19e9f59ae2 external_created_at: type: integer format: date-time nullable: true description: The time when the Custom Object instance was created in the external system it originated from. example: 1571672154 external_updated_at: type: integer format: date-time nullable: true description: The time when the Custom Object instance was last updated in the external system it originated from. example: 1571672154 created_at: type: integer format: date-time description: The time the attribute was created as a UTC Unix timestamp example: 1671028894 updated_at: type: integer format: date-time description: The time the attribute was last updated as a UTC Unix timestamp example: 1671028894 type: type: string description: The identifier of the custom object type that defines the structure of the custom object instance. example: Order custom_attributes: type: object description: The custom attributes you have set on the custom object instance. additionalProperties: type: string custom_object_instance_deleted: title: Custom Object Instance Deleted type: object description: deleted custom object instance object properties: object: type: string description: The unique identifier of the Custom Object type that defines the structure of the Custom Object instance. example: Order id: type: string description: The Intercom defined id representing the Custom Object instance. example: '123' deleted: type: boolean description: Whether the Custom Object instance is deleted or not. example: true custom_object_instance_list: title: Custom Object Instances type: object description: The list of associated custom object instances for a given reference attribute on the parent object. properties: type: type: string example: order.list instances: type: array description: The list of associated custom object instances for a given reference attribute on the parent object. items: "$ref": "#/components/schemas/custom_object_instance" customer_request: type: object nullable: true oneOf: - title: Intercom User ID properties: intercom_user_id: type: string description: The identifier for the contact as given by Intercom. example: 6329bd9ffe4e2e91dac76188 required: - intercom_user_id - title: User ID properties: user_id: type: string description: The external_id you have defined for the contact who is being added as a participant. example: 2e91dac761886329bd9ffe4e required: - user_id - title: Email properties: email: type: string description: The email you have defined for the contact who is being added as a participant. example: sam.sung@example.com required: - email data_attribute: title: Data Attribute type: object x-tags: - Data Attributes description: Data Attributes are metadata used to describe your contact, company and conversation models. These include standard and custom attributes. By using the data attributes endpoint, you can get the global list of attributes for your workspace, as well as create and archive custom attributes. properties: type: type: string description: Value is `data_attribute`. enum: - data_attribute example: data_attribute id: type: integer description: The unique identifier for the data attribute which is given by Intercom. Only available for custom attributes. example: 12878 model: type: string description: Value is `contact` for user/lead attributes and `company` for company attributes. enum: - contact - company example: contact name: type: string description: Name of the attribute. example: paid_subscriber full_name: type: string description: Full name of the attribute. Should match the name unless it's a nested attribute. We can split full_name on `.` to access nested user object values. example: custom_attributes.paid_subscriber label: type: string description: Readable name of the attribute (i.e. name you see in the UI) example: Paid Subscriber description: type: string description: Readable description of the attribute. example: Whether the user is a paid subscriber. data_type: type: string description: The data type of the attribute. enum: - string - integer - float - boolean - date example: boolean options: type: array description: List of predefined options for attribute value. items: type: string example: - 'true' - 'false' api_writable: type: boolean description: Can this attribute be updated through API example: true messenger_writable: type: boolean description: Can this attribute be updated by the Messenger example: false ui_writable: type: boolean description: Can this attribute be updated in the UI example: true custom: type: boolean description: Set to true if this is a CDA example: true archived: type: boolean description: Is this attribute archived. (Only applicable to CDAs) example: false created_at: type: integer format: date-time description: The time the attribute was created as a UTC Unix timestamp example: 1671028894 updated_at: type: integer format: date-time description: The time the attribute was last updated as a UTC Unix timestamp example: 1671028894 admin_id: type: string description: Teammate who created the attribute. Only applicable to CDAs example: '5712945' data_attribute_list: title: Data Attribute List type: object description: A list of all data attributes belonging to a workspace for contacts, companies or conversations. properties: type: type: string description: The type of the object enum: - list example: list data: type: array description: A list of data attributes items: "$ref": "#/components/schemas/data_attribute" data_event: title: Data Event type: object x-tags: - Data Events description: Data events are used to notify Intercom of changes to your data. properties: type: type: string description: The type of the object enum: - event example: event event_name: type: string description: 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_at: type: integer format: date-time description: The time the event occurred as a UTC Unix timestamp example: 1671028894 user_id: type: string description: Your identifier for the user. example: '314159' id: type: string description: Your identifier for a lead or a user. example: 8a88a590-e1c3-41e2-a502-e0649dbf721c intercom_user_id: type: string description: The Intercom identifier for the user. example: 63a0979a5eeebeaf28dd56ba email: type: string description: 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 metadata: type: object description: Optional metadata about the event. additionalProperties: type: string example: invite_code: ADDAFRIEND required: - event_name - created_at data_event_list: title: Data Event List type: object description: This will return a list of data events for the App. properties: type: type: string description: The type of the object enum: - event.list example: event.list events: type: array description: A list of data events items: "$ref": "#/components/schemas/data_event" pages: type: object description: Pagination properties: next: type: string example: https://api.intercom.io/events?per_page=2&before=1389913941064&intercom_user_id=63a0979a5eeebeaf28dd56ba&type=user" since: type: string example: https://api.intercom.io/events?intercom_user_id=63a0979a5eeebeaf28dd56ba&type=user&since=1389913941065 data_event_summary: title: Data Event Summary type: object description: This will return a summary of data events for the App. properties: type: type: string description: The type of the object enum: - event.summary example: event.summary email: type: string description: The email address of the user example: Sam.Sung@example.com intercom_user_id: type: string description: The Intercom user ID of the user example: 63a0979a5eeebeaf28dd56ba user_id: type: string description: The user ID of the user example: 62b997f288e14803c5006932 events: type: array description: A summary of data events items: "$ref": "#/components/schemas/data_event_summary_item" data_event_summary_item: title: Data Event Summary Item type: object description: This will return a summary of a data event for the App. nullable: true properties: name: type: string description: The name of the event example: placed-order first: type: string description: The first time the event was sent example: '2014-01-16T23:12:21.000+00:00' last: type: string description: The last time the event was sent example: '2014-01-16T23:12:21.000+00:00 ' count: type: integer description: The number of times the event was sent example: 1 description: type: string description: The description of the event example: A user placed an order data_export: title: Data Export type: object x-tags: - Data Export description: The data export api is used to view all message sent & viewed in a given timeframe. properties: job_identifier: type: string description: The identifier for your job. example: orzzsbd7hk67xyu status: type: string enum: - pending - in_progress - failed - completed - no_data - canceled description: The current state of your job. example: pending download_expires_at: type: string description: The time after which you will not be able to access the data. example: '1674917488' download_url: type: string description: The location where you can download your data. example: https://api.intercom.test/download/messages/data/example data_export_csv: title: Data Export CSV type: object description: A CSV output file properties: user_id: type: string description: The user_id of the user who was sent the message. user_external_id: type: string description: The external_user_id of the user who was sent the message company_id: type: string description: The company ID of the user in relation to the message that was sent. Will return -1 if no company is present. email: type: string description: The users email who was sent the message. name: type: string description: The full name of the user receiving the message ruleset_id: type: string description: The id of the message. content_id: type: string description: The specific content that was received. In an A/B test each version has its own Content ID. content_type: type: string description: Email, Chat, Post etc. content_title: type: string description: The title of the content you see in your Intercom workspace. ruleset_version_id: type: string description: 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_id: type: string description: ID for this receipt. Will be included with any related stats in other files to identify this specific delivery of a message. received_at: type: integer description: Timestamp for when the receipt was recorded. series_id: type: string description: The id of the series that this content is part of. Will return -1 if not part of a series. series_title: type: string description: The title of the series that this content is part of. node_id: type: string description: The id of the series node that this ruleset is associated with. Each block in a series has a corresponding node_id. first_reply: type: integer description: The first time a user replied to this message if the content was able to receive replies. first_completion: type: integer description: The first time a user completed this message if the content was able to be completed e.g. Tours, Surveys. first_series_completion: type: integer description: The first time the series this message was a part of was completed by the user. first_series_disengagement: type: integer description: The first time the series this message was a part of was disengaged by the user. first_series_exit: type: integer description: The first time the series this message was a part of was exited by the user. first_goal_success: type: integer description: The first time the user met this messages associated goal if one exists. first_open: type: integer description: The first time the user opened this message. first_click: type: integer description: The first time the series the user clicked on a link within this message. first_dismisall: type: integer description: The first time the series the user dismissed this message. first_unsubscribe: type: integer description: The first time the user unsubscribed from this message. first_hard_bounce: type: integer description: The first time this message hard bounced for this user deleted_article_object: title: Deleted Article Object type: object description: Response returned when an object is deleted properties: id: type: string description: The unique identifier for the article which you provided in the URL. example: '6890762' object: type: string description: The type of object which was deleted. - article enum: - article example: article deleted: type: boolean description: Whether the article was deleted successfully or not. example: true deleted_internal_article_object: title: Deleted Internal Article Object type: object description: Response returned when an object is deleted properties: id: type: string description: The unique identifier for the internal article which you provided in the URL. example: '6890762' object: type: string description: The type of object which was deleted. - internal_article enum: - internal_article example: internal_article deleted: type: boolean description: Whether the internal article was deleted successfully or not. example: true deleted_collection_object: title: Deleted Collection Object type: object description: Response returned when an object is deleted properties: id: type: string description: The unique identifier for the collection which you provided in the URL. example: '6890762' object: type: string description: The type of object which was deleted. - `collection` enum: - collection example: collection deleted: type: boolean description: Whether the collection was deleted successfully or not. example: true deleted_company_object: title: Deleted Company Object type: object description: Response returned when an object is deleted properties: id: type: string description: The unique identifier for the company which is given by Intercom. example: 5b7e8b2f-7a1a-4e6c-8e1b-4f9d4f4c4d4f object: type: string description: The type of object which was deleted. - `company` enum: - company example: company deleted: type: boolean description: Whether the company was deleted successfully or not. example: true deleted_object: title: Deleted Object type: object description: Response returned when an object is deleted properties: id: type: string description: The unique identifier for the news item which you provided in the URL. example: '6890762' object: type: string description: The type of object which was deleted - news-item. enum: - news-item example: news-item deleted: type: boolean description: Whether the news item was deleted successfully or not. example: true detach_contact_from_conversation_request: properties: admin_id: type: string description: The `id` of the admin who is performing the action. example: '5017690' required: - admin_id email_address_header: title: Email Address Header type: object description: Contains data for an email address header for a conversation part that was sent as an email. properties: type: type: string description: The type of email address header example: from email_address: type: string description: The email address example: jdoe@example.com name: type: string nullable: true description: The name associated with the email address example: Joe Example email_message_metadata: title: Email Message Metadata type: object description: Contains metadata if the message was sent as an email properties: subject: type: string description: The subject of the email example: Question about my order email_address_headers: title: Email Address Headers type: array description: A list of an email address headers. items: "$ref": "#/components/schemas/email_address_header" message_id: type: string nullable: true description: The unique identifier for the email message as specified in the Message-ID header example: "conversation_attribute_updated_by_workflow.
properties:
workflow:
type: object
properties:
name:
type: string
description: Name of the workflow
example: Workflow 1
attribute:
type: object
properties:
name:
type: string
description: Name of the CDA updated
example: flight_category
value:
type: object
properties:
name:
type: string
description: Value of the CDA updated
example: vip_status
conversation_attribute_updated_by_admin:
title: Part type - conversation_attribute_updated_by_admin
type: object
description: Contains details about Custom Data Attributes (CDAs) that were modified by an admin (operator) for conversation part type conversation_attribute_updated_by_admin.
properties:
attribute:
type: object
properties:
name:
type: string
description: Name of the CDA updated
example: jira_issue_key
value:
type: object
properties:
name:
type: string
description: Current value of the CDA updated
example: PROJ-007
previous:
type: string
nullable: true
description: Previous value of the CDA
example: PROJ-006
conversation_attribute_updated_by_user:
title: Part type - conversation_attribute_updated_by_user
type: object
description: Contains details about Custom Data Attributes (CDAs) that were modified by a user for conversation part type conversation_attribute_updated_by_user.
properties:
attribute:
type: object
properties:
name:
type: string
description: Name of the CDA updated
example: Priority
value:
type: object
properties:
name:
type: string
description: Current value of the CDA updated
example: High
previous:
type: string
nullable: true
description: Previous value of the CDA (null for older events)
example: Medium
custom_action_started:
title: Part type - custom_action_started
type: object
description: Contains details about name of the action that was initiated for conversation part type custom_action_started.
properties:
action:
type: object
properties:
name:
type: string
description: Name of the action
example: Jira Create Issue
custom_channel_attribute:
title: Custom Channel - Attribute
type: object
required:
- id
- value
properties:
id:
type: string
description: Identifier for the attribute being collected.
value:
type: string
description: Value provided by the user for the attribute.
custom_channel_base_event:
title: Custom Channel - Base Event
type: object
properties:
event_id:
type: string
description: Unique identifier for the event.
external_conversation_id:
type: string
description: Identifier for the conversation in your application.
contact:
$ref: '#/components/schemas/custom_channel_contact'
required:
- event_id
- external_conversation_id
- contact
custom_channel_contact:
title: Custom Channel - Simplified Contact
type: object
required:
- type
- external_id
properties:
type:
type: string
enum: [user, lead]
description: Type of contact, must be "user" or "lead".
external_id:
type: string
description: External identifier for the contact. Intercom will take care of the mapping of your external_id with our internal ones so you don't have to worry about it.
name:
type: string
description: Name of the contact. Required for user type.
email:
type: string
format: email
description: Email address of the contact. Required for user type.
custom_channel_notification_response:
type: object
required:
- external_conversation_id
- conversation_id
- external_contact_id
- contact_id
properties:
external_conversation_id:
type: string
description: The external conversation ID provided in the notification request
conversation_id:
type: string
description: The Intercom conversation ID mapped to the external conversation ID
external_contact_id:
type: string
description: The external contact ID provided in the notification request
contact_id:
type: string
description: The Intercom contact ID mapped to the external contact ID
custom_action_finished:
title: Part type - custom_action_finished
type: object
description: Contains details about final status of the completed action for conversation part type custom_action_finished.
properties:
action:
type: object
properties:
name:
type: string
description: Name of the action
example: Jira Create Issue
result:
type: string
description: Status of the action
enum:
- success
- failed
example: success
operator_workflow_event:
title: Part type - operator_workflow_event
type: object
description: Contains details about name of the workflow for conversation part type operator_workflow_event.
properties:
workflow:
type: object
properties:
name:
type: string
description: The name of the workflow
example: Custom Bot 1
event:
type: object
properties:
type:
type: string
description: Type of the workflow event initiated
example: wait_finished
result:
type: string
description: Result of the workflow event
example: Finsihed waiting
event_details:
title: Event details of Workflow & actions
type: object
anyOf:
- "$ref": "#/components/schemas/conversation_attribute_updated_by_workflow"
- "$ref": "#/components/schemas/conversation_attribute_updated_by_admin"
- "$ref": "#/components/schemas/conversation_attribute_updated_by_user"
- "$ref": "#/components/schemas/custom_action_started"
- "$ref": "#/components/schemas/custom_action_finished"
- "$ref": "#/components/schemas/operator_workflow_event"
error:
type: object
title: Error
description: The API will return an Error List for a failed request, which will
contain one or more Error objects.
properties:
type:
type: string
description: The type is error.list
example: error.list
request_id:
type: string
nullable: true
format: uuid
description: ''
example: f93ecfa8-d08a-4325-8694-89aeb89c8f85
errors:
type: array
description: An array of one or more error objects
items:
properties:
code:
type: string
description: A string indicating the kind of error, used to further
qualify the HTTP response code
example: unauthorized
message:
type: string
nullable: true
description: Optional. Human readable description of the error.
example: Access Token Invalid
field:
type: string
nullable: true
description: Optional. Used to identify a particular field or query
parameter that was in error.
example: email
required:
- code
required:
- type
- errors
external_page:
title: External Page
type: object
x-tags:
- AI Content
description: External pages that you have added to your Fin Content Library.
nullable: false
properties:
type:
type: string
description: Always external_page
enum:
- external_page
default: external_page
example: external_page
id:
type: string
description: The unique identifier for the external page which is given
by Intercom.
example: '1234'
title:
type: string
description: The title of the external page.
example: Getting started with...
html:
type: string
description: The body of the external page in HTML.
example: "Hello world!
" url: type: string description: The URL of the external page. This will be used by Fin to link end users to the page it based its answer on. example: https://help.example.com/en/articles/1234-getting-started ai_agent_availability: type: boolean description: Whether the external page should be used to answer questions by AI Agent. example: true ai_copilot_availability: type: boolean description: Whether the external page should be used to answer questions by AI Copilot. example: true fin_availability: type: boolean description: Deprecated. Use ai_agent_availability and ai_copilot_availability instead. example: true locale: type: string description: Always en enum: - en default: en example: en source_id: type: integer description: 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. example: 1234 external_id: type: string description: The identifier for the external page which was given by the source. Must be unique for the source. example: '5678' created_at: type: integer format: date-time description: The time when the external page was created. example: 1672928359 updated_at: type: integer format: date-time description: The time when the external page was last updated. example: 1672928610 last_ingested_at: type: integer format: date-time description: The time when the external page was last ingested. example: 1672928610 required: - id - type - title - html - ai_agent_availability - ai_copilot_availability - locale - source_id - created_at - updated_at - last_ingested_at - external_id external_pages_list: title: External Pages type: object x-tags: - AI Content description: This will return a list of external pages for the App. nullable: false properties: type: type: string description: The type of the object - `list`. enum: - list example: list pages: "$ref": "#/components/schemas/pages_link" total_count: type: integer description: A count of the total number of external pages. example: 1 data: type: array description: An array of External Page objects items: "$ref": "#/components/schemas/external_page" file_attribute: title: File type: object description: The value describing a file upload set for a custom attribute properties: type: type: string example: upload name: type: string description: The name of the file example: Screenshot.png url: type: string description: 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_type: type: string description: The type of file example: image/png filesize: type: integer description: The size of the file in bytes example: 11308309 width: type: integer description: The width of the file in pixels, if applicable example: 3024 height: type: integer description: The height of the file in pixels, if applicable example: 1964 group_content: title: Group Content type: object description: The Content of a Group. nullable: true properties: type: type: string description: The type of object - `group_content` . enum: - - group_content example: group_content nullable: true name: type: string description: The name of the collection or section. example: Collection name description: type: string description: The description of the collection. Only available for collections. example: " Collection description" group_translated_content: title: Group Translated Content type: object description: The Translated Content of an Group. The keys are the locale codes and the values are the translated content of the Group. nullable: true properties: type: type: string description: The type of object - group_translated_content. nullable: true enum: - - group_translated_content example: group_translated_content ar: description: The content of the group in Arabic "$ref": "#/components/schemas/group_content" bg: description: The content of the group in Bulgarian "$ref": "#/components/schemas/group_content" bs: description: The content of the group in Bosnian "$ref": "#/components/schemas/group_content" ca: description: The content of the group in Catalan "$ref": "#/components/schemas/group_content" cs: description: The content of the group in Czech "$ref": "#/components/schemas/group_content" da: description: The content of the group in Danish "$ref": "#/components/schemas/group_content" de: description: The content of the group in German "$ref": "#/components/schemas/group_content" el: description: The content of the group in Greek "$ref": "#/components/schemas/group_content" en: description: The content of the group in English "$ref": "#/components/schemas/group_content" es: description: The content of the group in Spanish "$ref": "#/components/schemas/group_content" et: description: The content of the group in Estonian "$ref": "#/components/schemas/group_content" fi: description: The content of the group in Finnish "$ref": "#/components/schemas/group_content" fr: description: The content of the group in French "$ref": "#/components/schemas/group_content" he: description: The content of the group in Hebrew "$ref": "#/components/schemas/group_content" hr: description: The content of the group in Croatian "$ref": "#/components/schemas/group_content" hu: description: The content of the group in Hungarian "$ref": "#/components/schemas/group_content" id: description: The content of the group in Indonesian "$ref": "#/components/schemas/group_content" it: description: The content of the group in Italian "$ref": "#/components/schemas/group_content" ja: description: The content of the group in Japanese "$ref": "#/components/schemas/group_content" ko: description: The content of the group in Korean "$ref": "#/components/schemas/group_content" lt: description: The content of the group in Lithuanian "$ref": "#/components/schemas/group_content" lv: description: The content of the group in Latvian "$ref": "#/components/schemas/group_content" mn: description: The content of the group in Mongolian "$ref": "#/components/schemas/group_content" nb: description: The content of the group in Norwegian "$ref": "#/components/schemas/group_content" nl: description: The content of the group in Dutch "$ref": "#/components/schemas/group_content" pl: description: The content of the group in Polish "$ref": "#/components/schemas/group_content" pt: description: The content of the group in Portuguese (Portugal) "$ref": "#/components/schemas/group_content" ro: description: The content of the group in Romanian "$ref": "#/components/schemas/group_content" ru: description: The content of the group in Russian "$ref": "#/components/schemas/group_content" sl: description: The content of the group in Slovenian "$ref": "#/components/schemas/group_content" sr: description: The content of the group in Serbian "$ref": "#/components/schemas/group_content" sv: description: The content of the group in Swedish "$ref": "#/components/schemas/group_content" tr: description: The content of the group in Turkish "$ref": "#/components/schemas/group_content" vi: description: The content of the group in Vietnamese "$ref": "#/components/schemas/group_content" pt-BR: description: The content of the group in Portuguese (Brazil) "$ref": "#/components/schemas/group_content" zh-CN: description: The content of the group in Chinese (China) "$ref": "#/components/schemas/group_content" zh-TW: description: The content of the group in Chinese (Taiwan) "$ref": "#/components/schemas/group_content" help_center: title: Help Center type: object x-tags: - Help Center description: Help Centers contain collections properties: id: type: string description: The unique identifier for the Help Center which is given by Intercom. example: '123' workspace_id: type: string description: The id of the workspace which the Help Center belongs to. example: hfi1bx4l created_at: type: integer format: date-time description: The time when the Help Center was created. example: 1672928359 updated_at: type: integer format: date-time description: The time when the Help Center was last updated. example: 1672928610 identifier: type: string description: The identifier of the Help Center. This is used in the URL of the Help Center. example: intercom website_turned_on: type: boolean description: Whether the Help Center is turned on or not. This is controlled in your Help Center settings. example: true display_name: type: string description: The display name of the Help Center only seen by teammates. example: Intercom Help Center url: type: string description: The URL for the help center, if you have a custom domain then this will show the URL using the custom domain. example: "https://help.mycompany.com" custom_domain: type: string nullable: true description: Custom domain configured for the help center example: "help.mycompany.com" help_center_list: title: Help Centers type: object x-tags: - Help Center description: A list of Help Centers belonging to the App properties: type: type: string description: The type of the object - `list`. enum: - list example: list data: type: array description: An array of Help Center objects items: "$ref": "#/components/schemas/help_center" jobs: title: Jobs type: object x-tags: - Jobs description: Jobs are tasks that are processed asynchronously by the Intercom system after being enqueued via the API. This allows for efficient handling of operations that may take time to complete, such as data imports or exports. You can check the status of your jobs to monitor their progress and ensure they are completed successfully. properties: type: type: string description: The type of the object enum: - job id: type: string description: The id of the job that's currently being processed or has completed. example: 20 url: type: string description: API endpoint URL to check the job status. example: https://api.intercom.io/jobs/status/20 status: type: string description: The status of the job execution. enum: - pending - success - failed resource_type: type: string description: The type of resource created during job execution. example: ticket resource_id: type: string description: The id of the resource created during job execution (e.g. ticket id) example: 123 nullable: true resource_url: type: string description: The url of the resource created during job exeuction. Use this url to fetch the resource. example: http://api.intercom.io/tickets/123 nullable: true required: - id ip_allowlist: title: IP Allowlist type: object description: IP allowlist settings for the workspace. properties: type: type: string description: String representing the object's type. Always has the value `ip_allowlist`. example: ip_allowlist enabled: type: boolean description: Whether the IP allowlist is enabled for the workspace. example: true ip_allowlist: type: array description: | List of allowed IP addresses and/or IP ranges in CIDR notation. Examples: - Single IP: `192.168.0.1` - IP range: `192.168.0.1/24` (allows 192.168.0.0 - 192.168.0.255) items: type: string example: - "192.168.1.0/24" - "10.0.0.1" intercom_version: description: Intercom API version.By default, it's equal to the version set in the app package. type: string example: '2.14' default: '2.14' enum: - '1.0' - '1.1' - '1.2' - '1.3' - '1.4' - '2.0' - '2.1' - '2.2' - '2.3' - '2.4' - '2.5' - '2.6' - '2.7' - '2.8' - '2.9' - '2.10' - '2.11' - '2.12' - '2.13' - '2.14' linked_object: title: Linked Object type: object description: A linked conversation or ticket. properties: type: type: string description: ticket or conversation enum: - ticket - conversation example: ticket id: type: string description: The ID of the linked object example: '7583' category: type: string description: Category of the Linked Ticket Object. enum: - Customer - Back-office - Tracker - example: Customer nullable: true linked_object_list: title: Linked Objects type: object description: An object containing metadata about linked conversations and linked tickets. Up to 1000 can be returned. properties: type: type: string description: Always list. enum: - list example: list total_count: type: integer description: The total number of linked objects. example: 100 has_more: type: boolean description: Whether or not there are more linked objects than returned. example: false data: type: array description: An array containing the linked conversations and linked tickets. items: "$ref": "#/components/schemas/linked_object" merge_contacts_request: description: Merge contact data. type: object title: Merge contact data properties: from: type: string description: The unique identifier for the contact to merge away from. Must be a lead. example: 5d70dd30de4efd54f42fd526 into: type: string description: The unique identifier for the contact to merge into. Must be a user. example: 5ba682d23d7cf92bef87bfd4 message: type: object title: Message x-tags: - Messages description: Message are how you reach out to contacts in Intercom. They are created when an admin sends an outbound message to a contact. properties: type: type: string description: The type of the message example: user_message id: type: string description: The id representing the message. example: '1488971108' created_at: type: integer format: date-time description: The time the conversation was created. example: 1667560812 subject: type: string description: 'The subject of the message. Only present if message_type: email.' example: Greetings body: type: string description: The message body, which may contain HTML. example: Hello message_type: type: string enum: - email - inapp - facebook - twitter description: The type of message that was sent. Can be email, inapp, facebook or twitter. example: inapp conversation_id: type: string description: The associated conversation_id example: '64619700005570' required: - type - id - created_at - body - message_type whatsapp_message_status_list: type: object required: - type - ruleset_id - pages - total_count - events properties: type: type: string enum: ["list"] ruleset_id: type: string description: The provided ruleset ID pages: type: object required: - type - per_page - total_pages properties: type: type: string enum: ["pages"] per_page: type: integer description: Number of results per page total_pages: type: integer description: Total number of pages next: type: object nullable: true description: Information for fetching next page (null if no more pages) properties: starting_after: type: string description: Cursor for the next page total_count: type: integer description: Total number of events events: type: array items: type: object required: - id - conversation_id - status - type - created_at - updated_at - whatsapp_message_id properties: id: type: string description: Event ID conversation_id: type: string description: ID of the conversation status: type: string description: Current status of the message enum: ["sent", "delivered", "read", "failed"] type: type: string description: Event type enum: ["broadcast_outbound"] created_at: type: integer description: Creation timestamp updated_at: type: integer description: Last update timestamp whatsapp_message_id: type: string description: WhatsApp's message identifier template_name: type: string description: Name of the WhatsApp template used multiple_filter_search_request: title: Multiple Filter Search Request description: Search using Intercoms Search APIs with more than one filter. type: object properties: operator: type: string enum: - AND - OR description: An operator to allow boolean inspection between multiple fields. example: AND value: oneOf: - type: array description: Add mutiple filters. title: multiple filter search request items: "$ref": "#/components/schemas/multiple_filter_search_request" - type: array description: Add a single filter field. title: single filter search request items: "$ref": "#/components/schemas/single_filter_search_request" news_item: title: News Item type: object x-tags: - News 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. properties: type: type: string description: The type of object. enum: - news-item example: news-item id: type: string description: The unique identifier for the news item which is given by Intercom. example: '141' workspace_id: type: string description: The id of the workspace which the news item belongs to. example: t74hdn32 title: type: string description: The title of the news item. example: 'New feature: News Items' body: type: string description: The news item body, which may contain HTML. example: We are excited to announce the launch of News Items, a new content type in Intercom enabling you to announce product updates, company news, promotions, events and more with your customers. sender_id: type: integer description: The id of the sender of the news item. Must be a teammate on the workspace. example: 123 state: type: string description: News items will not be visible to your users in the assigned newsfeeds until they are set live. enum: - draft - live example: live newsfeed_assignments: type: array description: A list of newsfeed_assignments to assign to the specified newsfeed. items: "$ref": "#/components/schemas/newsfeed_assignment" labels: type: array description: Label names displayed to users to categorize the news item. items: type: string nullable: true description: The label name. example: Product Update cover_image_url: type: string format: uri nullable: true description: URL of the image used as cover. Must have .jpg or .png extension. example: https://example.com/cover.jpg reactions: type: array description: Ordered list of emoji reactions to the news item. When empty, reactions are disabled. items: type: string nullable: true description: The emoji reaction to the news item. example: "\U0001F44D" deliver_silently: type: boolean description: When set to true, the news item will appear in the messenger newsfeed without showing a notification badge. example: true created_at: type: integer format: timestamp description: Timestamp for when the news item was created. example: 1610589632 updated_at: type: integer format: timestamp description: Timestamp for when the news item was last updated. example: 1610589632 news_item_request: 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. type: object title: Create News Item Request properties: title: type: string description: The title of the news item. example: Halloween is here! body: type: string description: The news item body, which may contain HTML. example: "New costumes in store for this spooky season
" sender_id: type: integer description: The id of the sender of the news item. Must be a teammate on the workspace. example: 123 state: type: string description: News items will not be visible to your users in the assigned newsfeeds until they are set live. enum: - draft - live example: live deliver_silently: type: boolean description: When set to `true`, the news item will appear in the messenger newsfeed without showing a notification badge. example: true labels: type: array description: Label names displayed to users to categorize the news item. items: type: string example: - Product - Update - New reactions: type: array description: Ordered list of emoji reactions to the news item. When empty, reactions are disabled. items: type: string nullable: true example: - "\U0001F606" - "\U0001F605" newsfeed_assignments: type: array description: A list of newsfeed_assignments to assign to the specified newsfeed. items: "$ref": "#/components/schemas/newsfeed_assignment" required: - title - sender_id newsfeed: title: Newsfeed type: object x-tags: - News description: | A newsfeed is a collection of news items, targeted to a specific audience. Newsfeeds currently cannot be edited through the API, please refer to [this article](https://www.intercom.com/help/en/articles/6362267-getting-started-with-news) to set up your newsfeeds in Intercom. properties: id: type: string description: The unique identifier for the newsfeed which is given by Intercom. example: '12312' type: type: string description: The type of object. enum: - newsfeed example: newsfeed name: type: string description: The name of the newsfeed. This name will never be visible to your users. example: My Newsfeed created_at: type: integer format: timestamp description: Timestamp for when the newsfeed was created. example: 1674917488 updated_at: type: integer format: timestamp description: Timestamp for when the newsfeed was last updated. example: 1674917488 newsfeed_assignment: title: Newsfeed Assignment type: object x-tags: - News description: Assigns a news item to a newsfeed. properties: newsfeed_id: type: integer description: The unique identifier for the newsfeed which is given by Intercom. Publish dates cannot be in the future, to schedule news items use the dedicated feature in app (see this article). example: 198313 published_at: type: integer format: timestamp description: Publish date of the news item on the newsfeed, use this field if you want to set a publish date in the past (e.g. when importing existing news items). On write, this field will be ignored if the news item state is "draft". example: 1674917488 note: title: Note type: object x-tags: - Notes description: Notes allow you to annotate and comment on your contacts. properties: type: type: string description: String representing the object's type. Always has the value `note`. example: note id: type: string description: The id of the note. example: '17495962' created_at: type: integer format: timestamp description: The time the note was created. example: 1674589321 contact: type: object description: Represents the contact that the note was created about. nullable: true properties: type: type: string description: String representing the object's type. Always has the value `contact`. id: type: string description: The id of the contact. example: 214656d0c743eafcfde7f248 author: "$ref": "#/components/schemas/admin" description: Optional. Represents the Admin that created the note. body: type: string description: The body text of the note. example: "Text for the note.
" note_list: title: Paginated Response type: object description: A paginated list of notes associated with a contact. properties: type: type: string description: String representing the object's type. Always has the value `list`. example: list data: type: array description: An array of notes. items: "$ref": "#/components/schemas/note" total_count: type: integer description: A count of the total number of notes. example: 1 pages: "$ref": "#/components/schemas/cursor_pages" open_conversation_request: title: Open Conversation Request type: object description: Payload of the request to open a conversation properties: message_type: type: string enum: - open example: open admin_id: type: string description: The id of the admin who is performing the action. example: '5017690' required: - message_type - admin_id pages_link: title: Pagination Object type: object description: | 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. properties: type: type: string example: pages enum: - pages page: type: integer example: 1 next: type: string format: uri description: A link to the next page of results. A response that does not contain a next link does not have further data to fetch. nullable: true per_page: type: integer example: 50 total_pages: type: integer example: 1 paginated_response: title: Paginated Response type: object description: Paginated Response properties: type: type: string description: The type of object enum: - list - conversation.list example: list pages: "$ref": "#/components/schemas/cursor_pages" total_count: type: integer description: A count of the total number of objects. example: 1 data: type: array description: An array of Objects items: anyOf: - "$ref": "#/components/schemas/news_item" - "$ref": "#/components/schemas/newsfeed" part_attachment: title: Part attachment type: object description: The file attached to a part properties: type: type: string description: The type of attachment example: upload name: type: string description: The name of the attachment example: example.png url: type: string description: The URL of the attachment example: https://picsum.photos/200/300 content_type: type: string description: The content type of the attachment example: image/png filesize: type: integer description: The size of the attachment example: 100 width: type: integer description: The width of the attachment example: 100 height: type: integer description: The height of the attachment example: 100 phone_switch: title: Phone Switch type: object description: Phone Switch Response nullable: true properties: type: type: string description: '' enum: - phone_call_redirect default: phone_call_redirect example: phone_call_redirect phone: type: string description: Phone number in E.164 format, that has received the SMS to continue the conversation in the Messenger. example: "+1 1234567890" quick_reply_option: title: Quick Reply Option type: object properties: text: type: string description: The text to display in this quick reply option. uuid: type: string format: uuid description: A unique identifier for this quick reply option. This value will be available within the metadata of the comment conversation part that is created when a user clicks on this reply option. required: - text - uuid register_fin_voice_call_request: title: Register Fin Voice Call Request Payload type: object description: Register a Fin Voice call with Intercom nullable: true required: - phone_number - call_id properties: phone_number: type: string description: Phone number in E.164 format for the call example: '+1234567890' call_id: type: string description: External call identifier from the call provider example: 'call-123-abc' source: type: string description: Source of the call. Can be "five9", "zoom_phone", or defaults to "aws_connect" enum: - five9 - zoom_phone - aws_connect example: 'aws_connect' data: type: object description: Additional metadata about the call nullable: true example: key: value redact_conversation_request: oneOf: - title: Redact Conversation Part Request type: object description: Payload of the request to redact a conversation part properties: type: type: string enum: - conversation_part description: The type of resource being redacted. example: conversation_part conversation_id: type: string description: The id of the conversation. example: '19894788788' conversation_part_id: type: string description: The id of the conversation_part. example: '19381789428' required: - type - conversation_id - conversation_part_id - title: Redact Conversation Source Request type: object description: Payload of the request to redact a conversation source properties: type: type: string enum: - source description: The type of resource being redacted. example: source conversation_id: type: string description: The id of the conversation. example: '19894788788' source_id: type: string description: The id of the source. example: '19894781231' required: - type - conversation_id - source_id reference: title: Reference type: object description: reference to another object properties: type: type: string description: '' example: contact id: type: string nullable: true description: '' example: 1a2b3c reply_conversation_request: oneOf: - "$ref": "#/components/schemas/contact_reply_conversation_request" - "$ref": "#/components/schemas/admin_reply_conversation_request" search_request: description: Search using Intercoms Search APIs. type: object title: Search data properties: query: oneOf: - "$ref": "#/components/schemas/single_filter_search_request" title: Single filter search request - "$ref": "#/components/schemas/multiple_filter_search_request" title: multiple filter search request pagination: "$ref": "#/components/schemas/starting_after_paging" required: - query segment: title: Segment type: object x-tags: - Segments description: A segment is a group of your contacts defined by the rules that you set. properties: type: type: string description: The type of object. enum: - segment example: segment id: type: string description: The unique identifier representing the segment. example: 56203d253cba154d39010062 name: type: string description: The name of the segment. example: Active created_at: type: integer description: The time the segment was created. example: 1394621988 updated_at: type: integer description: The time the segment was updated. example: 1394622004 person_type: type: string description: 'Type of the contact: contact (lead) or user.' enum: - contact - user example: contact count: type: integer description: The number of items in the user segment. It's returned when `include_count=true` is included in the request. example: 3 nullable: true segment_list: title: Segment List type: object description: This will return a list of Segment Objects. The result may also have a pages object if the response is paginated. properties: type: type: string description: The type of the object enum: - segment.list example: segment.list segments: type: array description: A list of Segment objects items: "$ref": "#/components/schemas/segment" pages: type: object description: A pagination object, which may be empty, indicating no further pages to fetch. single_filter_search_request: title: Single Filter Search Request description: Search using Intercoms Search APIs with a single filter. type: object properties: field: type: string description: The accepted field that you want to search on. example: created_at operator: type: string enum: - "=" - "!=" - IN - NIN - "<" - ">" - "~" - "!~" - "^" - "$" description: The accepted operators you can use to define how you want to search for the value. example: ">" value: oneOf: - type: string - type: integer - type: array items: oneOf: - type: string - type: integer description: The value that you want to search on. example: '73732934' nullable: true sla_applied: title: Applied SLA type: object nullable: true description: | 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. properties: type: type: string description: object type example: conversation_sla_summary sla_name: type: string description: The name of the SLA as given by the teammate when it was created. example: '' sla_status: type: string enum: - hit - missed - cancelled - active description: |- 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. example: hit snooze_conversation_request: title: Snooze Conversation Request type: object description: Payload of the request to snooze a conversation properties: message_type: type: string enum: - snoozed example: snoozed admin_id: type: string description: The id of the admin who is performing the action. example: '5017691' snoozed_until: type: integer format: timestamp description: The time you want the conversation to reopen. example: 1673609604 required: - message_type - admin_id - snoozed_until social_profile: title: Social Profile type: object description: A Social Profile allows you to label your contacts, companies, and conversations and list them using that Social Profile. properties: type: type: string description: value is "social_profile" example: social_profile name: type: string description: The name of the Social media profile example: Facebook url: type: string format: uri description: The name of the Social media profile example: http://twitter.com/th1sland starting_after_paging: title: 'Pagination: Starting After' type: object nullable: true properties: per_page: type: integer description: The number of results to fetch per page. example: 2 starting_after: type: string description: The cursor to use in the next request to get the next page of results. nullable: true example: your-cursor-from-response subscription_type: title: Subscription Types type: object x-tags: - Subscription Types description: A subscription type lets customers easily opt out of non-essential communications without missing what's important to them. properties: type: type: string description: The type of the object - subscription example: subscription id: type: string description: The unique identifier representing the subscription type. example: '123456' state: type: string description: The state of the subscription type. enum: - live - draft - archived example: live default_translation: "$ref": "#/components/schemas/translation" translations: type: array description: An array of translations objects with the localised version of the subscription type in each available locale within your translation settings. items: "$ref": "#/components/schemas/translation" consent_type: type: string description: Describes the type of consent. enum: - opt_out - opt_in example: opt_in content_types: type: array description: The message types that this subscription supports - can contain `email` or `sms_message`. items: type: string enum: - email - sms_message example: email subscription_type_list: title: Subscription Types type: object description: A list of subscription type objects. properties: type: type: string description: The type of the object enum: - list example: list data: type: array description: A list of subscription type objects associated with the workspace . items: "$ref": "#/components/schemas/subscription_type" tag: title: Tag type: object x-tags: - Tags description: A tag allows you to label your contacts, companies, and conversations and list them using that tag. properties: type: type: string description: value is "tag" example: tag id: type: string description: The id of the tag example: '123456' name: type: string description: The name of the tag example: Test tag applied_at: type: integer format: date-time nullable: true description: The time when the tag was applied to the object example: 1663597223 applied_by: type: object nullable: true description: The admin who applied the tag allOf: - "$ref": "#/components/schemas/reference" tag_basic: title: Tag type: object x-tags: - Tags description: A tag allows you to label your contacts, companies, and conversations and list them using that tag. properties: type: type: string description: value is "tag" example: tag id: type: string description: The id of the tag example: '123456' name: type: string description: The name of the tag example: Test tag tag_company_request: description: You can tag a single company or a list of companies. type: object title: Tag Company Request Payload properties: name: type: string description: The name of the tag, which will be created if not found. example: Independent companies: type: array items: properties: id: type: string description: The Intercom defined id representing the company. example: 531ee472cce572a6ec000006 company_id: type: string description: The company id you have defined for the company. example: '6' description: The id or company_id of the company can be passed as input parameters. required: - name - companies tag_list: title: Tags type: object description: A list of tags objects in the workspace. properties: type: type: string description: The type of the object enum: - list example: list data: type: array description: A list of tags objects associated with the workspace . items: "$ref": "#/components/schemas/tag" tag_multiple_users_request: description: You can tag a list of users. type: object title: Tag Users Request Payload properties: name: type: string description: The name of the tag, which will be created if not found. example: Independent users: type: array items: properties: id: type: string description: The Intercom defined id representing the user. example: 5f7f0d217289f8d2f4262080 required: - name - users tags: title: Tags type: object description: A list of tags objects associated with a conversation properties: type: type: string description: The type of the object enum: - tag.list example: tag.list tags: type: array description: A list of tags objects associated with the conversation. items: "$ref": "#/components/schemas/tag" team: title: Team type: object x-tags: - Teams description: Teams are groups of admins in Intercom. properties: type: type: string description: Value is always "team" example: team id: type: string description: The id of the team example: '814865' name: type: string description: The name of the team example: Example Team admin_ids: type: array description: The list of admin IDs that are a part of the team. example: - 493881 items: type: integer admin_priority_level: "$ref": "#/components/schemas/admin_priority_level" assignment_limit: type: integer nullable: true description: The assignment limit for the team. This field is only present when the team's distribution type is load balanced. example: 10 distribution_method: type: string nullable: true description: Describes how assignments are distributed among the team members example: "round_robin" team_list: title: Team List type: object description: This will return a list of team objects for the App. properties: type: type: string description: The type of the object enum: - team.list example: team.list teams: type: array description: A list of team objects items: "$ref": "#/components/schemas/team" team_priority_level: title: Team Priority Level type: object nullable: true description: Admin priority levels for teams properties: primary_team_ids: type: array description: The primary team ids for the team nullable: true example: - 814865 items: type: integer secondary_team_ids: type: array description: The secondary team ids for the team nullable: true example: - 493881 items: type: integer ticket: title: Ticket type: object x-tags: - Tickets description: Tickets are how you track requests from your users. nullable: true properties: type: type: string description: Always ticket enum: - ticket default: ticket example: ticket id: type: string description: The unique identifier for the ticket which is given by Intercom. example: '1295' ticket_id: type: string description: The ID of the Ticket used in the Intercom Inbox and Messenger. Do not use ticket_id for API queries. example: '1390' category: type: string description: Category of the Ticket. enum: - Customer - Back-office - Tracker example: Customer ticket_attributes: "$ref": "#/components/schemas/ticket_custom_attributes" ticket_state: "$ref": "#/components/schemas/ticket_state" ticket_type: "$ref": "#/components/schemas/ticket_type" contacts: "$ref": "#/components/schemas/ticket_contacts" admin_assignee_id: type: string description: The id representing the admin assigned to the ticket. example: '1295' team_assignee_id: type: string description: The id representing the team assigned to the ticket. example: '1295' created_at: type: integer format: date-time description: The time the ticket was created as a UTC Unix timestamp. example: 1663597223 updated_at: type: integer format: date-time description: The last time the ticket was updated as a UTC Unix timestamp. example: 1663597260 open: type: boolean description: Whether or not the ticket is open. If false, the ticket is closed. example: true snoozed_until: type: integer format: date-time description: The time the ticket will be snoozed until as a UTC Unix timestamp. If null, the ticket is not currently snoozed. example: 1663597260 linked_objects: "$ref": "#/components/schemas/linked_object_list" ticket_parts: "$ref": "#/components/schemas/ticket_parts" is_shared: type: boolean description: Whether or not the ticket is shared with the customer. example: true ticket_deleted: title: Ticket Deleted type: object description: deleted ticket object properties: id: type: string description: The unique identifier for the ticket. example: 5ba682d23d7cf92bef87bfd4 object: type: string description: always ticket enum: - ticket example: ticket deleted: type: boolean description: Whether the ticket is deleted or not. example: true ticket_contacts: title: Contacts type: object x-tags: - Tickets description: The list of contacts affected by a ticket. properties: type: type: string description: always contact.list enum: - contact.list example: contact.list contacts: type: array description: The list of contacts affected by this ticket. items: "$ref": "#/components/schemas/contact_reference" ticket_custom_attributes: title: Ticket Attributes type: object description: 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_`. additionalProperties: anyOf: - type: string nullable: true - type: number - type: boolean - type: array - "$ref": "#/components/schemas/file_attribute" example: _default_title_: Found a bug _default_description_: The button's not working ticket_list: title: Ticket List type: object description: Tickets are how you track requests from your users. properties: type: type: string description: Always ticket.list enum: - ticket.list example: ticket.list tickets: type: array description: The list of ticket objects items: "$ref": "#/components/schemas/ticket" total_count: type: integer description: A count of the total number of objects. example: 12345 pages: "$ref": "#/components/schemas/cursor_pages" ticket_part: title: Ticket Part type: object x-tags: - Tickets description: A Ticket Part represents a message in the ticket. properties: type: type: string description: Always ticket_part example: ticket_part id: type: string description: The id representing the ticket part. example: '3' part_type: type: string description: The type of ticket part. example: comment body: type: string nullable: true description: The message body, which may contain HTML. example: "Okay!
" previous_ticket_state: type: string enum: - submitted - in_progress - waiting_on_customer - resolved description: The previous state of the ticket. example: submitted ticket_state: type: string enum: - submitted - in_progress - waiting_on_customer - resolved description: The state of the ticket. example: submitted created_at: type: integer format: date-time description: The time the ticket part was created. example: 1663597223 updated_at: type: integer format: date-time description: The last time the ticket part was updated. example: 1663597260 assigned_to: "$ref": "#/components/schemas/reference" nullable: true description: The id of the admin that was assigned the ticket by this ticket_part (null if there has been no change in assignment.) author: "$ref": "#/components/schemas/ticket_part_author" attachments: title: Ticket part attachments type: array description: A list of attachments for the part. items: "$ref": "#/components/schemas/part_attachment" external_id: type: string nullable: true description: The external id of the ticket part example: abcd1234 redacted: type: boolean description: Whether or not the ticket part has been redacted. example: false app_package_code: type: string nullable: false example: text-integration description: The app package code if this part was created via API. Note this field won't show if the part was not created via API. updated_attribute_data: title: Updated Attribute type: object description: The updated attribute data of the ticket part. Only present for attribute update parts. nullable: true properties: attribute: type: object description: Information about the attribute that was updated. properties: type: type: string description: The type of the object. Always 'attribute'. enum: - attribute example: attribute id: type: string description: The unique identifier of the attribute. example: "7" label: type: string description: The human-readable name of the attribute. example: "Progress" required: - type - id - label value: type: object description: The new value of the attribute. properties: type: type: string description: The type of the object. Always 'value'. enum: - value example: value id: oneOf: - type: string description: The value for text/number/decimal/boolean/date attributes, or the ID of the list option for list attributes. nullable: true example: "Fast" - type: array description: Array of file IDs for file attributes. items: type: integer example: [2] label: oneOf: - type: string description: The display value for text/number/decimal/boolean/date/list attributes. example: "Fast" - type: array description: Array of file names for file attributes. items: type: string example: ["photo.png"] required: - type - id - label required: - attribute - value ticket_part_author: title: Ticket part author type: object description: The author that wrote or triggered the part. Can be a bot, admin, team or user. properties: type: type: string description: The type of the author example: admin enum: - admin - bot - team - user id: type: string description: The id of the author example: '274' name: type: string nullable: true description: The name of the author example: Operator email: type: string format: email description: The email of the author example: operator+abcd1234@intercom.io ticket_parts: title: Ticket Parts type: object description: A list of Ticket Part objects for each note and event in the ticket. There is a limit of 500 parts. properties: type: type: string description: '' enum: - ticket_part.list example: ticket_part.list ticket_parts: title: Tickt Parts type: array description: A list of Ticket Part objects for each ticket. There is a limit of 500 parts. items: "$ref": "#/components/schemas/ticket_part" total_count: type: integer description: '' example: 2 ticket_reply: title: A Ticket Part representing a note, comment, or quick_reply on a ticket type: object description: A Ticket Part representing a note, comment, or quick_reply on a ticket properties: type: type: string description: Always ticket_part example: ticket_part enum: - ticket_part id: type: string description: The id representing the part. example: '3' part_type: type: string description: Type of the part example: note enum: - note - comment - quick_reply body: type: string nullable: true description: The message body, which may contain HTML. example: "Okay!
" created_at: type: integer format: date-time description: The time the note was created. example: 1663597223 updated_at: type: integer format: date-time description: The last time the note was updated. example: 1663597260 author: "$ref": "#/components/schemas/ticket_part_author" attachments: title: Ticket part attachments type: array description: A list of attachments for the part. items: "$ref": "#/components/schemas/part_attachment" redacted: type: boolean description: Whether or not the ticket part has been redacted. example: false ticket_request_custom_attributes: title: Ticket Attributes type: object description: 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](ref:get_ticket-types). 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`). additionalProperties: anyOf: - type: string nullable: true - type: number - type: boolean - type: array example: _default_title_: Found a bug _default_description_: The button is not working ticket_state: title: Ticket State type: object x-tags: - Tickets description: A ticket state, used to define the state of a ticket. nullable: true properties: type: type: string description: String representing the object's type. Always has the value `ticket_state`. example: ticket_state id: type: string description: The id of the ticket state example: '12' category: type: string description: The category of the ticket state example: in_progress enum: - submitted - in_progress - waiting_on_customer - resolved internal_label: type: string description: The state the ticket is currently in, in a human readable form - visible in Intercom example: With Dev Team external_label: type: string description: The state the ticket is currently in, in a human readable form - visible to customers, in the messenger, email and tickets portal. example: In Progress ticket_state_detailed: title: Ticket State type: object x-tags: - Tickets description: A ticket state, used to define the state of a ticket. nullable: true properties: type: type: string description: String representing the object's type. Always has the value `ticket_state`. example: ticket_state id: type: string description: The id of the ticket state example: '12' category: type: string description: The category of the ticket state example: in_progress enum: - submitted - in_progress - waiting_on_customer - resolved internal_label: type: string description: The state the ticket is currently in, in a human readable form - visible in Intercom example: With Dev Team external_label: type: string description: The state the ticket is currently in, in a human readable form - visible to customers, in the messenger, email and tickets portal. example: In Progress archived: type: boolean description: Whether the ticket state is archived example: false ticket_types: type: object description: A list of ticket types associated with a given ticket state. properties: type: type: string description: String representing the object's type. Always has the value `list`. example: list data: type: array description: A list of ticket type attributes associated with a given ticket type. items: "$ref": "#/components/schemas/ticket_type" ticket_state_list: title: Ticket States type: object description: A list of ticket states associated with a given ticket type. properties: type: type: string description: String representing the object's type. Always has the value `list`. example: list data: type: array description: A list of ticket states associated with a given ticket type. items: "$ref": "#/components/schemas/ticket_state_detailed" ticket_type: title: Ticket Type type: object x-tags: - Tickets description: A ticket type, used to define the data fields to be captured in a ticket. nullable: true properties: type: type: string description: String representing the object's type. Always has the value `ticket_type`. example: ticket_type id: type: string description: The id representing the ticket type. example: '1295' category: type: string description: Category of the Ticket Type. enum: - Customer - Back-office - Tracker example: Customer name: type: string description: The name of the ticket type example: Bug description: type: string description: The description of the ticket type example: A bug that has been reported. icon: type: string description: The icon of the ticket type example: "\U0001F41E" workspace_id: type: string description: The id of the workspace that the ticket type belongs to. example: ecahpwf5 ticket_type_attributes: "$ref": "#/components/schemas/ticket_type_attribute_list" ticket_states: title: Ticket States type: object description: A list of ticket states associated with a given ticket type. properties: type: type: string description: String representing the object's type. Always has the value `list`. example: list data: type: array description: A list of ticket states associated with a given ticket type. items: "$ref": "#/components/schemas/ticket_state" archived: type: boolean description: Whether the ticket type is archived or not. example: false created_at: type: integer format: timestamp description: The date and time the ticket type was created. updated_at: type: integer format: timestamp description: The date and time the ticket type was last updated. ticket_type_attribute: title: Ticket Type Attribute type: object description: Ticket type attribute, used to define each data field to be captured in a ticket. nullable: true properties: type: type: string description: String representing the object's type. Always has the value `ticket_type_attribute`. example: ticket_type_attribute id: type: string description: The id representing the ticket type attribute. example: '1' workspace_id: type: string description: The id of the workspace that the ticket type attribute belongs to. example: ecahpwf5 name: type: string description: The name of the ticket type attribute example: Title description: type: string description: The description of the ticket type attribute example: Bug title. data_type: type: string description: 'The type of the data attribute (allowed values: "string list integer decimal boolean datetime files")' example: string input_options: type: object description: Input options for the attribute example: 'multiline: true' order: type: integer description: The order of the attribute against other attributes example: 1 required_to_create: type: boolean description: Whether the attribute is required or not for teammates. default: false example: false required_to_create_for_contacts: type: boolean description: Whether the attribute is required or not for contacts. default: false example: false visible_on_create: type: boolean description: Whether the attribute is visible or not to teammates. default: true example: false visible_to_contacts: type: boolean description: Whether the attribute is visible or not to contacts. default: true example: false default: type: boolean description: Whether the attribute is built in or not. example: true ticket_type_id: type: integer description: The id of the ticket type that the attribute belongs to. example: 42 archived: type: boolean description: Whether the ticket type attribute is archived or not. example: false created_at: type: integer format: timestamp description: The date and time the ticket type attribute was created. updated_at: type: integer format: timestamp description: The date and time the ticket type attribute was last updated. ticket_type_attribute_list: title: Ticket Type Attributes type: object description: A list of attributes associated with a given ticket type. properties: type: type: string description: String representing the object's type. Always has the value `ticket_type_attributes.list`. ticket_type_attributes: type: array description: A list of ticket type attributes associated with a given ticket type. items: "$ref": "#/components/schemas/ticket_type_attribute" ticket_type_list: title: Ticket Types type: object description: A list of ticket types associated with a given workspace. properties: type: type: string description: String representing the object's type. Always has the value `list`. example: list data: type: array description: A list of ticket_types associated with a given workspace. items: "$ref": "#/components/schemas/ticket_type" translation: title: Translation type: object description: A translation object contains the localised details of a subscription type. properties: name: type: string description: The localised name of the subscription type. example: Announcements description: type: string description: The localised description of the subscription type. example: Offers, product and feature announcements locale: type: string description: The two character identifier for the language of the translation object. example: en untag_company_request: description: You can tag a single company or a list of companies. type: object title: Untag Company Request Payload properties: name: type: string description: The name of the tag which will be untagged from the company example: Independent companies: type: array items: properties: id: type: string description: The Intercom defined id representing the company. example: 531ee472cce572a6ec000006 company_id: type: string description: The company id you have defined for the company. example: '6' untag: type: boolean description: Always set to true example: 'true' description: The id or company_id of the company can be passed as input parameters. required: - name - companies update_article_request: description: You can Update an Article type: object title: Update Article Request Payload nullable: true properties: title: type: string description: The title of the article.For multilingual articles, this will be the title of the default language's content. example: Thanks for everything description: type: string description: The description of the article. For multilingual articles, this will be the description of the default language's content. example: Description of the Article body: type: string description: The content of the article. For multilingual articles, this will be the body of the default language's content. example: "This is the body in html
" author_id: type: integer description: 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 state: type: string description: 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_id: type: string description: The id of the article's parent collection or section. An article without this field stands alone. example: '18' parent_type: type: string description: The type of parent, which can either be a `collection` or `section`. example: collection translated_content: "$ref": "#/components/schemas/article_translated_content" update_internal_article_request: description: You can Update an Internal Article type: object title: Update Internal Article Request Payload nullable: true properties: title: type: string description: The title of the article. example: Thanks for everything body: type: string description: The content of the article. author_id: type: integer description: The id of the author of the article. example: 1295 owner_id: type: integer description: The id of the author of the article. example: 1295 update_collection_request: description: You can update a collection type: object title: Update Collection Request Payload properties: name: type: string description: The name of the collection. For multilingual collections, this will be the name of the default language's content. example: collection 51 description: type: string description: The description of the collection. For multilingual collections, this will be the description of the default language's content. example: English description translated_content: nullable: true "$ref": "#/components/schemas/group_translated_content" parent_id: type: string nullable: true description: The id of the parent collection. If `null` then it will be updated as the first level collection. example: '6871118' update_contact_request: description: You can update a contact type: object title: Update Contact Request Payload properties: role: type: string description: The role of the contact. external_id: type: string description: A unique identifier for the contact which is given to Intercom email: type: string description: The contacts email example: jdoe@example.com phone: type: string nullable: true description: The contacts phone example: "+353871234567" name: type: string nullable: true description: The contacts name example: John Doe avatar: type: string nullable: true description: An image URL containing the avatar of a contact example: https://www.example.com/avatar_image.jpg signed_up_at: type: integer format: date-time nullable: true description: The time specified for when a contact signed up example: 1571672154 last_seen_at: type: integer format: date-time nullable: true description: The time when the contact was last seen (either where the Intercom Messenger was installed or when specified manually) example: 1571672154 owner_id: type: integer nullable: true description: The id of an admin that has been assigned account ownership of the contact example: 123 unsubscribed_from_emails: type: boolean nullable: true description: Whether the contact is unsubscribed from emails example: true custom_attributes: type: object nullable: true description: The custom attributes which are set for the contact update_content_import_source_request: title: Create Content Import Source Payload type: object description: You can modify a Content Import Source of your Fin Content Library. nullable: false properties: sync_behavior: type: string description: 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. enum: - api - automated - manual example: api status: type: string description: The status of the content import source. enum: - active - deactivated default: active example: active url: type: string description: The URL of the content import source. This may only be different from the existing value if the sync behavior is API. example: https://help.example.com required: - sync_behavior - url update_conversation_request: title: Update Conversation Request type: object description: Payload of the request to update a conversation properties: read: type: boolean description: Mark a conversation as read within Intercom. example: true title: type: string description: The title given to the conversation example: Conversation Title custom_attributes: "$ref": "#/components/schemas/custom_attributes" company_id: type: string description: The ID of the company that the conversation is associated with. The unique identifier for the company which is given by Intercom. Set to nil to remove company. example: 5f4d3c1c-7b1b-4d7d-a97e-6095715c6632 update_data_attribute_request: description: '' type: object title: Update Data Attribute Request properties: archived: type: boolean description: Whether the attribute is to be archived or not. example: false description: type: string description: The readable description you see in the UI for the attribute. example: My Data Attribute Description messenger_writable: type: boolean description: Can this attribute be updated by the Messenger example: false oneOf: - properties: options: type: array description: Array of objects representing the options of the list, with `value` as the key and the option as the value. At least two options are required. items: type: object properties: value: type: string example: - value: 1-10 - value: 11-50 required: - options title: 'list attribute' - title: 'other type' update_external_page_request: title: Update External Page Payload type: object description: You can update an External Page in your Fin Content Library. nullable: false properties: title: type: string description: The title of the external page. example: Getting started with... html: type: string description: The body of the external page in HTML. example: "Hello world!
" url: type: string description: The URL of the external page. This will be used by Fin to link end users to the page it based its answer on. example: https://help.example.com/en/articles/1234-getting-started fin_availability: type: boolean description: Whether the external page should be used to answer questions by Fin. default: true example: true locale: type: string description: Always en enum: - en default: en example: en source_id: type: integer description: 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. example: 1234 external_id: type: string description: The identifier for the external page which was given by the source. Must be unique for the source. example: '5678' required: - title - html - url - locale - source_id update_ticket_request: description: You can update a Ticket type: object title: Update Ticket Request Payload properties: ticket_attributes: type: object description: The attributes set on the ticket. example: _default_title_: example _default_description_: having a problem ticket_state_id: type: string description: The ID of the ticket state associated with the ticket type. example: '123' company_id: type: string description: The ID of the company that the ticket is associated with. The unique identifier for the company which is given by Intercom. Set to nil to remove company. example: 5f4d3c1c-7b1b-4d7d-a97e-6095715c6632 open: type: boolean description: Specify if a ticket is open. Set to false to close a ticket. Closing a ticket will also unsnooze it. example: true is_shared: type: boolean description: Specify whether the ticket is visible to users. example: true snoozed_until: type: integer format: timestamp description: The time you want the ticket to reopen. example: 1673609604 admin_id: type: integer description: The ID of the admin performing ticket update. Needed for workflows execution and attributing actions to specific admins. example: 123 assignee_id: type: string description: The ID of the admin or team to which the ticket is assigned. Set this 0 to unassign it. example: '123' update_ticket_type_attribute_request: description: You can update a Ticket Type Attribute type: object title: Update Ticket Type Attribute Request Payload properties: name: type: string description: The name of the ticket type attribute example: Bug Priority description: type: string description: The description of the attribute presented to the teammate or contact example: Priority level of the bug required_to_create: type: boolean description: 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_contacts: type: boolean description: Whether the attribute is required to be filled in when contacts are creating the ticket in Messenger. default: false example: false visible_on_create: type: boolean description: Whether the attribute is visible to teammates when creating a ticket in Inbox. default: true example: true visible_to_contacts: type: boolean description: Whether the attribute is visible to contacts when creating a ticket in Messenger. default: true example: true multiline: type: boolean description: Whether the attribute allows multiple lines of text (only applicable to string attributes) example: false list_items: type: string description: A comma delimited list of items for the attribute value (only applicable to list attributes) example: Low Priority,Medium Priority,High Priority allow_multiple_values: type: boolean description: Whether the attribute allows multiple files to be attached to it (only applicable to file attributes) example: false archived: type: boolean description: 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 update_ticket_type_request: description: | The request payload for updating a ticket type. You can copy the `icon` property for your ticket type from [Twemoji Cheatsheet](https://twemoji-cheatsheet.vercel.app/) type: object title: Update Ticket Type Request Payload nullable: true properties: name: type: string description: The name of the ticket type. example: Bug description: type: string description: The description of the ticket type. example: A bug has been occured category: type: string description: Category of the Ticket Type. enum: - Customer - Back-office - Tracker example: Customer icon: type: string description: The icon of the ticket type. example: "\U0001F41E" default: "\U0001F39F️" archived: type: boolean description: The archived status of the ticket type. example: false is_internal: type: boolean description: 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. example: false default: false update_visitor_request: description: Update an existing visitor. type: object title: Update Visitor Request Payload properties: id: type: string description: A unique identified for the visitor which is given by Intercom. example: 8a88a590-e user_id: type: string description: A unique identified for the visitor which is given by you. example: '123' name: type: string description: The visitor's name. example: Christian Bale custom_attributes: type: object description: The custom attributes which are set for the visitor. additionalProperties: type: string example: paid_subscriber: true monthly_spend: 155.5 team_mates: 9 anyOf: - required: - id - required: - user_id visitor: title: Visitor type: object description: 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. nullable: true properties: type: type: string description: Value is 'visitor' default: visitor example: visitor id: type: string description: The Intercom defined id representing the Visitor. example: 530370b477ad7120001d user_id: type: string description: Automatically generated identifier for the Visitor. example: 8a88a590-e1c3-41e2-a502-e0649dbf721c anonymous: type: boolean description: Identifies if this visitor is anonymous. example: false email: type: string format: email description: The email of the visitor. example: jane.doe@example.com phone: type: string nullable: true description: The phone number of the visitor. example: 555-555-5555 name: type: string nullable: true description: The name of the visitor. example: Jane Doe pseudonym: type: string nullable: true description: The pseudonym of the visitor. example: Red Duck from Dublin avatar: type: object properties: type: type: string description: '' default: avatar example: avatar image_url: type: string format: uri nullable: true description: This object represents the avatar associated with the visitor. example: https://example.com/avatar.png app_id: type: string description: The id of the app the visitor is associated with. example: hfi1bx4l companies: type: object properties: type: type: string description: The type of the object enum: - company.list example: company.list companies: type: array items: "$ref": "#/components/schemas/company" location_data: type: object properties: type: type: string description: '' default: location_data example: location_data city_name: type: string description: The city name of the visitor. example: Dublin continent_code: type: string description: The continent code of the visitor. example: EU country_code: type: string description: The country code of the visitor. example: IRL country_name: type: string description: The country name of the visitor. example: Ireland postal_code: type: string description: The postal code of the visitor. example: D02 N960 region_name: type: string description: The region name of the visitor. example: Leinster timezone: type: string description: The timezone of the visitor. example: Europe/Dublin las_request_at: type: integer description: The time the Lead last recorded making a request. example: 1663597260 created_at: type: integer description: The time the Visitor was added to Intercom. example: 1663597223 remote_created_at: type: integer description: The time the Visitor was added to Intercom. example: 1663597223 signed_up_at: type: integer description: The time the Visitor signed up for your product. example: 1663597223 updated_at: type: integer description: The last time the Visitor was updated. example: 1663597260 session_count: type: integer description: The number of sessions the Visitor has had. example: 1 social_profiles: type: object properties: type: type: string description: The type of the object enum: - social_profile.list example: social_profile.list social_profiles: type: array items: type: string owner_id: type: string nullable: true description: The id of the admin that owns the Visitor. example: '5169261' unsubscribed_from_emails: type: boolean description: Whether the Visitor is unsubscribed from emails. example: false marked_email_as_spam: type: boolean description: Identifies if this visitor has marked an email as spam. example: false has_hard_bounced: type: boolean description: Identifies if this visitor has had a hard bounce. example: false tags: type: object properties: type: type: string description: The type of the object enum: - tag.list example: tag.list tags: type: array items: properties: type: type: string description: The type of the object enum: - tag example: tag id: type: string description: The id of the tag. example: '8482' name: type: string description: The name of the tag. example: tag_name segments: type: object properties: type: type: string description: The type of the object enum: - segment.list example: segment.list segments: type: array items: type: string custom_attributes: type: object description: The custom attributes you have set on the Visitor. additionalProperties: type: string referrer: type: string nullable: true description: The referer of the visitor. example: https://www.google.com/ utm_campaign: type: string nullable: true description: The utm_campaign of the visitor. example: intercom-link utm_content: type: string nullable: true description: The utm_content of the visitor. example: banner utm_medium: type: string nullable: true description: The utm_medium of the visitor. example: email utm_source: type: string nullable: true description: The utm_source of the visitor. example: Intercom utm_term: type: string nullable: true description: The utm_term of the visitor. example: messenger do_not_track: type: boolean nullable: true description: Identifies if this visitor has do not track enabled. example: false visitor_deleted_object: title: Visitor Deleted Object type: object description: Response returned when an object is deleted properties: id: type: string description: The unique identifier for the visitor which is given by Intercom. example: 530370b477ad7120001d type: type: string description: The type of object which was deleted enum: - visitor example: visitor user_id: type: string description: Automatically generated identifier for the Visitor. example: 8a88a590-e1c3-41e2-a502-e0649dbf721c workflow_export: title: Workflow Export type: object description: A workflow export containing the complete workflow configuration. properties: export_version: type: string description: The version of the export format. example: "1.0" exported_at: type: string format: date-time description: The timestamp when the export was generated. example: "2026-01-26T12:00:00Z" app_id: type: integer description: The workspace identifier. example: 12345 workflow: type: object description: The workflow configuration. properties: id: type: string description: The unique identifier for the workflow. example: "67890" title: type: string description: The title of the workflow. example: "My Workflow" description: type: string nullable: true description: The description of the workflow. example: "A workflow that handles customer inquiries" trigger_type: type: string description: The type of trigger that starts this workflow. example: "inbound_conversation" state: type: string description: The current state of the workflow. enum: - live - draft - paused example: "live" target_channels: type: array items: type: string description: The channels this workflow targets. example: ["chat"] preferred_devices: type: array items: type: string description: The preferred devices for this workflow. example: ["desktop", "mobile"] created_at: type: string format: date-time description: When the workflow was created. example: "2025-06-15T10:30:00Z" updated_at: type: string format: date-time description: When the workflow was last updated. example: "2026-01-20T14:45:00Z" targeting: type: object nullable: true description: The targeting rules for this workflow. snapshot: type: object nullable: true description: The current snapshot of workflow steps and configuration. attributes: type: array items: type: object description: Custom attributes defined for this workflow. embedded_rules: type: array items: type: object description: Rules embedded within the workflow steps. securitySchemes: bearerAuth: type: http scheme: bearer responses: Unauthorized: description: Unauthorized content: application/json: examples: Unauthorized: value: type: error.list request_id: 12a938a3-314e-4939-b773-5cd45738bd21 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" TypeNotFound: description: Not Found content: application/json: examples: TypeNotFound: value: type: error.list request_id: 12a938a3-314e-4939-b773-5cd45738bd21 errors: - code: not_found message: Custom object type `undefined` not found schema: "$ref": "#/components/schemas/error" ObjectNotFound: description: Not Found content: application/json: examples: ObjectNotFound: value: type: error.list request_id: 12a938a3-314e-4939-b773-5cd45738bd21 errors: - code: not_found message: Object not found CustomObjectNotFound: value: type: error.list request_id: 12a938a3-314e-4939-b773-5cd45738bd21 errors: - code: not_found message: Custom object instance not found IntegrationNotFound: value: type: error.list request_id: 12a938a3-314e-4939-b773-5cd45738bd21 errors: - code: data_invalid message: Integration not found schema: "$ref": "#/components/schemas/error" ValidationError: description: Validation Error content: application/json: examples: ValidationError: value: type: error.list request_id: 12a938a3-314e-4939-b773-5cd45738bd21 errors: - code: data_invalid message: Invalid or duplicated record reference schema: "$ref": "#/components/schemas/error" BadRequest: description: Bad Request content: application/json: examples: BadRequest: value: type: error.list request_id: 12a938a3-314e-4939-b773-5cd45738bd21 errors: - code: data_invalid message: Contact not found or could not be created schema: "$ref": "#/components/schemas/error" CustomChannelNotificationSuccess: description: Successfully notified Intercom content: application/json: schema: $ref: '#/components/schemas/custom_channel_notification_response' examples: NotificationSuccess: value: external_conversation_id: "customer_conversation_id_12" conversation_id: "intercom_conversation_id_34" external_contact_id: "customer_contact_id_56" contact_id: "intercom_contact_id_79" servers: - url: https://api.intercom.io description: The production API server - url: https://api.eu.intercom.io description: The european API server - url: https://api.au.intercom.io description: The australian API server security: - bearerAuth: [] tags: - name: Admins description: Everything about your Admins - name: AI Content description: | 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.", - name: Articles description: Everything about your Articles - name: Away Status Reasons description: Everything about your Away Status Reasons - name: Brands description: Everything about your Brands - name: Companies description: Everything about your Companies - name: Contacts description: Everything about your contacts - name: Conversations description: Everything about your Conversations externalDocs: description: What is a conversation? url: https://www.intercom.com/help/en/articles/4323904-what-is-a-conversation - name: Custom Channel Events description: | With the "Custom Channel" integration, you can bring Fin and Intercom capabilities to your own platform via API, enabling powerful custom integrations. Intercom treats your integration like any other Intercom channel, allowing your application and Intercom to exchange events seamlessly. This makes it possible, for example, for your users to interact with Fin directly within your own application’s UI. > **Note:** "Fin over API" is currently under managed availability. Please reach out to your accounts team to discuss access and tailored, hands-on support. - name: Custom Object Instances description: | Everything about your Custom Object instances. {% admonition type="warning" name="Permission Requirements" %} From now on, to access this endpoint, you need additional permissions. Please head over to the [Developer Hub](https://app.intercom.com/a/apps/_/developer-hub) app package authentication settings to configure the required permissions. {% /admonition %} - name: Data Attributes description: Everything about your Data Attributes - name: Data Events description: Everything about your Data Events - name: Data Export description: Everything about your Data Exports - name: Emails description: Everything about your Email Settings - name: Help Center description: Everything about your Help Center - name: Internal Articles description: Everything about your Internal Articles - name: IP Allowlist description: | Manage IP allowlist settings for your workspace. The IP Allowlist API allows you to configure which IP addresses are allowed to access the Intercom API and web application for your workspace. This is useful for restricting access to your Intercom workspace to specific corporate networks or VPNs. {% admonition type="info" name="Authentication" %} This endpoint requires the `manage_ip_allowlist` OAuth scope. {% /admonition %} - name: Jobs description: Everything about jobs - name: Messages description: Everything about your messages - name: News description: Everything about your News externalDocs: description: News explained url: https://www.intercom.com/help/en/articles/6362251-news-explained - name: Notes description: Everything about your Notes - name: Segments description: Everything about your Segments - name: Subscription Types description: Everything about subscription types - name: Switch description: Everything about Switch externalDocs: description: 'Meet Switch: from on hold to messaging in just a few taps' url: https://www.intercom.com/switch - name: Tags description: Everything about tags - name: Teams description: Everything about your Teams - name: Ticket States description: Everything about your ticket states - name: Ticket Type Attributes description: Everything about your ticket type attributes - name: Ticket Types description: Everything about your ticket types - name: Tickets description: Everything about your tickets - name: Visitors description: Everything about your Visitors - name: Workflows description: Everything about your Workflows