From 23d04ac6307e655d69a7279652aa7e1b6ccdd32b Mon Sep 17 00:00:00 2001 From: Niels Swimberghe <3382717+Swimburger@users.noreply.github.com> Date: Thu, 19 Dec 2024 15:07:05 -0500 Subject: [PATCH 1/2] Update OpenAPI spec and Fern generators --- descriptions/2.11/api.intercom.io.yaml | 6540 +++++++++++++----------- fern/fern.config.json | 2 +- fern/generators.yml | 17 +- fern/openapi-overrides.yml | 619 ++- 4 files changed, 4072 insertions(+), 3106 deletions(-) diff --git a/descriptions/2.11/api.intercom.io.yaml b/descriptions/2.11/api.intercom.io.yaml index 1c832cb..678f499 100644 --- a/descriptions/2.11/api.intercom.io.yaml +++ b/descriptions/2.11/api.intercom.io.yaml @@ -56,24 +56,18 @@ paths: has_inbox_seat: true schema: "$ref": "#/components/schemas/admin_with_app" - "/admins/{id}/away": - put: - summary: Set an admin to away + "/admins": + get: + summary: List all admins parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: id - in: path - required: true - description: The unique identifier of a given admin - schema: - type: integer tags: - Admins - operationId: setAwayAdmin - description: You can set an Admin as away for the Inbox. + operationId: listAdmins + description: You can fetch a list of admins for a given workspace. responses: '200': description: Successful response @@ -82,30 +76,18 @@ paths: examples: Successful response: value: - type: admin - id: '991267391' - name: Ciaran2 Lee - email: admin2@email.com - away_mode_enabled: true - away_mode_reassign: true - has_inbox_seat: true - team_ids: [] - schema: - "$ref": "#/components/schemas/admin" - '404': - description: Admin not found - content: - application/json: - examples: - Admin not found: - value: - type: error.list - request_id: 9818bd03-9cc6-4ab8-8e7c-20a45ac58e97 - errors: - - code: admin_not_found - message: Admin for admin_id not found + type: admin.list + admins: + - type: admin + email: admin7@email.com + id: '991267397' + name: Ciaran7 Lee + away_mode_enabled: false + away_mode_reassign: false + has_inbox_seat: true + team_ids: [] schema: - "$ref": "#/components/schemas/error" + "$ref": "#/components/schemas/admin_list" '401': description: Unauthorized content: @@ -114,49 +96,12 @@ paths: Unauthorized: value: type: error.list - request_id: 18722269-a019-46c4-87d7-50d0f6f8a990 + request_id: 4ba8121e-4a4a-4668-adb2-363c561f3c52 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" - requestBody: - content: - application/json: - schema: - type: object - required: - - away_mode_enabled - - away_mode_reassign - properties: - away_mode_enabled: - type: boolean - description: Set to "true" to change the status of the admin to - away. - example: true - default: true - away_mode_reassign: - type: boolean - description: Set to "true" to assign any new conversation replies - to your default inbox. - example: false - default: false - examples: - successful_response: - summary: Successful response - value: - away_mode_enabled: true - away_mode_reassign: true - admin_not_found: - summary: Admin not found - value: - away_mode_enabled: true - away_mode_reassign: true - unauthorized: - summary: Unauthorized - value: - away_mode_enabled: true - away_mode_reassign: true "/admins/activity_logs": get: summary: List all activity logs @@ -247,38 +192,57 @@ paths: message: Access Token Invalid schema: "$ref": "#/components/schemas/error" - "/admins": + "/admins/{admin_id}": get: - summary: List all admins + summary: Retrieve an admin parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" + - name: admin_id + in: path + required: true + description: The unique identifier of a given admin + example: "123" + schema: + type: string tags: - Admins - operationId: listAdmins - description: You can fetch a list of admins for a given workspace. + operationId: retrieveAdmin + description: You can retrieve the details of a single admin. responses: '200': - description: Successful response + description: Admin found content: application/json: examples: - Successful response: + Admin found: value: - type: admin.list - admins: - - type: admin - email: admin7@email.com - id: '991267397' - name: Ciaran7 Lee - away_mode_enabled: false - away_mode_reassign: false - has_inbox_seat: true - team_ids: [] + type: admin + id: '991267399' + name: Ciaran9 Lee + email: admin9@email.com + away_mode_enabled: false + away_mode_reassign: false + has_inbox_seat: true + team_ids: [] schema: - "$ref": "#/components/schemas/admin_list" + "$ref": "#/components/schemas/admin" + '404': + description: Admin not found + content: + application/json: + examples: + Admin not found: + value: + type: error.list + request_id: 989bdb0b-1e8c-46cc-8953-9733dad40562 + errors: + - code: admin_not_found + message: Admin not found + schema: + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -287,45 +251,44 @@ paths: Unauthorized: value: type: error.list - request_id: 4ba8121e-4a4a-4668-adb2-363c561f3c52 + request_id: 83978032-1473-4696-b755-b497d46a23cf errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" - "/admins/{id}": - get: - summary: Retrieve an admin + "/admins/{admin_id}/away": + put: + summary: Set an admin to away parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: id + - name: admin_id in: path required: true description: The unique identifier of a given admin - example: 123 schema: - type: integer + type: string tags: - Admins - operationId: retrieveAdmin - description: You can retrieve the details of a single admin. + operationId: setAwayAdmin + description: You can set an Admin as away for the Inbox. responses: '200': - description: Admin found + description: Successful response content: application/json: examples: - Admin found: + Successful response: value: type: admin - id: '991267399' - name: Ciaran9 Lee - email: admin9@email.com - away_mode_enabled: false - away_mode_reassign: false + id: '991267391' + name: Ciaran2 Lee + email: admin2@email.com + away_mode_enabled: true + away_mode_reassign: true has_inbox_seat: true team_ids: [] schema: @@ -338,10 +301,10 @@ paths: Admin not found: value: type: error.list - request_id: 989bdb0b-1e8c-46cc-8953-9733dad40562 + request_id: 9818bd03-9cc6-4ab8-8e7c-20a45ac58e97 errors: - code: admin_not_found - message: Admin not found + message: Admin for admin_id not found schema: "$ref": "#/components/schemas/error" '401': @@ -352,12 +315,49 @@ paths: Unauthorized: value: type: error.list - request_id: 83978032-1473-4696-b755-b497d46a23cf + request_id: 18722269-a019-46c4-87d7-50d0f6f8a990 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" + requestBody: + content: + application/json: + schema: + type: object + required: + - away_mode_enabled + - away_mode_reassign + properties: + away_mode_enabled: + type: boolean + description: Set to "true" to change the status of the admin to + away. + example: true + default: true + away_mode_reassign: + type: boolean + description: Set to "true" to assign any new conversation replies + to your default inbox. + example: false + default: false + examples: + successful_response: + summary: Successful response + value: + away_mode_enabled: true + away_mode_reassign: true + admin_not_found: + summary: Admin not found + value: + away_mode_enabled: true + away_mode_reassign: true + unauthorized: + summary: Unauthorized + value: + away_mode_enabled: true + away_mode_reassign: true "/articles": get: summary: List all articles @@ -366,6 +366,20 @@ paths: 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 15 + example: 15 + schema: + type: integer tags: - Articles operationId: listArticles @@ -522,25 +536,115 @@ paths: description: Description of the Article body: Body of the Article state: published - "/articles/{id}": + "/articles/search": get: - summary: Retrieve an article + summary: Search for articles parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: id - in: path - required: true - description: The unique identifier for the article which is given by Intercom. + - name: phrase + in: query + required: false + description: The phrase within your articles to search for. + example: Getting started + schema: + type: string + - name: state + in: query + required: false + description: The state of the Articles returned. One of `published`, `draft` + or `all`. + example: published + schema: + type: string + - name: help_center_id + in: query + required: false + description: The ID of the Help Center to search in. example: 123 schema: type: integer + - name: highlight + in: query + required: false + description: Return a highlighted version of the matching content within your + articles. Refer to the response schema for more details. + example: false + schema: + type: boolean tags: - Articles - operationId: retrieveArticle - description: You can fetch the details of a single article by making a GET request + operationId: searchArticles + description: You can search for articles by making a GET request to `https://api.intercom.io/articles/search`. + responses: + '200': + description: Search successful + content: + application/json: + examples: + Search successful: + value: + type: list + total_count: 1 + data: + articles: + - id: '55' + type: article + workspace_id: this_is_an_id61_that_should_be_at_least_4 + parent_id: + parent_type: + parent_ids: [] + title: Title 1 + description: '' + body: '' + author_id: 991267431 + state: draft + created_at: 1719492719 + updated_at: 1719492719 + url: + highlights: [] + pages: + type: pages + page: 1 + total_pages: 1 + per_page: 10 + schema: + "$ref": "#/components/schemas/search_articles_response" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: 626c6766-ee1a-489d-b87a-230d9b980c7d + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + "/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: string + 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/`. responses: '200': @@ -609,13 +713,13 @@ paths: in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: id + - name: article_id in: path required: true description: The unique identifier for the article which is given by Intercom. - example: 123 + example: "123" schema: - type: integer + type: string tags: - Articles operationId: updateArticle @@ -685,7 +789,7 @@ paths: content: application/json: schema: - "$ref": "#/components/schemas/update_article_request" + "$ref": "#/components/schemas/update_article_request_body" examples: successful: summary: successful @@ -704,13 +808,13 @@ paths: in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: id + - name: article_id in: path required: true description: The unique identifier for the article which is given by Intercom. - example: 123 + example: "123" schema: - type: integer + type: string tags: - Articles operationId: deleteArticle @@ -756,104 +860,28 @@ paths: message: Access Token Invalid schema: "$ref": "#/components/schemas/error" - "/articles/search": + "/help_center/collections": get: - summary: Search for articles + summary: List all collections parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: phrase - in: query - required: false - description: The phrase within your articles to search for. - example: Getting started - schema: - type: string - - name: state - in: query - required: false - description: The state of the Articles returned. One of `published`, `draft` - or `all`. - example: published - schema: - type: string - - name: help_center_id + - name: page in: query required: false - description: The ID of the Help Center to search in. - example: 123 + description: The page of results to fetch. Defaults to first page + example: 1 schema: type: integer - - name: highlight + - name: per_page in: query required: false - description: Return a highlighted version of the matching content within your - articles. Refer to the response schema for more details. - example: false - schema: - type: boolean - tags: - - Articles - operationId: searchArticles - description: You can search for articles by making a GET request to `https://api.intercom.io/articles/search`. - responses: - '200': - description: Search successful - content: - application/json: - examples: - Search successful: - value: - type: list - total_count: 1 - data: - articles: - - id: '55' - type: article - workspace_id: this_is_an_id61_that_should_be_at_least_4 - parent_id: - parent_type: - parent_ids: [] - title: Title 1 - description: '' - body: '' - author_id: 991267431 - state: draft - created_at: 1719492719 - updated_at: 1719492719 - url: - highlights: [] - pages: - type: pages - page: 1 - total_pages: 1 - per_page: 10 - schema: - "$ref": "#/components/schemas/article_search_response" - '401': - description: Unauthorized - content: - application/json: - examples: - Unauthorized: - value: - type: error.list - request_id: 626c6766-ee1a-489d-b87a-230d9b980c7d - errors: - - code: unauthorized - message: Access Token Invalid - schema: - "$ref": "#/components/schemas/error" - "/help_center/collections": - get: - summary: List all collections - parameters: - - name: Intercom-Version - in: header + description: How many results to display per page. Defaults to 15 + example: 15 schema: - "$ref": "#/components/schemas/intercom_version" + type: integer tags: - Help Center operationId: listAllCollections @@ -989,7 +1017,7 @@ paths: summary: Bad Request value: description: Missing required parameter - "/help_center/collections/{id}": + "/help_center/collections/{collection_id}": get: summary: Retrieve a collection parameters: @@ -997,13 +1025,13 @@ paths: in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: id + - name: collection_id in: path required: true description: The unique identifier for the collection which is given by Intercom. - example: 123 + example: "123" schema: - type: integer + type: string tags: - Help Center operationId: retrieveCollection @@ -1065,13 +1093,13 @@ paths: in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: id + - name: collection_id in: path required: true description: The unique identifier for the collection which is given by Intercom. - example: 123 + example: "123" schema: - type: integer + type: string tags: - Help Center operationId: updateCollection @@ -1147,13 +1175,13 @@ paths: in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: id + - name: collection_id in: path required: true description: The unique identifier for the collection which is given by Intercom. - example: 123 + example: "123" schema: - type: integer + type: string tags: - Help Center operationId: deleteCollection @@ -1200,7 +1228,59 @@ paths: message: Access Token Invalid schema: "$ref": "#/components/schemas/error" - "/help_center/help_centers/{id}": + "/help_center/help_centers": + get: + summary: List all Help Centers + 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 15 + example: 15 + schema: + type: integer + tags: + - Help Center + operationId: listHelpCenters + description: You can list all Help Centers by making a GET request to `https://api.intercom.io/help_center/help_centers`. + responses: + '200': + description: Help Centers found + content: + application/json: + examples: + Help Centers found: + value: + type: list + data: [] + schema: + "$ref": "#/components/schemas/help_center_list" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: c96a4779-a06d-45bb-aa39-eb96c587c2c7 + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + "/help_center/help_centers/{help_center_id}": get: summary: Retrieve a Help Center parameters: @@ -1208,13 +1288,13 @@ paths: in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: id + - name: help_center_id in: path required: true - description: The unique identifier for the collection which is given by Intercom. - example: 123 + description: The unique identifier for the Help Center which is given by Intercom. + example: "123" schema: - type: integer + type: string tags: - Help Center operationId: retrieveHelpCenter @@ -1265,72 +1345,34 @@ paths: message: Access Token Invalid schema: "$ref": "#/components/schemas/error" - "/help_center/help_centers": - get: - summary: List all Help Centers + "/companies": + post: + summary: Create or Update a company parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" tags: - - Help Center - operationId: listHelpCenters - description: You can list all Help Centers by making a GET request to `https://api.intercom.io/help_center/help_centers`. + - Companies + operationId: createOrUpdateCompany + description: | + You can create or update a company. + + Companies will be only visible in Intercom when there is at least one associated user. + + Companies are looked up via `company_id` in a `POST` request, if not found via `company_id`, the new company will be created, if found, that company will be updated. + + {% admonition type="attention" name="Using `company_id`" %} + You can set a unique `company_id` value when creating a company. However, it is not possible to update `company_id`. Be sure to set a unique value once upon creation of the company. + {% /admonition %} responses: '200': - description: Help Centers found + description: Successful content: application/json: examples: - Help Centers found: - value: - type: list - data: [] - schema: - "$ref": "#/components/schemas/help_center_list" - '401': - description: Unauthorized - content: - application/json: - examples: - Unauthorized: - value: - type: error.list - request_id: c96a4779-a06d-45bb-aa39-eb96c587c2c7 - errors: - - code: unauthorized - message: Access Token Invalid - schema: - "$ref": "#/components/schemas/error" - "/companies": - post: - summary: Create or Update a company - parameters: - - name: Intercom-Version - in: header - schema: - "$ref": "#/components/schemas/intercom_version" - tags: - - Companies - operationId: createOrUpdateCompany - description: | - You can create or update a company. - - Companies will be only visible in Intercom when there is at least one associated user. - - Companies are looked up via `company_id` in a `POST` request, if not found via `company_id`, the new company will be created, if found, that company will be updated. - - {% admonition type="attention" name="Using `company_id`" %} - You can set a unique `company_id` value when creating a company. However, it is not possible to update `company_id`. Be sure to set a unique value once upon creation of the company. - {% /admonition %} - responses: - '200': - description: Successful - content: - application/json: - examples: - Successful: + Successful: value: type: company company_id: company_remote_id @@ -1528,7 +1570,7 @@ paths: message: Access Token Invalid schema: "$ref": "#/components/schemas/error" - "/companies/{id}": + "/companies/{company_id}": get: summary: Retrieve a company by ID parameters: @@ -1536,7 +1578,7 @@ paths: in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: id + - name: company_id in: path required: true description: The unique identifier for the company which is given by Intercom @@ -1611,7 +1653,7 @@ paths: in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: id + - name: company_id in: path required: true description: The unique identifier for the company which is given by Intercom @@ -1691,7 +1733,7 @@ paths: in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: id + - name: company_id in: path required: true description: The unique identifier for the company which is given by Intercom @@ -1743,7 +1785,7 @@ paths: message: Access Token Invalid schema: "$ref": "#/components/schemas/error" - "/companies/{id}/contacts": + "/companies/{company_id}/contacts": get: summary: List attached contacts parameters: @@ -1751,13 +1793,27 @@ paths: in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: id + - name: company_id in: path required: true description: The unique identifier for the company which is given by Intercom example: 5f4d3c1c-7b1b-4d7d-a97e-6095715c6632 schema: type: string + - 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 tags: - Companies - Contacts @@ -1809,7 +1865,7 @@ paths: message: Access Token Invalid schema: "$ref": "#/components/schemas/error" - "/companies/{id}/segments": + "/companies/{company_id}/segments": get: summary: List attached segments for companies parameters: @@ -1817,7 +1873,7 @@ paths: in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: id + - name: company_id in: path required: true description: The unique identifier for the company which is given by Intercom @@ -2044,82 +2100,61 @@ paths: message: Access Token Invalid schema: "$ref": "#/components/schemas/error" - "/contacts/{id}/companies": - post: - summary: Attach a Contact to a Company + "/contacts": + get: + summary: List all contacts parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: id - in: path - required: true - description: The unique identifier for the contact which is given by Intercom + - 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 15 + example: 15 + schema: + type: integer + - name: starting_after + in: query + required: false + description: String used to get the next page of conversations. schema: type: string tags: - - Companies - Contacts - operationId: attachContactToACompany - description: You can attach a company to a single contact. + operationId: ListContacts + description: | + You can fetch a list of all contacts (ie. users or leads) in your workspace. + {% admonition type="warning" name="Pagination" %} + You can use 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/#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: company - company_id: '1' - id: 667d608d8a68186f43bafd70 - app_id: this_is_an_id166_that_should_be_at_least_ - name: company6 - remote_created_at: 1719492749 - created_at: 1719492749 - updated_at: 1719492749 - 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: 9297dcfc-1896-43a3-a3f9-131238422ed2 - errors: - - code: parameter_not_found - message: company not specified - schema: - "$ref": "#/components/schemas/error" - '404': - description: Company Not Found + description: successful content: application/json: examples: - Company Not Found: + successful: value: - type: error.list - request_id: 32d121d8-fcbf-4c59-9c60-204f7d602f36 - errors: - - code: company_not_found - message: Company Not Found + type: list + data: [] + total_count: 0 + pages: + type: pages + page: 1 + per_page: 10 + total_pages: 0 schema: - "$ref": "#/components/schemas/error" + "$ref": "#/components/schemas/contact_list" '401': description: Unauthorized content: @@ -2128,56 +2163,23 @@ paths: Unauthorized: value: type: error.list - request_id: 99739bbd-2dbe-4ce3-ae91-af23379b5cd7 + request_id: d5bac7ff-7961-4fe5-8aed-6f1b031b38af 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: 667d608d8a68186f43bafd70 - bad_request: - summary: Bad Request - value: - company_not_found: - summary: Company Not Found - value: - id: '123' - get: - summary: List attached companies for contact + post: + summary: Create contact parameters: - - name: 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. + operationId: CreateContact + description: You can create a new contact (ie. user or lead). responses: '200': description: successful @@ -2186,68 +2188,121 @@ paths: examples: successful: value: - type: list - data: - - type: company - company_id: '1' - id: 667d60938a68186f43bafd91 - app_id: this_is_an_id182_that_should_be_at_least_ - name: company12 - remote_created_at: 1719492755 - created_at: 1719492755 - updated_at: 1719492755 - last_request_at: 1719319955 - 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: b9d7374d-1780-4668-bb62-0e1ff9cdab45 - errors: - - code: not_found - message: User Not Found - schema: - "$ref": "#/components/schemas/error" - '401': - description: Unauthorized - content: - application/json: - examples: - Unauthorized: - value: + type: contact + id: 667d60b08a68186f43bafdbf + workspace_id: this_is_an_id272_that_should_be_at_least_ + external_id: + role: user + email: joebloggs@intercom.io + phone: + name: + avatar: + owner_id: + social_profiles: + type: list + data: [] + has_hard_bounced: false + marked_email_as_spam: false + unsubscribed_from_emails: false + created_at: 1719492784 + updated_at: 1719492784 + signed_up_at: + 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/667d60b08a68186f43bafdbf/tags" + total_count: 0 + has_more: false + notes: + type: list + data: [] + url: "/contacts/667d60b08a68186f43bafdbf/notes" + total_count: 0 + has_more: false + companies: + type: list + data: [] + url: "/contacts/667d60b08a68186f43bafdbf/companies" + total_count: 0 + has_more: false + opted_out_subscription_types: + type: list + data: [] + url: "/contacts/667d60b08a68186f43bafdbf/subscriptions" + total_count: 0 + has_more: false + opted_in_subscription_types: + type: list + data: [] + url: "/contacts/667d60b08a68186f43bafdbf/subscriptions" + total_count: 0 + has_more: false + utm_campaign: + utm_content: + utm_medium: + utm_source: + utm_term: + referrer: + schema: + "$ref": "#/components/schemas/contact" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: type: error.list - request_id: d211ec8c-df9b-420c-86df-23c27ad54bc5 + request_id: c18ca0d4-ad2c-41e7-9a71-1df806f9c954 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" - "/contacts/{contact_id}/companies/{id}": - delete: - summary: Detach a contact from a company + requestBody: + content: + application/json: + schema: + oneOf: + - "$ref": "#/components/schemas/create_contact_request" + examples: + successful: + summary: successful + value: + email: joebloggs@intercom.io + "/contacts/{contact_id}": + put: + summary: Update a contact parameters: - name: Intercom-Version in: header @@ -2255,73 +2310,110 @@ paths: "$ref": "#/components/schemas/intercom_version" - name: contact_id in: path + description: id + example: 63a07ddf05a32042dffac965 required: true - description: The unique identifier for the contact which is given by Intercom - example: 58a430d35458202d41b1e65b - schema: - type: string - - name: 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. + operationId: UpdateContact + description: You can update an existing contact (ie. user or lead). responses: '200': - description: Successful + description: successful content: application/json: examples: - Successful: + successful: value: - type: company - company_id: '1' - id: 667d60918a68186f43bafd80 - app_id: this_is_an_id174_that_should_be_at_least_ - name: company8 - remote_created_at: 1719492753 - created_at: 1719492753 - updated_at: 1719492753 - monthly_spend: 0 - session_count: 0 - user_count: 0 - tags: - type: tag.list - tags: [] - segments: - type: segment.list - segments: [] - plan: {} + type: contact + id: 667d60a88a68186f43bafdb8 + workspace_id: this_is_an_id248_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: 1719492776 + updated_at: 1719492776 + signed_up_at: 1719492776 + 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/667d60a88a68186f43bafdb8/tags" + total_count: 0 + has_more: false + notes: + type: list + data: [] + url: "/contacts/667d60a88a68186f43bafdb8/notes" + total_count: 0 + has_more: false + companies: + type: list + data: [] + url: "/contacts/667d60a88a68186f43bafdb8/companies" + total_count: 0 + has_more: false + opted_out_subscription_types: + type: list + data: [] + url: "/contacts/667d60a88a68186f43bafdb8/subscriptions" + total_count: 0 + has_more: false + opted_in_subscription_types: + type: list + data: [] + url: "/contacts/667d60a88a68186f43bafdb8/subscriptions" + total_count: 0 + has_more: false + utm_campaign: + utm_content: + utm_medium: + utm_source: + utm_term: + referrer: schema: - "$ref": "#/components/schemas/company" - '404': - description: Contact Not Found - content: - application/json: - examples: - Company Not Found: - value: - type: error.list - request_id: cd4f1648-724c-45f0-b6e1-72a1bc6479ee - errors: - - code: company_not_found - message: Company Not Found - Contact Not Found: - value: - type: error.list - request_id: d316defc-0a2f-49e7-b8ff-4cb6ccf46c90 - errors: - - code: not_found - message: User Not Found - schema: - "$ref": "#/components/schemas/error" + "$ref": "#/components/schemas/contact" '401': description: Unauthorized content: @@ -2330,212 +2422,199 @@ paths: Unauthorized: value: type: error.list - request_id: d8c1ab2d-4044-4c4f-98f0-176860747112 + request_id: b1b88e2d-938c-4a26-b65d-26ff65a0af36 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" - "/contacts/{id}/notes": + requestBody: + content: + application/json: + schema: + oneOf: + - "$ref": "#/components/schemas/update_contact_request" + examples: + successful: + summary: successful + value: + email: joebloggs@intercom.io + name: joe bloggs get: - summary: List all notes + summary: Get a contact parameters: - - name: id - in: path - required: true - description: The unique identifier of a contact. - schema: - type: integer - 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: - - Notes - Contacts - operationId: listNotes - description: You can fetch a list of notes that are associated to a contact. + operationId: ShowContact + description: You can fetch the details of a single contact. responses: '200': - description: Successful response + description: successful content: application/json: examples: - Successful response: + successful: value: - type: list - data: - - type: note - id: '29' - created_at: 1718887958 - contact: - type: contact - id: 667d60968a68186f43bafd9c - author: - type: admin - id: '991267491' - name: Ciaran101 Lee - email: admin101@email.com - away_mode_enabled: false - away_mode_reassign: false - body: "

This is a note.

" - - type: note - id: '28' - created_at: 1718801558 - contact: - type: contact - id: 667d60968a68186f43bafd9c - author: - type: admin - id: '991267491' - name: Ciaran101 Lee - email: admin101@email.com - away_mode_enabled: false - away_mode_reassign: false - body: "

This is a note.

" - - type: note - id: '27' - created_at: 1718801558 - contact: - type: contact - id: 667d60968a68186f43bafd9c - author: - type: admin - id: '991267491' - name: Ciaran101 Lee - email: admin101@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 + type: contact + id: 667d60a98a68186f43bafdb9 + workspace_id: this_is_an_id252_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: 1719492777 + updated_at: 1719492777 + signed_up_at: 1719492777 + 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/667d60a98a68186f43bafdb9/tags" + total_count: 0 + has_more: false + notes: + type: list + data: [] + url: "/contacts/667d60a98a68186f43bafdb9/notes" + total_count: 0 + has_more: false + companies: + type: list + data: [] + url: "/contacts/667d60a98a68186f43bafdb9/companies" + total_count: 0 + has_more: false + opted_out_subscription_types: + type: list + data: [] + url: "/contacts/667d60a98a68186f43bafdb9/subscriptions" + total_count: 0 + has_more: false + opted_in_subscription_types: + type: list + data: [] + url: "/contacts/667d60a98a68186f43bafdb9/subscriptions" + total_count: 0 + has_more: false + utm_campaign: + utm_content: + utm_medium: + utm_source: + utm_term: + referrer: schema: - "$ref": "#/components/schemas/note_list" - '404': - description: Contact not found + "$ref": "#/components/schemas/contact" + '401': + description: Unauthorized content: application/json: examples: - Contact not found: + Unauthorized: value: type: error.list - request_id: e93f90a6-4c85-4dbf-b063-96b649318371 + request_id: f70085f1-f655-43ee-9585-d2061b260fcd errors: - - code: not_found - message: User Not Found + - code: unauthorized + message: Access Token Invalid schema: "$ref": "#/components/schemas/error" - post: - summary: Create a note + delete: + summary: Delete a contact parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: id + - name: contact_id in: path + description: id required: true - description: The unique identifier of a given contact. - example: '123' schema: - type: integer + type: string tags: - - Notes - Contacts - operationId: createNote - description: You can add a note to a single contact. + operationId: DeleteContact + description: You can delete a single contact. responses: '200': - description: Successful response + description: successful content: application/json: examples: - Successful response: + successful: value: - type: note - id: '34' - created_at: 1719492759 - contact: - type: contact - id: 667d60978a68186f43bafd9e - author: - type: admin - id: '991267493' - name: Ciaran103 Lee - email: admin103@email.com - away_mode_enabled: false - away_mode_reassign: false - body: "

Hello

" + id: 667d60aa8a68186f43bafdba + external_id: '70' + type: contact + deleted: true schema: - "$ref": "#/components/schemas/note" - '404': - description: Contact not found + "$ref": "#/components/schemas/contact_deleted" + '401': + description: Unauthorized content: application/json: examples: - Admin not found: - value: - type: error.list - request_id: d7c69ce6-3195-46be-b2cb-0dce355d2919 - errors: - - code: not_found - message: Resource Not Found - Contact not found: + Unauthorized: value: type: error.list - request_id: 2e3bd274-9ac6-43c3-a419-bcc8e6a03a1d + request_id: 0bce3945-d2ec-4b8e-a790-b16fd52d9f11 errors: - - code: not_found - message: User Not Found + - code: unauthorized + message: Access Token Invalid 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 - contact_id: - type: string - description: The unique identifier of a given contact. - example: '123' - admin_id: - type: string - description: The unique identifier of a given admin. - example: '123' - examples: - successful_response: - summary: Successful response - value: - contact_id: 667d60978a68186f43bafd9e - admin_id: 991267493 - body: Hello - admin_not_found: - summary: Admin not found - value: - contact_id: 667d60988a68186f43bafd9f - admin_id: 123 - body: Hello - contact_not_found: - summary: Contact not found - value: - contact_id: 123 - admin_id: 991267495 - body: Hello - "/contacts/{contact_id}/segments": + "/contacts/{contact_id}/companies": get: - summary: List attached segments for contact + summary: List attached companies for contact parameters: - name: contact_id in: path @@ -2548,11 +2627,25 @@ paths: 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 15 + example: 15 + schema: + type: integer tags: - Contacts - - Segments - operationId: listSegmentsForAContact - description: You can fetch a list of segments that are associated to a contact. + - Companies + operationId: listCompaniesForAContact + description: You can fetch a list of companies that are associated to a contact. responses: '200': description: successful @@ -2563,14 +2656,35 @@ paths: value: type: list data: - - type: segment - id: 667d60998a68186f43bafda1 - name: segment - created_at: 1719492761 - updated_at: 1719492761 - person_type: user + - type: company + company_id: '1' + id: 667d60938a68186f43bafd91 + app_id: this_is_an_id182_that_should_be_at_least_ + name: company12 + remote_created_at: 1719492755 + created_at: 1719492755 + updated_at: 1719492755 + last_request_at: 1719319955 + 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_segments" + "$ref": "#/components/schemas/contact_attached_companies" '404': description: Contact not found content: @@ -2579,7 +2693,7 @@ paths: Contact not found: value: type: error.list - request_id: 7d4ab1a9-5990-4338-b5d9-0f3f55f1acb7 + request_id: b9d7374d-1780-4668-bb62-0e1ff9cdab45 errors: - code: not_found message: User Not Found @@ -2593,39 +2707,30 @@ paths: Unauthorized: value: type: error.list - request_id: d2927c64-9c5a-4593-997b-381f8c2356ea + request_id: d211ec8c-df9b-420c-86df-23c27ad54bc5 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" - "/contacts/{contact_id}/subscriptions": - get: - summary: List subscriptions for a contact + 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 - description: The unique identifier for the contact which is given by Intercom - example: 63a07ddf05a32042dffac965 required: true + description: The unique identifier for the contact which is given by Intercom schema: type: string - - name: Intercom-Version - in: header - schema: - "$ref": "#/components/schemas/intercom_version" tags: + - Companies - 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. + operationId: attachContactToACompany + description: You can attach a company to a single contact. responses: '200': description: Successful @@ -2634,50 +2739,53 @@ paths: examples: Successful: value: - type: list - data: - - type: subscription - id: '93' - 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: '95' - 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 + type: company + company_id: '1' + id: 667d608d8a68186f43bafd70 + app_id: this_is_an_id166_that_should_be_at_least_ + name: company6 + remote_created_at: 1719492749 + created_at: 1719492749 + updated_at: 1719492749 + 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/subscription_type_list" + "$ref": "#/components/schemas/company" + '400': + description: Bad Request + content: + application/json: + examples: + Bad Request: + value: + type: error.list + request_id: 9297dcfc-1896-43a3-a3f9-131238422ed2 + errors: + - code: parameter_not_found + message: company not specified + schema: + "$ref": "#/components/schemas/error" '404': - description: Contact not found + description: Company Not Found content: application/json: examples: - Contact not found: + Company Not Found: value: type: error.list - request_id: 3f481052-cf49-4b95-a492-734223865981 + request_id: 32d121d8-fcbf-4c59-9c60-204f7d602f36 errors: - - code: not_found - message: User Not Found + - code: company_not_found + message: Company Not Found schema: "$ref": "#/components/schemas/error" '401': @@ -2688,17 +2796,40 @@ paths: Unauthorized: value: type: error.list - request_id: 82a95655-569d-4e5d-b0d9-f8a6c7a379f3 + request_id: 99739bbd-2dbe-4ce3-ae91-af23379b5cd7 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" - post: - summary: Add subscription to a contact - tags: - - Subscription Types - - Contacts + 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: 667d608d8a68186f43bafd70 + bad_request: + summary: Bad Request + value: + company_not_found: + summary: Company Not Found + value: + id: '123' + "/contacts/{contact_id}/companies/{company_id}": + delete: + summary: Detach a contact from a company parameters: - name: Intercom-Version in: header @@ -2706,20 +2837,23 @@ paths: "$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: 63a07ddf05a32042dffac965 + 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 - 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. + tags: + - Companies + - Contacts + operationId: detachContactFromACompany + description: You can detach a company from a single contact. responses: '200': description: Successful @@ -2728,41 +2862,46 @@ paths: examples: Successful: value: - type: subscription - id: '108' - 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 + type: company + company_id: '1' + id: 667d60918a68186f43bafd80 + app_id: this_is_an_id174_that_should_be_at_least_ + name: company8 + remote_created_at: 1719492753 + created_at: 1719492753 + updated_at: 1719492753 + 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/subscription_type" + "$ref": "#/components/schemas/company" '404': - description: Resource not found + description: Contact Not Found content: application/json: examples: - Contact not found: + Company Not Found: value: type: error.list - request_id: cf0f6fd6-7c5e-492b-909d-f60b35eea1c4 + request_id: cd4f1648-724c-45f0-b6e1-72a1bc6479ee errors: - - code: not_found - message: User Not Found - Resource not found: + - code: company_not_found + message: Company Not Found + Contact Not Found: value: type: error.list - request_id: 3f852f45-1a80-4ade-9bc6-72b377d2bbd8 + request_id: d316defc-0a2f-49e7-b8ff-4cb6ccf46c90 errors: - code: not_found - message: Resource Not Found + message: User Not Found schema: "$ref": "#/components/schemas/error" '401': @@ -2773,141 +2912,122 @@ paths: Unauthorized: value: type: error.list - request_id: 377d162e-82a5-4148-a26f-29c9c760dadc + request_id: d8c1ab2d-4044-4c4f-98f0-176860747112 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: 108 - consent_type: opt_in - contact_not_found: - summary: Contact not found - value: - id: 112 - consent_type: opt_in - resource_not_found: - summary: Resource not found - value: - id: invalid_id - consent_type: opt_in - "/contacts/{contact_id}/subscriptions/{id}": - delete: - summary: Remove subscription from a contact - tags: - - Subscription Types - - Contacts + "/contacts/{contact_id}/notes": + get: + summary: List all notes 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 + description: The unique identifier of a contact. schema: type: string - - name: id - in: path - description: The unique identifier for the subscription type which is given - by Intercom - example: '37846' - required: true + - name: Intercom-Version + in: header 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. + "$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 15 + example: 15 + schema: + type: integer + tags: + - Notes + - Contacts + operationId: listNotes + description: You can fetch a list of notes that are associated to a contact. responses: '200': - description: Successful + description: Successful response content: application/json: examples: - Successful: + Successful response: value: - type: subscription - id: '124' - 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 + type: list + data: + - type: note + id: '29' + created_at: 1718887958 + contact: + type: contact + id: 667d60968a68186f43bafd9c + author: + type: admin + id: '991267491' + name: Ciaran101 Lee + email: admin101@email.com + away_mode_enabled: false + away_mode_reassign: false + body: "

This is a note.

" + - type: note + id: '28' + created_at: 1718801558 + contact: + type: contact + id: 667d60968a68186f43bafd9c + author: + type: admin + id: '991267491' + name: Ciaran101 Lee + email: admin101@email.com + away_mode_enabled: false + away_mode_reassign: false + body: "

This is a note.

" + - type: note + id: '27' + created_at: 1718801558 + contact: + type: contact + id: 667d60968a68186f43bafd9c + author: + type: admin + id: '991267491' + name: Ciaran101 Lee + email: admin101@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/subscription_type" + "$ref": "#/components/schemas/note_list" '404': - description: Resource not found + description: Contact not found content: application/json: examples: Contact not found: value: type: error.list - request_id: 7bc429e4-e887-4f53-b69c-94e6e55d2125 + request_id: e93f90a6-4c85-4dbf-b063-96b649318371 errors: - code: not_found message: User Not Found - Resource not found: - value: - type: error.list - request_id: 66ebc1f5-5e02-4584-8028-f2559a41e8df - 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: 99fba0c6-2252-4658-abd2-1d2ff16a508b - 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 + post: + summary: Create a note parameters: - name: Intercom-Version in: header @@ -2915,67 +3035,100 @@ paths: "$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 + description: The unique identifier of a given contact. + example: "123" schema: type: string - operationId: listTagsForAContact - description: You can fetch a list of all tags that are attached to a specific - contact. + tags: + - Notes + - Contacts + operationId: createNote + description: You can add a note to a single contact. responses: '200': - description: successful + description: Successful response content: application/json: examples: - successful: + Successful response: value: - type: list - data: - - type: tag - id: '93' - name: Manual tag - schema: - "$ref": "#/components/schemas/tag_list" - '404': - description: Contact not found - content: - application/json: - examples: - Contact not found: - value: - type: error.list - request_id: 2b513026-b78c-4c67-b073-da0266f62cc7 - errors: - - code: not_found - message: User Not Found + type: note + id: '34' + created_at: 1719492759 + contact: + type: contact + id: 667d60978a68186f43bafd9e + author: + type: admin + id: '991267493' + name: Ciaran103 Lee + email: admin103@email.com + away_mode_enabled: false + away_mode_reassign: false + body: "

Hello

" schema: - "$ref": "#/components/schemas/error" - '401': - description: Unauthorized + "$ref": "#/components/schemas/note" + '404': + description: Contact not found content: application/json: examples: - Unauthorized: + Admin not found: value: type: error.list - request_id: 97383559-0fb0-4084-8a9a-8e3407c46108 + request_id: d7c69ce6-3195-46be-b2cb-0dce355d2919 errors: - - code: unauthorized - message: Access Token Invalid + - code: not_found + message: Resource Not Found + Contact not found: + value: + type: error.list + request_id: 2e3bd274-9ac6-43c3-a419-bcc8e6a03a1d + errors: + - code: not_found + message: User Not Found schema: "$ref": "#/components/schemas/error" - post: - summary: Add tag to a contact - tags: - - Tags - - Contacts + 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: 667d60978a68186f43bafd9e + admin_id: 991267493 + body: Hello + admin_not_found: + summary: Admin not found + value: + contact_id: 667d60988a68186f43bafd9f + admin_id: 123 + body: Hello + contact_not_found: + summary: Contact not found + value: + contact_id: 123 + admin_id: 991267495 + body: Hello + "/contacts/{contact_id}/segments": + get: + summary: List attached segments for contact 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 @@ -2983,9 +3136,15 @@ paths: 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. + - 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 @@ -2994,30 +3153,28 @@ paths: examples: successful: value: - type: tag - id: '94' - name: Manual tag + type: list + data: + - type: segment + id: 667d60998a68186f43bafda1 + name: segment + created_at: 1719492761 + updated_at: 1719492761 + person_type: user schema: - "$ref": "#/components/schemas/tag" + "$ref": "#/components/schemas/contact_segments" '404': - description: Tag not found + description: Contact not found content: application/json: examples: Contact not found: value: type: error.list - request_id: 1bbd7e4b-718e-46f4-b682-a429aea78f01 + request_id: 7d4ab1a9-5990-4338-b5d9-0f3f55f1acb7 errors: - code: not_found message: User Not Found - Tag not found: - value: - type: error.list - request_id: a1a28017-728a-423b-adc0-2705d375f533 - errors: - - code: not_found - message: Resource Not Found schema: "$ref": "#/components/schemas/error" '401': @@ -3028,49 +3185,16 @@ paths: Unauthorized: value: type: error.list - request_id: 63a2828f-107e-4d51-9398-a220b81a7bce + request_id: d2927c64-9c5a-4593-997b-381f8c2356ea 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: 94 - contact_not_found: - summary: Contact not found - value: - id: 95 - tag_not_found: - summary: Tag not found - value: - id: '123' - "/contacts/{contact_id}/tags/{id}": - delete: - summary: Remove tag from a contact - tags: - - Tags - - Contacts + "/contacts/{contact_id}/subscriptions": + get: + summary: List subscriptions for a contact 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 @@ -3078,48 +3202,74 @@ paths: required: true schema: type: string - - name: id - in: path - description: The unique identifier for the tag which is given by Intercom - example: '7522907' - required: true + - name: Intercom-Version + in: header 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. + "$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 + description: Successful content: application/json: examples: - successful: + Successful: value: - type: tag - id: '97' - name: Manual tag + type: list + data: + - type: subscription + id: '93' + 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: '95' + 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/tag" + "$ref": "#/components/schemas/subscription_type_list" '404': - description: Tag not found + description: Contact not found content: application/json: examples: Contact not found: value: type: error.list - request_id: 6f735483-c309-4e94-b9ab-143aedc0c691 + request_id: 3f481052-cf49-4b95-a492-734223865981 errors: - code: not_found message: User Not Found - Tag not found: - value: - type: error.list - request_id: 9e780671-29b3-4913-b4be-15234ea0bc6a - errors: - - code: not_found - message: Resource Not Found schema: "$ref": "#/components/schemas/error" '401': @@ -3130,126 +3280,83 @@ paths: Unauthorized: value: type: error.list - request_id: e97d9f1b-8c9e-4caf-b473-3bce411c697e + request_id: 82a95655-569d-4e5d-b0d9-f8a6c7a379f3 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" - "/contacts/{id}": - put: - summary: Update a contact + post: + summary: Add subscription to a contact + tags: + - Subscription Types + - Contacts parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: id + - name: contact_id in: path - description: id + description: The unique identifier for the contact which is given by Intercom example: 63a07ddf05a32042dffac965 required: true schema: type: string - tags: - - Contacts - operationId: UpdateContact - description: You can update an existing contact (ie. user or lead). - responses: - '200': - description: successful + 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: + Successful: value: - type: contact - id: 667d60a88a68186f43bafdb8 - workspace_id: this_is_an_id248_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: 1719492776 - updated_at: 1719492776 - signed_up_at: 1719492776 - 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/667d60a88a68186f43bafdb8/tags" - total_count: 0 - has_more: false - notes: - type: list - data: [] - url: "/contacts/667d60a88a68186f43bafdb8/notes" - total_count: 0 - has_more: false - companies: - type: list - data: [] - url: "/contacts/667d60a88a68186f43bafdb8/companies" - total_count: 0 - has_more: false - opted_out_subscription_types: - type: list - data: [] - url: "/contacts/667d60a88a68186f43bafdb8/subscriptions" - total_count: 0 - has_more: false - opted_in_subscription_types: - type: list - data: [] - url: "/contacts/667d60a88a68186f43bafdb8/subscriptions" - total_count: 0 - has_more: false - utm_campaign: - utm_content: - utm_medium: - utm_source: - utm_term: - referrer: + type: subscription + id: '108' + 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/contact" + "$ref": "#/components/schemas/subscription_type" + '404': + description: Resource not found + content: + application/json: + examples: + Contact not found: + value: + type: error.list + request_id: cf0f6fd6-7c5e-492b-909d-f60b35eea1c4 + errors: + - code: not_found + message: User Not Found + Resource not found: + value: + type: error.list + request_id: 3f852f45-1a80-4ade-9bc6-72b377d2bbd8 + errors: + - code: not_found + message: Resource Not Found + schema: + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -3258,7 +3365,7 @@ paths: Unauthorized: value: type: error.list - request_id: b1b88e2d-938c-4a26-b65d-26ff65a0af36 + request_id: 377d162e-82a5-4148-a26f-29c9c760dadc errors: - code: unauthorized message: Access Token Invalid @@ -3268,127 +3375,111 @@ paths: content: application/json: schema: - oneOf: - - "$ref": "#/components/schemas/update_contact_request" + 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 + summary: Successful value: - email: joebloggs@intercom.io - name: joe bloggs - get: - summary: Get a contact + id: 108 + consent_type: opt_in + contact_not_found: + summary: Contact not found + value: + id: 112 + 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: id + - name: contact_id in: path - description: id + description: The unique identifier for the contact which is given by Intercom example: 63a07ddf05a32042dffac965 required: true schema: type: string - tags: - - Contacts - operationId: ShowContact - description: You can fetch the details of a single contact. + - 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 + description: Successful content: application/json: examples: - successful: + Successful: value: - type: contact - id: 667d60a98a68186f43bafdb9 - workspace_id: this_is_an_id252_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: 1719492777 - updated_at: 1719492777 - signed_up_at: 1719492777 - 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/667d60a98a68186f43bafdb9/tags" - total_count: 0 - has_more: false - notes: - type: list - data: [] - url: "/contacts/667d60a98a68186f43bafdb9/notes" - total_count: 0 - has_more: false - companies: - type: list - data: [] - url: "/contacts/667d60a98a68186f43bafdb9/companies" - total_count: 0 - has_more: false - opted_out_subscription_types: - type: list - data: [] - url: "/contacts/667d60a98a68186f43bafdb9/subscriptions" - total_count: 0 - has_more: false - opted_in_subscription_types: - type: list - data: [] - url: "/contacts/667d60a98a68186f43bafdb9/subscriptions" - total_count: 0 - has_more: false - utm_campaign: - utm_content: - utm_medium: - utm_source: - utm_term: - referrer: + type: subscription + id: '124' + 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/contact" + "$ref": "#/components/schemas/subscription_type" + '404': + description: Resource not found + content: + application/json: + examples: + Contact not found: + value: + type: error.list + request_id: 7bc429e4-e887-4f53-b69c-94e6e55d2125 + errors: + - code: not_found + message: User Not Found + Resource not found: + value: + type: error.list + request_id: 66ebc1f5-5e02-4584-8028-f2559a41e8df + errors: + - code: not_found + message: Resource Not Found + schema: + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -3397,29 +3488,33 @@ paths: Unauthorized: value: type: error.list - request_id: f70085f1-f655-43ee-9585-d2061b260fcd + request_id: 99fba0c6-2252-4658-abd2-1d2ff16a508b errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" - delete: - summary: Delete a contact + "/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: id + - name: contact_id in: path - description: id + description: The unique identifier for the contact which is given by Intercom + example: 63a07ddf05a32042dffac965 required: true schema: type: string - tags: - - Contacts - operationId: DeleteContact - description: You can delete a single contact. + operationId: listTagsForAContact + description: You can fetch a list of all tags that are attached to a specific + contact. responses: '200': description: successful @@ -3428,12 +3523,27 @@ paths: examples: successful: value: - id: 667d60aa8a68186f43bafdba - external_id: '70' - type: contact - deleted: true + type: list + data: + - type: tag + id: '93' + name: Manual tag schema: - "$ref": "#/components/schemas/contact_deleted" + "$ref": "#/components/schemas/tag_list" + '404': + description: Contact not found + content: + application/json: + examples: + Contact not found: + value: + type: error.list + request_id: 2b513026-b78c-4c67-b073-da0266f62cc7 + errors: + - code: not_found + message: User Not Found + schema: + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -3442,25 +3552,32 @@ paths: Unauthorized: value: type: error.list - request_id: 0bce3945-d2ec-4b8e-a790-b16fd52d9f11 + request_id: 97383559-0fb0-4084-8a9a-8e3407c46108 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" - "/contacts/merge": post: - summary: Merge a lead and a user + summary: Add tag to a contact + tags: + - Tags + - Contacts 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`. + - 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 @@ -3469,93 +3586,32 @@ paths: examples: successful: value: - type: contact - id: 667d60ac8a68186f43bafdbc - workspace_id: this_is_an_id260_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: 1719492780 - updated_at: 1719492780 - signed_up_at: 1719492780 - 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/667d60ac8a68186f43bafdbc/tags" - total_count: 0 - has_more: false - notes: - type: list - data: [] - url: "/contacts/667d60ac8a68186f43bafdbc/notes" - total_count: 0 - has_more: false - companies: - type: list - data: [] - url: "/contacts/667d60ac8a68186f43bafdbc/companies" - total_count: 0 - has_more: false - opted_out_subscription_types: - type: list - data: [] - url: "/contacts/667d60ac8a68186f43bafdbc/subscriptions" - total_count: 0 - has_more: false - opted_in_subscription_types: - type: list - data: [] - url: "/contacts/667d60ac8a68186f43bafdbc/subscriptions" - total_count: 0 - has_more: false - utm_campaign: - utm_content: - utm_medium: - utm_source: - utm_term: - referrer: + type: tag + id: '94' + name: Manual tag schema: - "$ref": "#/components/schemas/contact" + "$ref": "#/components/schemas/tag" + '404': + description: Tag not found + content: + application/json: + examples: + Contact not found: + value: + type: error.list + request_id: 1bbd7e4b-718e-46f4-b682-a429aea78f01 + errors: + - code: not_found + message: User Not Found + Tag not found: + value: + type: error.list + request_id: a1a28017-728a-423b-adc0-2705d375f533 + errors: + - code: not_found + message: Resource Not Found + schema: + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -3564,7 +3620,7 @@ paths: Unauthorized: value: type: error.list - request_id: 57b64228-0e60-4e35-833d-39c4e4067dde + request_id: 63a2828f-107e-4d51-9398-a220b81a7bce errors: - code: unauthorized message: Access Token Invalid @@ -3574,125 +3630,56 @@ paths: content: application/json: schema: - "$ref": "#/components/schemas/merge_contacts_request" - examples: - successful: - summary: successful - value: - from: 667d60ac8a68186f43bafdbb - into: 667d60ac8a68186f43bafdbc - "/contacts/search": - post: - summary: Search contacts + 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: 94 + contact_not_found: + summary: Contact not found + value: + id: 95 + 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" - 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 | String
Accepts user or lead | - | name | String | - | avatar | String | - | owner_id | Integer | - | email | String | - | email_domain | String | - | phone | String | - | formatted_phone | String | - | external_id | String | - | created_at | Date (UNIX Timestamp) | - | signed_up_at | Date (UNIX Timestamp) | - | updated_at | Date (UNIX Timestamp) | - | last_seen_at | Date (UNIX Timestamp) | - | last_contacted_at | Date (UNIX Timestamp) | - | last_replied_at | Date (UNIX Timestamp) | - | last_email_opened_at | Date (UNIX Timestamp) | - | last_email_clicked_at | Date (UNIX Timestamp) | - | language_override | String | - | browser | String | - | browser_language | String | - | os | String | - | location.country | String | - | location.region | String | - | location.city | String | - | unsubscribed_from_emails | Boolean | - | marked_email_as_spam | Boolean | - | has_hard_bounced | Boolean | - | ios_last_seen_at | Date (UNIX Timestamp) | - | ios_app_version | String | - | ios_device | String | - | ios_app_device | String | - | ios_os_version | String | - | ios_app_name | String | - | ios_sdk_version | String | - | android_last_seen_at | Date (UNIX Timestamp) | - | android_app_version | String | - | android_device | String | - | android_app_name | String | - | andoid_sdk_version | String | - | segment_id | String | - | tag_id | String | - | custom_attributes.{attribute_name} | String | - - ### Accepted Operators - - {% admonition type="attention" name="Searching based on `created_at`" %} - You cannot use the `<=` or `>=` operators to search by `created_at`. - {% /admonition %} - - The table below shows the operators you can use to define how you want to search for the value. The operator should be put in as a string (`"="`). The operator has to be compatible with the field's type (eg. you cannot search with `>` for a given string value as it's only compatible for integer's and dates). - - | Operator | Valid Types | Description | - | :------- | :------------------------------- | :--------------------------------------------------------------- | - | = | All | Equals | - | != | All | Doesn't Equal | - | IN | All | In
Shortcut for `OR` queries
Values must be in Array | - | NIN | All | Not In
Shortcut for `OR !` queries
Values must be in Array | - | > | Integer
Date (UNIX Timestamp) | Greater than | - | < | Integer
Date (UNIX Timestamp) | Lower than | - | ~ | String | Contains | - | !~ | String | Doesn't Contain | - | ^ | String | Starts With | - | $ | String | Ends With | + - 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 @@ -3701,82 +3688,32 @@ paths: examples: successful: value: - type: list - data: [] - total_count: 0 - pages: - type: pages - page: 1 - per_page: 5 - total_pages: 0 + type: tag + id: '97' + name: Manual tag schema: - "$ref": "#/components/schemas/contact_list" - '401': - description: Unauthorized + "$ref": "#/components/schemas/tag" + '404': + description: Tag not found content: application/json: examples: - Unauthorized: + Contact not found: value: type: error.list - request_id: 2b28c47b-8fa3-4e17-8fc1-6ba80f1cc844 + request_id: 6f735483-c309-4e94-b9ab-143aedc0c691 errors: - - code: unauthorized - message: Access Token Invalid - schema: - "$ref": "#/components/schemas/error" - 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 - "/contacts": - get: - summary: List all contacts - parameters: - - name: Intercom-Version - in: header - schema: - "$ref": "#/components/schemas/intercom_version" - tags: - - Contacts - operationId: ListContacts - description: | - You can fetch a list of all contacts (ie. users or leads) in your workspace. - {% admonition type="warning" name="Pagination" %} - You can use 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/#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: + - code: not_found + message: User Not Found + Tag not found: value: - type: list - data: [] - total_count: 0 - pages: - type: pages - page: 1 - per_page: 10 - total_pages: 0 + type: error.list + request_id: 9e780671-29b3-4913-b4be-15234ea0bc6a + errors: + - code: not_found + message: Resource Not Found schema: - "$ref": "#/components/schemas/contact_list" + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -3785,23 +3722,31 @@ paths: Unauthorized: value: type: error.list - request_id: d5bac7ff-7961-4fe5-8aed-6f1b031b38af + request_id: e97d9f1b-8c9e-4caf-b473-3bce411c697e errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" + "/contacts/{contact_id}/archive": post: - summary: Create contact + summary: Archive 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 - operationId: CreateContact - description: You can create a new contact (ie. user or lead). + operationId: ArchiveContact + description: You can archive a single contact. responses: '200': description: successful @@ -3810,14 +3755,74 @@ paths: examples: successful: value: + id: 667d60b18a68186f43bafdc0 + external_id: '70' type: contact - id: 667d60b08a68186f43bafdbf - workspace_id: this_is_an_id272_that_should_be_at_least_ - external_id: - role: user - email: joebloggs@intercom.io + archived: true + schema: + "$ref": "#/components/schemas/contact_archived" + "/contacts/{contact_id}/unarchive": + post: + summary: Unarchive 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 + operationId: UnarchiveContact + description: You can unarchive a single contact. + responses: + '200': + description: successful + content: + application/json: + examples: + successful: + value: + id: 667d60b28a68186f43bafdc1 + external_id: '70' + type: contact + archived: false + schema: + "$ref": "#/components/schemas/contact_unarchived" + "/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: 667d60ac8a68186f43bafdbc + workspace_id: this_is_an_id260_that_should_be_at_least_ + external_id: '70' + role: user + email: joe@bloggs.com phone: - name: + name: Joe Bloggs avatar: owner_id: social_profiles: @@ -3826,9 +3831,9 @@ paths: has_hard_bounced: false marked_email_as_spam: false unsubscribed_from_emails: false - created_at: 1719492784 - updated_at: 1719492784 - signed_up_at: + created_at: 1719492780 + updated_at: 1719492780 + signed_up_at: 1719492780 last_seen_at: last_replied_at: last_contacted_at: @@ -3862,31 +3867,31 @@ paths: tags: type: list data: [] - url: "/contacts/667d60b08a68186f43bafdbf/tags" + url: "/contacts/667d60ac8a68186f43bafdbc/tags" total_count: 0 has_more: false notes: type: list data: [] - url: "/contacts/667d60b08a68186f43bafdbf/notes" + url: "/contacts/667d60ac8a68186f43bafdbc/notes" total_count: 0 has_more: false companies: type: list data: [] - url: "/contacts/667d60b08a68186f43bafdbf/companies" + url: "/contacts/667d60ac8a68186f43bafdbc/companies" total_count: 0 has_more: false opted_out_subscription_types: type: list data: [] - url: "/contacts/667d60b08a68186f43bafdbf/subscriptions" + url: "/contacts/667d60ac8a68186f43bafdbc/subscriptions" total_count: 0 has_more: false opted_in_subscription_types: type: list data: [] - url: "/contacts/667d60b08a68186f43bafdbf/subscriptions" + url: "/contacts/667d60ac8a68186f43bafdbc/subscriptions" total_count: 0 has_more: false utm_campaign: @@ -3905,7 +3910,7 @@ paths: Unauthorized: value: type: error.list - request_id: c18ca0d4-ad2c-41e7-9a71-1df806f9c954 + request_id: 57b64228-0e60-4e35-833d-39c4e4067dde errors: - code: unauthorized message: Access Token Invalid @@ -3915,32 +3920,125 @@ paths: content: application/json: schema: - oneOf: - - "$ref": "#/components/schemas/create_contact_request" + "$ref": "#/components/schemas/merge_contacts_request" examples: successful: summary: successful value: - email: joebloggs@intercom.io - "/contacts/{id}/archive": + from: 667d60ac8a68186f43bafdbb + into: 667d60ac8a68186f43bafdbc + "/contacts/search": post: - summary: Archive contact + summary: Search contacts parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: id - in: path - description: id - example: 63a07ddf05a32042dffac965 - required: true - schema: - type: string tags: - Contacts - operationId: ArchiveContact - description: You can archive a single contact. + 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 | String
Accepts user or lead | + | name | String | + | avatar | String | + | owner_id | Integer | + | email | String | + | email_domain | String | + | phone | String | + | formatted_phone | String | + | external_id | String | + | created_at | Date (UNIX Timestamp) | + | signed_up_at | Date (UNIX Timestamp) | + | updated_at | Date (UNIX Timestamp) | + | last_seen_at | Date (UNIX Timestamp) | + | last_contacted_at | Date (UNIX Timestamp) | + | last_replied_at | Date (UNIX Timestamp) | + | last_email_opened_at | Date (UNIX Timestamp) | + | last_email_clicked_at | Date (UNIX Timestamp) | + | language_override | String | + | browser | String | + | browser_language | String | + | os | String | + | location.country | String | + | location.region | String | + | location.city | String | + | unsubscribed_from_emails | Boolean | + | marked_email_as_spam | Boolean | + | has_hard_bounced | Boolean | + | ios_last_seen_at | Date (UNIX Timestamp) | + | ios_app_version | String | + | ios_device | String | + | ios_app_device | String | + | ios_os_version | String | + | ios_app_name | String | + | ios_sdk_version | String | + | android_last_seen_at | Date (UNIX Timestamp) | + | android_app_version | String | + | android_device | String | + | android_app_name | String | + | andoid_sdk_version | String | + | segment_id | String | + | tag_id | String | + | custom_attributes.{attribute_name} | String | + + ### Accepted Operators + + {% admonition type="attention" name="Searching based on `created_at`" %} + You cannot use the `<=` or `>=` operators to search by `created_at`. + {% /admonition %} + + The table below shows the operators you can use to define how you want to search for the value. The operator should be put in as a string (`"="`). The operator has to be compatible with the field's type (eg. you cannot search with `>` for a given string value as it's only compatible for integer's and dates). + + | Operator | Valid Types | Description | + | :------- | :------------------------------- | :--------------------------------------------------------------- | + | = | All | Equals | + | != | All | Doesn't Equal | + | IN | All | In
Shortcut for `OR` queries
Values must be in Array | + | NIN | All | Not In
Shortcut for `OR !` queries
Values must be in Array | + | > | Integer
Date (UNIX Timestamp) | Greater than | + | < | Integer
Date (UNIX Timestamp) | Lower than | + | ~ | String | Contains | + | !~ | String | Doesn't Contain | + | ^ | String | Starts With | + | $ | String | Ends With | responses: '200': description: successful @@ -3949,239 +4047,47 @@ paths: examples: successful: value: - id: 667d60b18a68186f43bafdc0 - external_id: '70' - type: contact - archived: true + type: list + data: [] + total_count: 0 + pages: + type: pages + page: 1 + per_page: 5 + total_pages: 0 schema: - "$ref": "#/components/schemas/contact_archived" - "/contacts/{id}/unarchive": - post: - summary: Unarchive contact - parameters: - - name: Intercom-Version - in: header - schema: - "$ref": "#/components/schemas/intercom_version" - - name: id - in: path - description: id - example: 63a07ddf05a32042dffac965 - required: true - schema: - type: string - tags: - - Contacts - operationId: UnarchiveContact - description: You can unarchive a single contact. - responses: - '200': - description: successful + "$ref": "#/components/schemas/contact_list" + '401': + description: Unauthorized content: application/json: examples: - successful: + Unauthorized: value: - id: 667d60b28a68186f43bafdc1 - external_id: '70' - type: contact - archived: false - schema: - "$ref": "#/components/schemas/contact_unarchived" - "/conversations/{conversation_id}/tags": - post: - summary: Add tag to a conversation - parameters: - - name: Intercom-Version - in: header - schema: - "$ref": "#/components/schemas/intercom_version" - - name: conversation_id - in: path - description: conversation_id - example: '64619700005694' - required: true - schema: - type: string - tags: - - Tags - - Conversations - operationId: attachTagToConversation - description: You can tag a specific conversation. This will return a tag object - for the tag that was added to the conversation. - responses: - '200': - description: successful - content: - application/json: - examples: - successful: - value: - type: tag - id: '99' - name: Manual tag - schema: - "$ref": "#/components/schemas/tag" - '404': - description: Conversation not found - content: - application/json: - examples: - Conversation not found: - value: - type: error.list - request_id: 840d35aa-2414-402a-b3c6-763a410e0d16 - errors: - - code: not_found - message: Conversation not found - schema: - "$ref": "#/components/schemas/error" - '401': - description: Unauthorized - content: - application/json: - examples: - Unauthorized: - value: - type: error.list - request_id: 95cacea0-4744-4de8-a2bf-da4419f75732 - errors: - - code: unauthorized - message: Access Token Invalid - schema: - "$ref": "#/components/schemas/error" - requestBody: - content: - application/json: - schema: - type: object - required: - - id - - admin_id - properties: - id: - type: string - description: The unique identifier for the tag which is given by - Intercom - example: '7522907' - admin_id: - type: string - description: The unique identifier for the admin which is given - by Intercom. - example: '780' - examples: - successful: - summary: successful - value: - id: 99 - admin_id: 991267526 - conversation_not_found: - summary: Conversation not found - value: - id: 100 - admin_id: 991267528 - "/conversations/{conversation_id}/tags/{id}": - delete: - summary: Remove tag from a conversation - parameters: - - name: Intercom-Version - in: header - schema: - "$ref": "#/components/schemas/intercom_version" - - name: conversation_id - in: path - description: conversation_id - example: '64619700005694' - required: true - schema: - type: string - - name: id - in: path - description: id - example: '7522907' - required: true - schema: - type: string - tags: - - Tags - - Conversations - operationId: detachTagFromConversation - description: You can remove tag from a specific conversation. This will return - a tag object for the tag that was removed from the conversation. - responses: - '200': - description: successful - content: - application/json: - examples: - successful: - value: - type: tag - id: '102' - name: Manual tag - schema: - "$ref": "#/components/schemas/tag" - '404': - description: Tag not found - content: - application/json: - examples: - Conversation not found: - value: - type: error.list - request_id: f78f63ba-911d-47b8-a389-b33e3ccbe77e - errors: - - code: not_found - message: Conversation not found - Tag not found: - value: - type: error.list - request_id: 0d00d069-2cf1-496f-b887-a4db74ee320d - errors: - - code: tag_not_found - message: Tag not found - schema: - "$ref": "#/components/schemas/error" - '401': - description: Unauthorized - content: - application/json: - examples: - Unauthorized: - value: - type: error.list - request_id: f083d6b1-e9d2-43b3-86df-67539007fc3e - errors: - - code: unauthorized - message: Access Token Invalid + type: error.list + request_id: 2b28c47b-8fa3-4e17-8fc1-6ba80f1cc844 + errors: + - code: unauthorized + message: Access Token Invalid schema: "$ref": "#/components/schemas/error" requestBody: content: application/json: schema: - type: object - required: - - admin_id - properties: - admin_id: - type: string - description: The unique identifier for the admin which is given - by Intercom. - example: '123' + "$ref": "#/components/schemas/search_request" examples: successful: summary: successful value: - admin_id: 991267530 - conversation_not_found: - summary: Conversation not found - value: - admin_id: 991267532 - tag_not_found: - summary: Tag not found - value: - admin_id: 991267533 + query: + operator: AND + value: + - field: created_at + operator: ">" + value: '1306054154' + pagination: + per_page: 5 "/conversations": get: summary: List all conversations @@ -4283,7 +4189,7 @@ paths: ai_agent: ai_agent_participated: false schema: - "$ref": "#/components/schemas/paginated_response" + "$ref": "#/components/schemas/paginated_conversation_response" '401': description: Unauthorized content: @@ -4411,7 +4317,7 @@ paths: type: user id: 123_doesnt_exist body: Hello there - "/conversations/{id}": + "/conversations/{conversation_id}": get: summary: Retrieve a conversation parameters: @@ -4419,13 +4325,13 @@ paths: in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: id + - name: conversation_id in: path required: true description: The id of the conversation to target - example: 123 + example: "123" schema: - type: integer + type: string - name: display_as in: query required: false @@ -4561,13 +4467,13 @@ paths: in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: id + - name: conversation_id in: path required: true description: The id of the conversation to target - example: 123 + example: "123" schema: - type: integer + type: string - name: display_as in: query required: false @@ -4747,117 +4653,27 @@ paths: custom_attributes: issue_type: Billing priority: High - "/conversations/search": + "/conversations/{conversation_id}/tags": post: - summary: Search conversations + summary: Add tag to a conversation parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" + - name: conversation_id + in: path + description: conversation_id + example: '64619700005694' + required: true + schema: + type: string tags: + - 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 as part of the The conversation model is 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 | String
Accepted fields are `conversation`, `email`, `facebook`, `instagram`, `phone_call`, `phone_switch`, `push`, `sms`, `twitter` and `whatsapp`. | - | source.id | String | - | source.delivered_as | String | - | source.subject | String | - | source.body | String | - | source.author.id | String | - | source.author.type | String | - | source.author.name | String | - | source.author.email | String | - | source.url | String | - | contact_ids | String | - | teammate_ids | String | - | admin_assignee_id | String | - | team_assignee_id | String | - | channel_initiated | String | - | open | Boolean | - | read | Boolean | - | state | String | - | waiting_since | Date (UNIX timestamp) | - | snoozed_until | Date (UNIX timestamp) | - | tag_ids | String | - | priority | String | - | statistics.time_to_assignment | Integer | - | statistics.time_to_admin_reply | Integer | - | statistics.time_to_first_close | Integer | - | statistics.time_to_last_close | Integer | - | statistics.median_time_to_reply | Integer | - | statistics.first_contact_reply_at | Date (UNIX timestamp) | - | statistics.first_assignment_at | Date (UNIX timestamp) | - | statistics.first_admin_reply_at | Date (UNIX timestamp) | - | statistics.first_close_at | Date (UNIX timestamp) | - | statistics.last_assignment_at | Date (UNIX timestamp) | - | statistics.last_assignment_admin_reply_at | Date (UNIX timestamp) | - | statistics.last_contact_reply_at | Date (UNIX timestamp) | - | statistics.last_admin_reply_at | Date (UNIX timestamp) | - | statistics.last_close_at | Date (UNIX timestamp) | - | statistics.last_closed_by_id | String | - | statistics.count_reopens | Integer | - | statistics.count_assignments | Integer | - | statistics.count_conversation_parts | Integer | - | conversation_rating.requested_at | Date (UNIX timestamp) | - | conversation_rating.replied_at | Date (UNIX timestamp) | - | conversation_rating.score | Integer | - | conversation_rating.remark | String | - | conversation_rating.contact_id | String | - | conversation_rating.admin_d | String | - | ai_agent_participated | Boolean | - | ai_agent.resolution_state | String | - | ai_agent.last_answer_type | String | - | ai_agent.rating | Integer | - | ai_agent.rating_remark | String | - | ai_agent.source_type | String | - | ai_agent.source_title | String | - - ### Accepted Operators - - The table below shows the operators you can use to define how you want to search for the value. The operator should be put in as a string (`"="`). The operator has to be compatible with the field's type (eg. you cannot search with `>` for a given string value as it's only compatible for integer's and dates). - - | Operator | Valid Types | Description | - | :------- | :----------------------------- | :----------------------------------------------------------- | - | = | All | Equals | - | != | All | Doesn't Equal | - | IN | All | In Shortcut for `OR` queries Values most be in Array | - | NIN | All | Not In Shortcut for `OR !` queries Values must be in Array | - | > | Integer Date (UNIX Timestamp) | Greater (or equal) than | - | < | Integer Date (UNIX Timestamp) | Lower (or equal) than | - | ~ | String | Contains | - | !~ | String | Doesn't Contain | - | ^ | String | Starts With | - | $ | String | Ends With | + operationId: attachTagToConversation + description: You can tag a specific conversation. This will return a tag object + for the tag that was added to the conversation. responses: '200': description: successful @@ -4866,166 +4682,253 @@ paths: examples: successful: value: - type: conversation.list - pages: - type: pages - page: 1 - per_page: 5 - total_pages: 1 - total_count: 1 - conversations: - - type: conversation - id: '378' - created_at: 1719492843 - updated_at: 1719492843 - waiting_since: - snoozed_until: - source: - type: conversation - id: '403918266' - delivered_as: admin_initiated - subject: '' - body: "

this is the message body

" - author: - type: admin - id: '991267591' - name: Ciaran180 Lee - email: admin180@email.com - attachments: [] - url: - redacted: false - contacts: - type: contact.list - contacts: - - type: contact - id: 667d60ea8a68186f43bafdec - 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 + type: tag + id: '99' + name: Manual tag + schema: + "$ref": "#/components/schemas/tag" + '404': + description: Conversation not found + content: + application/json: + examples: + Conversation not found: + value: + type: error.list + request_id: 840d35aa-2414-402a-b3c6-763a410e0d16 + errors: + - code: not_found + message: Conversation not found + schema: + "$ref": "#/components/schemas/error" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: 95cacea0-4744-4de8-a2bf-da4419f75732 + errors: + - code: unauthorized + message: Access Token Invalid schema: - "$ref": "#/components/schemas/conversation_list" + "$ref": "#/components/schemas/error" requestBody: content: application/json: schema: - "$ref": "#/components/schemas/search_request" + type: object + required: + - id + - admin_id + properties: + id: + type: string + description: The unique identifier for the tag which is given by + Intercom + example: '7522907' + admin_id: + type: string + description: The unique identifier for the admin which is given + by Intercom. + example: '780' examples: successful: summary: successful value: - query: - operator: AND - value: - - field: created_at - operator: ">" - value: '1306054154' - pagination: - per_page: 5 - "/conversations/{id}/reply": - post: - summary: Reply to a conversation + id: 99 + admin_id: 991267526 + conversation_not_found: + summary: Conversation not found + value: + id: 100 + admin_id: 991267528 + "/conversations/{conversation_id}/tags/{tag_id}": + delete: + summary: Remove tag from a conversation parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: id + - name: conversation_id in: path + description: conversation_id + example: '64619700005694' + required: true + schema: + type: string + - name: tag_id + in: path + description: id + example: '7522907' 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: + - 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. + operationId: detachTagFromConversation + description: You can remove tag from a specific conversation. This will return + a tag object for the tag that was removed from the conversation. responses: '200': - description: User last conversation reply + description: successful content: application/json: examples: - User reply: + successful: value: - type: conversation - id: '387' - created_at: 1719492849 - updated_at: 1719492850 - waiting_since: 1719492850 - snoozed_until: - source: - type: conversation - id: '403918269' - delivered_as: admin_initiated - subject: '' - body: "

this is the message body

" - author: - type: admin - id: '991267594' - name: Ciaran182 Lee - email: admin182@email.com - attachments: [] - url: - redacted: false - contacts: - type: contact.list - contacts: - - type: contact - id: 667d60f18a68186f43bafdf4 - external_id: '70' - first_contact_reply: - created_at: 1719492850 - 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: + type: tag + id: '102' + name: Manual tag + schema: + "$ref": "#/components/schemas/tag" + '404': + description: Tag not found + content: + application/json: + examples: + Conversation not found: + value: + type: error.list + request_id: f78f63ba-911d-47b8-a389-b33e3ccbe77e + errors: + - code: not_found + message: Conversation not found + Tag not found: + value: + type: error.list + request_id: 0d00d069-2cf1-496f-b887-a4db74ee320d + errors: + - code: tag_not_found + message: Tag not found + schema: + "$ref": "#/components/schemas/error" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: f083d6b1-e9d2-43b3-86df-67539007fc3e + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + requestBody: + content: + application/json: + schema: + type: object + required: + - admin_id + properties: + admin_id: + type: string + description: The unique identifier for the admin which is given + by Intercom. + example: '123' + examples: + successful: + summary: successful + value: + admin_id: 991267530 + conversation_not_found: + summary: Conversation not found + value: + admin_id: 991267532 + tag_not_found: + summary: Tag not found + value: + admin_id: 991267533 + "/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: '387' + created_at: 1719492849 + updated_at: 1719492850 + waiting_since: 1719492850 + snoozed_until: + source: + type: conversation + id: '403918269' + delivered_as: admin_initiated + subject: '' + body: "

this is the message body

" + author: + type: admin + id: '991267594' + name: Ciaran182 Lee + email: admin182@email.com + attachments: [] + url: + redacted: false + contacts: + type: contact.list + contacts: + - type: contact + id: 667d60f18a68186f43bafdf4 + external_id: '70' + first_contact_reply: + created_at: 1719492850 + 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 @@ -5289,7 +5192,7 @@ paths: type: user intercom_user_id: 667d60f98a68186f43bafdf8 body: Thanks again :) - "/conversations/{id}/parts": + "/conversations/{conversation_id}/parts": post: summary: Manage a conversation parameters: @@ -5297,7 +5200,7 @@ paths: in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: id + - name: conversation_id in: path required: true description: The identifier for the conversation as given by Intercom. @@ -5699,7 +5602,7 @@ paths: type: admin admin_id: 991267617 body: Goodbye :) - "/conversations/{id}/run_assignment_rules": + "/conversations/{conversation_id}/run_assignment_rules": post: summary: Run Assignment Rules on a conversation parameters: @@ -5707,7 +5610,7 @@ paths: in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: id + - name: conversation_id in: path required: true description: The identifier for the conversation as given by Intercom. @@ -5847,7 +5750,7 @@ paths: message: Active subscription needed. schema: "$ref": "#/components/schemas/error" - "/conversations/{id}/customers": + "/conversations/{conversation_id}/customers": post: summary: Attach a contact to a conversation parameters: @@ -5855,7 +5758,7 @@ paths: in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: id + - name: conversation_id in: path required: true description: The identifier for the conversation as given by Intercom. @@ -6083,64 +5986,192 @@ paths: admin_id: 991267648 customer: intercom_user_id: 667d61338a68186f43bafe2a - "/conversations/redact": + "/conversations/{conversation_id}/convert": post: - summary: Redact a conversation part + 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: string 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 %} - + description: You can convert a conversation to a ticket. + operationId: convertConversationToTicket responses: '200': - description: Redact a conversation part + description: successful content: application/json: examples: - Redact a conversation part: + successful: value: - type: conversation - id: '471' - created_at: 1719492938 - updated_at: 1719492940 - waiting_since: 1719492939 - snoozed_until: - source: - type: conversation - id: '403918311' - delivered_as: admin_initiated - subject: '' - body: "

this is the message body

" - author: - type: admin - id: '991267657' - name: Ciaran217 Lee - email: admin217@email.com - attachments: [] - url: - redacted: false + type: ticket + id: '474' + ticket_id: '37' + ticket_attributes: {} + ticket_state: submitted + ticket_type: + type: ticket_type + id: '79' + name: my-ticket-type-1 + description: my ticket type description is awesome. + icon: "\U0001F981" + workspace_id: this_is_an_id404_that_should_be_at_least_ + archived: false + created_at: 1719492947 + updated_at: 1719492947 + is_internal: false + ticket_type_attributes: + type: list + data: [] + category: Customer contacts: type: contact.list contacts: - type: contact - id: 667d614a8a68186f43bafe42 + id: 667d61518a68186f43bafe45 external_id: '70' - first_contact_reply: - created_at: 1719492939 - type: conversation - url: - admin_assignee_id: - team_assignee_id: + admin_assignee_id: '0' + team_assignee_id: '0' + created_at: 1719492945 + updated_at: 1719492947 + ticket_parts: + type: ticket_part.list + ticket_parts: + - type: ticket_part + id: '117' + part_type: comment + body: "

Comment for message

" + created_at: 1719492945 + updated_at: 1719492945 + author: + id: 667d61518a68186f43bafe45 + type: user + name: Joe Bloggs + email: joe@bloggs.com + attachments: [] + redacted: false + - type: ticket_part + id: '118' + part_type: ticket_state_updated_by_admin + ticket_state: submitted + previous_ticket_state: submitted + created_at: 1719492947 + updated_at: 1719492947 + author: + id: '991267667' + type: bot + name: Operator + email: operator+this_is_an_id404_that_should_be_at_least_@intercom.io + attachments: [] + redacted: false + total_count: 2 + open: true + linked_objects: + type: list + data: [] + total_count: 0 + has_more: false + category: Customer + is_shared: true + ticket_state_internal_label: Submitted + ticket_state_external_label: Submitted + schema: + "$ref": "#/components/schemas/ticket" + '400': + description: Bad request + content: + application/json: + examples: + Bad request: + value: + type: error.list + request_id: 74656c1a-0a17-4c80-a7b9-66fa45c6d71b + 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: '79' + bad_request: + summary: Bad request + value: + ticket_type_id: '80' + "/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: '471' + created_at: 1719492938 + updated_at: 1719492940 + waiting_since: 1719492939 + snoozed_until: + source: + type: conversation + id: '403918311' + delivered_as: admin_initiated + subject: '' + body: "

this is the message body

" + author: + type: admin + id: '991267657' + name: Ciaran217 Lee + email: admin217@email.com + attachments: [] + url: + redacted: false + contacts: + type: contact.list + contacts: + - type: contact + id: 667d614a8a68186f43bafe42 + external_id: '70' + first_contact_reply: + created_at: 1719492939 + type: conversation + url: + admin_assignee_id: + team_assignee_id: open: true state: open read: true @@ -6231,25 +6262,117 @@ paths: type: conversation_part conversation_id: really_123_doesnt_exist conversation_part_id: really_123_doesnt_exist - "/conversations/{id}/convert": + "/conversations/search": post: - summary: Convert a conversation to a ticket + summary: Search conversations parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: 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 + 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 as part of the The conversation model is 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 | String
Accepted fields are `conversation`, `email`, `facebook`, `instagram`, `phone_call`, `phone_switch`, `push`, `sms`, `twitter` and `whatsapp`. | + | source.id | String | + | source.delivered_as | String | + | source.subject | String | + | source.body | String | + | source.author.id | String | + | source.author.type | String | + | source.author.name | String | + | source.author.email | String | + | source.url | String | + | contact_ids | String | + | teammate_ids | String | + | admin_assignee_id | String | + | team_assignee_id | String | + | channel_initiated | String | + | open | Boolean | + | read | Boolean | + | state | String | + | waiting_since | Date (UNIX timestamp) | + | snoozed_until | Date (UNIX timestamp) | + | tag_ids | String | + | priority | String | + | statistics.time_to_assignment | Integer | + | statistics.time_to_admin_reply | Integer | + | statistics.time_to_first_close | Integer | + | statistics.time_to_last_close | Integer | + | statistics.median_time_to_reply | Integer | + | statistics.first_contact_reply_at | Date (UNIX timestamp) | + | statistics.first_assignment_at | Date (UNIX timestamp) | + | statistics.first_admin_reply_at | Date (UNIX timestamp) | + | statistics.first_close_at | Date (UNIX timestamp) | + | statistics.last_assignment_at | Date (UNIX timestamp) | + | statistics.last_assignment_admin_reply_at | Date (UNIX timestamp) | + | statistics.last_contact_reply_at | Date (UNIX timestamp) | + | statistics.last_admin_reply_at | Date (UNIX timestamp) | + | statistics.last_close_at | Date (UNIX timestamp) | + | statistics.last_closed_by_id | String | + | statistics.count_reopens | Integer | + | statistics.count_assignments | Integer | + | statistics.count_conversation_parts | Integer | + | conversation_rating.requested_at | Date (UNIX timestamp) | + | conversation_rating.replied_at | Date (UNIX timestamp) | + | conversation_rating.score | Integer | + | conversation_rating.remark | String | + | conversation_rating.contact_id | String | + | conversation_rating.admin_d | String | + | ai_agent_participated | Boolean | + | ai_agent.resolution_state | String | + | ai_agent.last_answer_type | String | + | ai_agent.rating | Integer | + | ai_agent.rating_remark | String | + | ai_agent.source_type | String | + | ai_agent.source_title | String | + + ### Accepted Operators + + The table below shows the operators you can use to define how you want to search for the value. The operator should be put in as a string (`"="`). The operator has to be compatible with the field's type (eg. you cannot search with `>` for a given string value as it's only compatible for integer's and dates). + + | Operator | Valid Types | Description | + | :------- | :----------------------------- | :----------------------------------------------------------- | + | = | All | Equals | + | != | All | Doesn't Equal | + | IN | All | In Shortcut for `OR` queries Values most be in Array | + | NIN | All | Not In Shortcut for `OR !` queries Values must be in Array | + | > | Integer Date (UNIX Timestamp) | Greater (or equal) than | + | < | Integer Date (UNIX Timestamp) | Lower (or equal) than | + | ~ | String | Contains | + | !~ | String | Doesn't Contain | + | ^ | String | Starts With | + | $ | String | Ends With | responses: '200': description: successful @@ -6258,107 +6381,84 @@ paths: examples: successful: value: - type: ticket - id: '474' - ticket_id: '37' - ticket_attributes: {} - ticket_state: submitted - ticket_type: - type: ticket_type - id: '79' - name: my-ticket-type-1 - description: my ticket type description is awesome. - icon: "\U0001F981" - workspace_id: this_is_an_id404_that_should_be_at_least_ - archived: false - created_at: 1719492947 - updated_at: 1719492947 - is_internal: false - ticket_type_attributes: - type: list - data: [] - category: Customer - contacts: - type: contact.list - contacts: - - type: contact - id: 667d61518a68186f43bafe45 - external_id: '70' - admin_assignee_id: '0' - team_assignee_id: '0' - created_at: 1719492945 - updated_at: 1719492947 - ticket_parts: - type: ticket_part.list - ticket_parts: - - type: ticket_part - id: '117' - part_type: comment - body: "

Comment for message

" - created_at: 1719492945 - updated_at: 1719492945 - author: - id: 667d61518a68186f43bafe45 - type: user - name: Joe Bloggs - email: joe@bloggs.com - attachments: [] - redacted: false - - type: ticket_part - id: '118' - part_type: ticket_state_updated_by_admin - ticket_state: submitted - previous_ticket_state: submitted - created_at: 1719492947 - updated_at: 1719492947 + type: conversation.list + pages: + type: pages + page: 1 + per_page: 5 + total_pages: 1 + total_count: 1 + conversations: + - type: conversation + id: '378' + created_at: 1719492843 + updated_at: 1719492843 + waiting_since: + snoozed_until: + source: + type: conversation + id: '403918266' + delivered_as: admin_initiated + subject: '' + body: "

this is the message body

" author: - id: '991267667' - type: bot - name: Operator - email: operator+this_is_an_id404_that_should_be_at_least_@intercom.io + type: admin + id: '991267591' + name: Ciaran180 Lee + email: admin180@email.com attachments: [] + url: redacted: false - total_count: 2 - open: true - linked_objects: - type: list - data: [] - total_count: 0 - has_more: false - category: Customer - is_shared: true - ticket_state_internal_label: Submitted - ticket_state_external_label: Submitted - schema: - "$ref": "#/components/schemas/ticket" - '400': - description: Bad request - content: - application/json: - examples: - Bad request: - value: - type: error.list - request_id: 74656c1a-0a17-4c80-a7b9-66fa45c6d71b - errors: - - code: parameter_invalid - message: Ticket type is not a customer ticket type + contacts: + type: contact.list + contacts: + - type: contact + id: 667d60ea8a68186f43bafdec + 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/error" + "$ref": "#/components/schemas/paginated_conversation_response" requestBody: content: application/json: schema: - "$ref": "#/components/schemas/convert_conversation_to_ticket_request" + "$ref": "#/components/schemas/search_request" examples: successful: summary: successful value: - ticket_type_id: '79' - bad_request: - summary: Bad request - value: - ticket_type_id: '80' + query: + operator: AND + value: + - field: created_at + operator: ">" + value: '1306054154' + pagination: + per_page: 5 "/data_attributes": get: summary: List all data attributes @@ -6388,7 +6488,7 @@ paths: type: boolean tags: - Data Attributes - operationId: lisDataAttributes + operationId: listDataAttributes description: You can fetch a list of all data attributes belonging to a workspace for contacts, companies or conversations. responses: @@ -6771,7 +6871,7 @@ paths: options: - value: 1-10 archived: false - "/data_attributes/{id}": + "/data_attributes/{data_attribute_id}": put: summary: Update a data attribute parameters: @@ -6779,13 +6879,13 @@ paths: in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: id + - name: data_attribute_id in: path required: true description: The data attribute id - example: 1 + example: "1" schema: - type: integer + type: string tags: - Data Attributes operationId: updateDataAttribute @@ -7037,6 +7137,13 @@ paths: description: summary flag schema: type: boolean + - name: per_page + in: query + required: false + description: How many results to display per page. Defaults to 15 + example: 15 + schema: + type: integer tags: - Data Events operationId: lisDataEvents @@ -7521,7 +7628,7 @@ paths: newsfeed_assignments: [] total_count: 2 schema: - "$ref": "#/components/schemas/paginated_response" + "$ref": "#/components/schemas/paginated_news_item_response" '401': description: Unauthorized content: @@ -7616,7 +7723,7 @@ paths: newsfeed_assignments: - newsfeed_id: 53 published_at: 1664638214 - "/news/news_items/{id}": + "/news/news_items/{news_item_id}": get: summary: Retrieve a news item parameters: @@ -7624,13 +7731,13 @@ paths: in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: id + - name: news_item_id in: path required: true description: The unique identifier for the news item which is given by Intercom. - example: 123 + example: "123" schema: - type: integer + type: string tags: - News operationId: retrieveNewsItem @@ -7700,13 +7807,13 @@ paths: in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: id + - name: news_item_id in: path required: true description: The unique identifier for the news item which is given by Intercom. - example: 123 + example: "123" schema: - type: integer + type: string tags: - News operationId: updateNewsItem @@ -7795,13 +7902,13 @@ paths: in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: id + - name: news_item_id in: path required: true description: The unique identifier for the news item which is given by Intercom. - example: 123 + example: "123" schema: - type: integer + type: string tags: - News operationId: deleteNewsItem @@ -7847,27 +7954,18 @@ paths: message: Access Token Invalid schema: "$ref": "#/components/schemas/error" - "/news/newsfeeds/{id}/items": + "/news/newsfeeds": get: - summary: List all live newsfeed items + summary: List all newsfeeds parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: 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 + operationId: listNewsfeeds + description: You can fetch a list of all newsfeeds responses: '200': description: successful @@ -7879,13 +7977,23 @@ paths: type: list pages: page: 1 - per_page: 20 - total_pages: 0 + per_page: 10 + total_pages: 1 type: pages - data: [] - total_count: 0 + data: + - id: '68' + type: newsfeed + name: Visitor Feed + created_at: 1719492987 + updated_at: 1719492987 + - id: '69' + type: newsfeed + name: Visitor Feed + created_at: 1719492987 + updated_at: 1719492987 + total_count: 2 schema: - "$ref": "#/components/schemas/paginated_response" + "$ref": "#/components/schemas/paginated_newsfeed_response" '401': description: Unauthorized content: @@ -7894,24 +8002,32 @@ paths: Unauthorized: value: type: error.list - request_id: de07bbcf-64ff-4fc8-a7e5-fcbe772b85a5 + request_id: d00f8d67-1e7c-464b-b0b7-b2409d706076 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" - "/news/newsfeeds": + "/news/newsfeeds/{newsfeed_id}": get: - summary: List all newsfeeds + 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: listNewsfeeds - description: You can fetch a list of all newsfeeds + operationId: retrieveNewsfeed + description: You can fetch the details of a single newsfeed responses: '200': description: successful @@ -7920,26 +8036,13 @@ paths: 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: 1719492987 - updated_at: 1719492987 - - id: '69' - type: newsfeed - name: Visitor Feed - created_at: 1719492987 - updated_at: 1719492987 - total_count: 2 + id: '72' + type: newsfeed + name: Visitor Feed + created_at: 1719492988 + updated_at: 1719492988 schema: - "$ref": "#/components/schemas/paginated_response" + "$ref": "#/components/schemas/newsfeed" '401': description: Unauthorized content: @@ -7948,32 +8051,33 @@ paths: Unauthorized: value: type: error.list - request_id: d00f8d67-1e7c-464b-b0b7-b2409d706076 + request_id: 185ce494-34e2-4cda-85cb-c51ad7281292 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" - "/news/newsfeeds/{id}": + "/news/newsfeeds/{newsfeed_id}/items": get: - summary: Retrieve a newsfeed + summary: List all live newsfeed items parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: id + - name: newsfeed_id in: path required: true description: The unique identifier for the news feed item which is given by Intercom. - example: '123' + example: "123" schema: type: string tags: - News - operationId: retrieveNewsfeed - description: You can fetch the details of a single newsfeed + operationId: listLiveNewsfeedItems + description: You can fetch a list of all news items that are live on a given + newsfeed responses: '200': description: successful @@ -7982,13 +8086,16 @@ paths: examples: successful: value: - id: '72' - type: newsfeed - name: Visitor Feed - created_at: 1719492988 - updated_at: 1719492988 + type: list + pages: + page: 1 + per_page: 20 + total_pages: 0 + type: pages + data: [] + total_count: 0 schema: - "$ref": "#/components/schemas/newsfeed" + "$ref": "#/components/schemas/paginated_news_item_response" '401': description: Unauthorized content: @@ -7997,13 +8104,13 @@ paths: Unauthorized: value: type: error.list - request_id: 185ce494-34e2-4cda-85cb-c51ad7281292 + request_id: de07bbcf-64ff-4fc8-a7e5-fcbe772b85a5 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" - "/notes/{id}": + "/notes/{note_id}": get: summary: Retrieve a note parameters: @@ -8011,13 +8118,13 @@ paths: in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: id + - name: note_id in: path required: true description: The unique identifier of a given note - example: 1 + example: "1" schema: - type: integer + type: string tags: - Notes operationId: retrieveNote @@ -8131,7 +8238,7 @@ paths: message: Access Token Invalid schema: "$ref": "#/components/schemas/error" - "/segments/{id}": + "/segments/{segment_id}": get: summary: Retrieve a segment parameters: @@ -8139,11 +8246,11 @@ paths: in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: id + - name: segment_id in: path required: true description: The unique identified of a given segment. - example: '123' + example: "123" schema: type: string tags: @@ -8501,7 +8608,7 @@ paths: name: test users: - id: '123' - "/tags/{id}": + "/tags/{tag_id}": get: summary: Find a specific tag parameters: @@ -8509,10 +8616,10 @@ paths: in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: id + - name: tag_id in: path description: The unique identifier of a given tag - example: '123' + example: "123" required: true schema: type: string @@ -8570,10 +8677,10 @@ paths: in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: id + - name: tag_id in: path description: The unique identifier of a given tag - example: '123' + example: "123" required: true schema: type: string @@ -8642,138 +8749,16 @@ paths: 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: 006b2c8f-9a29-463e-be69-ad213576aee6 - errors: - - code: unauthorized - message: Access Token Invalid - schema: - "$ref": "#/components/schemas/error" - "/teams/{id}": - get: - summary: Retrieve a team - parameters: - - name: Intercom-Version - in: header - schema: - "$ref": "#/components/schemas/intercom_version" - - name: 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: '991267802' - name: team 1 - admin_ids: [] - schema: - "$ref": "#/components/schemas/team" - '404': - description: Team not found - content: - application/json: - examples: - Team not found: - value: - type: error.list - request_id: 4745dfce-7275-4864-abfd-44e0d84bf52a - 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: 110ad8e4-99ed-461a-bd93-92a5cdbaa6b2 - 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: '210' - workspace_id: this_is_an_id600_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: 81 - archived: false - created_at: 1719493013 - updated_at: 1719493013 + description: successful + content: + application/json: + examples: + successful: + value: + type: team.list + teams: [] schema: - "$ref": "#/components/schemas/ticket_type_attribute" + "$ref": "#/components/schemas/team_list" '401': description: Unauthorized content: @@ -8782,76 +8767,60 @@ paths: Unauthorized: value: type: error.list - request_id: 3bc672fa-e051-4ede-b6e9-79f518231ba9 + request_id: 006b2c8f-9a29-463e-be69-ad213576aee6 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/{id}": - put: - summary: Update an existing attribute for a ticket type + "/teams/{team_id}": + get: + summary: Retrieve a team 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: id + - name: team_id in: path required: true - description: The unique identifier for the ticket type attribute which is - given by Intercom. + description: The unique identifier of a given team. + example: "123" schema: type: string tags: - - Ticket Type Attributes - description: You can update an existing attribute for a ticket type. - operationId: updateTicketTypeAttribute + - 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: Ticket Type Attribute updated + description: successful content: application/json: examples: - Ticket Type Attribute updated: + successful: value: - type: ticket_type_attribute - id: '215' - workspace_id: this_is_an_id604_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: 83 - archived: false - created_at: 1719493013 - updated_at: 1719493014 + type: team + id: '991267802' + name: team 1 + admin_ids: [] schema: - "$ref": "#/components/schemas/ticket_type_attribute" + "$ref": "#/components/schemas/team" + '404': + description: Team not found + content: + application/json: + examples: + Team not found: + value: + type: error.list + request_id: 4745dfce-7275-4864-abfd-44e0d84bf52a + errors: + - code: team_not_found + message: Team not found + schema: + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -8860,22 +8829,12 @@ paths: Unauthorized: value: type: error.list - request_id: 6e45414c-e627-4769-bdbd-d51f2c19e1e9 + request_id: 110ad8e4-99ed-461a-bd93-92a5cdbaa6b2 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 @@ -9082,7 +9041,7 @@ paths: description: Customer Report Template icon: "\U0001F39F️" category: Customer - "/ticket_types/{id}": + "/ticket_types/{ticket_type_id}": get: summary: Retrieve a ticket type parameters: @@ -9090,7 +9049,7 @@ paths: in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: id + - name: ticket_type_id in: path required: true description: The unique identifier for the ticket type which is given by Intercom. @@ -9198,7 +9157,7 @@ paths: in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: id + - name: ticket_type_id in: path required: true description: The unique identifier for the ticket type which is given by Intercom. @@ -9246,168 +9205,46 @@ paths: default: true ticket_type_id: 92 archived: false - created_at: 1719493018 - updated_at: 1719493018 - - type: ticket_type_attribute - id: '240' - workspace_id: this_is_an_id620_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: 92 - archived: false - created_at: 1719493018 - updated_at: 1719493018 - - type: ticket_type_attribute - id: '239' - workspace_id: this_is_an_id620_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: 92 - archived: false - created_at: 1719493018 - updated_at: 1719493018 - category: Customer - schema: - "$ref": "#/components/schemas/ticket_type" - '401': - description: Unauthorized - content: - application/json: - examples: - Unauthorized: - value: - type: error.list - request_id: 2b0554fe-ba10-41d4-ab7b-715c2b7b8e47 - 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/{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: id - in: path - required: true - schema: - title: Ticket ID - type: string - description: The id of the ticket to target. - example: '123' - tags: - - Tickets - responses: - '400': - description: User reply - content: - application/json: - examples: - User reply: - value: - type: error.list - request_id: b8b42c55-347c-4704-b4c1-92220c01f4ac - errors: - - code: parameter_mismatch - message: User replies are not allowed on Backoffice tickets - schema: - "$ref": "#/components/schemas/error" - '200': - description: Admin quick_reply reply - content: - application/json: - examples: - Admin note reply: - value: - type: ticket_part - id: '122' - part_type: note - body: |- -

An Unordered HTML List

- -

An Ordered HTML List

-
    -
  1. Coffee
    2. -
  2. Tea
    3. -
  3. Milk
    4. -
- created_at: 1719493024 - updated_at: 1719493024 - author: - id: '991267829' - type: admin - name: Ciaran375 Lee - email: admin375@email.com - attachments: [] - redacted: false - Admin quick_reply reply: - value: - type: ticket_part - id: '124' - part_type: quick_reply - created_at: 1719493029 - updated_at: 1719493029 - author: - id: '991267834' - type: admin - name: Ciaran379 Lee - email: admin379@email.com - attachments: [] - redacted: false - schema: - "$ref": "#/components/schemas/ticket_reply" - '404': - description: Not found - content: - application/json: - examples: - Not found: - value: - type: error.list - request_id: c23e8dab-6102-483c-bb1b-c62923be35ab - errors: - - code: not_found - message: Resource Not Found + created_at: 1719493018 + updated_at: 1719493018 + - type: ticket_type_attribute + id: '240' + workspace_id: this_is_an_id620_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: 92 + archived: false + created_at: 1719493018 + updated_at: 1719493018 + - type: ticket_type_attribute + id: '239' + workspace_id: this_is_an_id620_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: 92 + archived: false + created_at: 1719493018 + updated_at: 1719493018 + category: Customer schema: - "$ref": "#/components/schemas/error" + "$ref": "#/components/schemas/ticket_type" '401': description: Unauthorized content: @@ -9416,7 +9253,7 @@ paths: Unauthorized: value: type: error.list - request_id: bb012854-cca8-4fa7-972e-6c38204e8294 + request_id: 2b0554fe-ba10-41d4-ab7b-715c2b7b8e47 errors: - code: unauthorized message: Access Token Invalid @@ -9426,93 +9263,58 @@ paths: content: application/json: schema: - oneOf: - - "$ref": "#/components/schemas/contact_reply_ticket_request" - - "$ref": "#/components/schemas/admin_reply_ticket_request" + "$ref": "#/components/schemas/update_ticket_type_request_body" examples: - user_reply: - summary: User reply - value: - message_type: comment - type: user - intercom_user_id: 667d619d8a68186f43bafe82 - body: Thanks again :) - admin_note_reply: - summary: Admin note reply - value: - message_type: note - type: admin - admin_id: 991267829 - body: "

An Unordered HTML List

An Ordered HTML List

- \
  1. Coffee
  2. Tea
  3. Milk
- \ " - admin_quick_reply_reply: - summary: Admin quick_reply reply - value: - message_type: quick_reply - type: admin - admin_id: 991267834 - reply_options: - - text: 'Yes' - uuid: 22d6d1f4-1a19-41d0-94c2-e54031f78aca - - text: 'No' - uuid: fbc3dbe0-ec0c-4fb6-826d-e19127191906 - not_found: - summary: Not found + ticket_type_updated: + summary: Ticket type updated value: - message_type: comment - type: user - intercom_user_id: 667d61a68a68186f43bafe85 - body: Thanks again :) - "/tickets/{ticket_id}/tags": + name: Bug Report 2 + "/ticket_types/{ticket_type_id}/attributes": post: - summary: Add tag to a ticket + summary: Create a new attribute for a ticket type parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: ticket_id + - name: ticket_type_id in: path - description: ticket_id - example: '64619700005694' required: true + description: The unique identifier for the ticket type which is given by Intercom. schema: type: string tags: - - Tags - - Tickets - operationId: attachTagToTicket - description: You can tag a specific ticket. This will return a tag object for - the tag that was added to the ticket. + - Ticket Type Attributes + description: You can create a new attribute for a ticket type. + operationId: createTicketTypeAttribute responses: '200': - description: successful - content: - application/json: - examples: - successful: - value: - type: tag - id: '134' - name: Manual tag - schema: - "$ref": "#/components/schemas/tag" - '404': - description: Ticket not found + description: Ticket Type Attribute created content: application/json: examples: - Ticket not found: + Ticket Type Attribute created: value: - type: error.list - request_id: e11d8f55-82fe-4c0d-b4c6-6f22c6a694e9 - errors: - - code: ticket_not_found - message: Ticket not found + type: ticket_type_attribute + id: '210' + workspace_id: this_is_an_id600_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: 81 + archived: false + created_at: 1719493013 + updated_at: 1719493013 schema: - "$ref": "#/components/schemas/error" + "$ref": "#/components/schemas/ticket_type_attribute" '401': description: Unauthorized content: @@ -9521,7 +9323,7 @@ paths: Unauthorized: value: type: error.list - request_id: a502f48f-c80d-48fd-bea5-cafe7e24d9f9 + request_id: 3bc672fa-e051-4ede-b6e9-79f518231ba9 errors: - code: unauthorized message: Access Token Invalid @@ -9531,94 +9333,66 @@ paths: content: application/json: schema: - type: object - required: - - id - - admin_id - properties: - id: - type: string - description: The unique identifier for the tag which is given by - Intercom - example: '7522907' - admin_id: - type: string - description: The unique identifier for the admin which is given - by Intercom. - example: '780' + "$ref": "#/components/schemas/create_ticket_type_attribute_request" examples: - successful: - summary: successful - value: - id: 134 - admin_id: 991267844 - ticket_not_found: - summary: Ticket not found + ticket_type_attribute_created: + summary: Ticket Type Attribute created value: - id: 135 - admin_id: 991267847 - "/tickets/{ticket_id}/tags/{id}": - delete: - summary: Remove tag from a ticket + 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_id + - name: ticket_type_id in: path - description: ticket_id - example: '64619700005694' required: true + description: The unique identifier for the ticket type which is given by Intercom. schema: type: string - - name: id + - name: attribute_id in: path - description: The unique identifier for the tag which is given by Intercom - example: '7522907' required: true + description: The unique identifier for the ticket type attribute which is + given by Intercom. schema: type: string tags: - - Tags - - Tickets - operationId: detachTagFromTicket - description: You can remove tag from a specific ticket. This will return a tag - object for the tag that was removed from the ticket. + - Ticket Type Attributes + description: You can update an existing attribute for a ticket type. + operationId: updateTicketTypeAttribute responses: '200': - description: successful - content: - application/json: - examples: - successful: - value: - type: tag - id: '137' - name: Manual tag - schema: - "$ref": "#/components/schemas/tag" - '404': - description: Tag not found + description: Ticket Type Attribute updated content: application/json: examples: - Ticket not found: - value: - type: error.list - request_id: ffa08bb4-3994-4132-b9e3-14837e0723e8 - errors: - - code: ticket_not_found - message: Ticket not found - Tag not found: + Ticket Type Attribute updated: value: - type: error.list - request_id: d2385995-502c-4c03-bf4b-93ef3d24037b - errors: - - code: tag_not_found - message: Tag not found + type: ticket_type_attribute + id: '215' + workspace_id: this_is_an_id604_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: 83 + archived: false + created_at: 1719493013 + updated_at: 1719493014 schema: - "$ref": "#/components/schemas/error" + "$ref": "#/components/schemas/ticket_type_attribute" '401': description: Unauthorized content: @@ -9627,38 +9401,22 @@ paths: Unauthorized: value: type: error.list - request_id: 0d3be117-0a9e-4e88-9a05-4fdd7f93d7bc + request_id: 6e45414c-e627-4769-bdbd-d51f2c19e1e9 errors: - code: unauthorized message: Access Token Invalid schema: - "$ref": "#/components/schemas/error" - requestBody: - content: - application/json: - schema: - type: object - required: - - admin_id - properties: - admin_id: - type: string - description: The unique identifier for the admin which is given - by Intercom. - example: '123' + "$ref": "#/components/schemas/error" + requestBody: + content: + application/json: + schema: + "$ref": "#/components/schemas/update_ticket_type_attribute_request" examples: - successful: - summary: successful - value: - admin_id: 991267853 - ticket_not_found: - summary: Ticket not found - value: - admin_id: 991267856 - tag_not_found: - summary: Tag not found + ticket_type_attribute_updated: + summary: Ticket Type Attribute updated value: - admin_id: 991267859 + description: New Attribute Description "/tickets": post: summary: Create a ticket @@ -9804,7 +9562,7 @@ paths: ticket_attributes: _default_title_: example _default_description_: there is a problem - "/tickets/{id}": + "/tickets/{ticket_id}": put: summary: Update a ticket parameters: @@ -9812,7 +9570,7 @@ paths: in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: id + - name: ticket_id in: path required: true description: The unique identifier for the ticket which is given by Intercom @@ -9991,26 +9749,416 @@ paths: ticket_state_internal_label: In progress ticket_state_external_label: In progress schema: - "$ref": "#/components/schemas/ticket" + "$ref": "#/components/schemas/ticket" + '404': + description: Assignee not found + content: + application/json: + examples: + Admin not found: + value: + type: error.list + request_id: 809aceaa-c073-4e2a-96c3-a25e15576946 + errors: + - code: assignee_not_found + message: Assignee not found + Assignee not found: + value: + type: error.list + request_id: 639b5b51-1eb9-4c06-8de4-d9b0e30fff05 + errors: + - code: assignee_not_found + message: Assignee not found + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: e5202025-e8f9-400a-9107-192ae8bfd50c + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + requestBody: + content: + application/json: + schema: + "$ref": "#/components/schemas/update_ticket_request" + examples: + successful_response: + summary: Successful response + value: + ticket_attributes: + _default_title_: example + _default_description_: there is a problem + state: in_progress + assignment: + admin_id: '991267883' + assignee_id: '991267885' + open: true + snoozed_until: 1673609604 + admin_not_found: + summary: Admin not found + value: + ticket_attributes: + _default_title_: example + _default_description_: there is a problem + state: in_progress + assignment: + admin_id: '123' + assignee_id: '991267893' + assignee_not_found: + summary: Assignee not found + value: + ticket_attributes: + _default_title_: example + _default_description_: there is a problem + state: in_progress + assignment: + admin_id: '991267899' + assignee_id: '456' + get: + summary: Retrieve a ticket + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + - name: ticket_id + in: path + required: true + description: The unique identifier for the ticket which is given by Intercom. + schema: + type: string + tags: + - Tickets + operationId: getTicket + description: You can fetch the details of a single ticket. + responses: + '200': + description: Ticket found + content: + application/json: + examples: + Ticket found: + value: + type: ticket + id: '493' + ticket_id: '52' + ticket_attributes: + _default_title_: attribute_value + _default_description_: + ticket_state: submitted + ticket_type: + type: ticket_type + id: '112' + name: my-ticket-type-21 + description: my ticket type description is awesome. + icon: "\U0001F981" + workspace_id: this_is_an_id660_that_should_be_at_least_ + archived: false + created_at: 1719493060 + updated_at: 1719493060 + is_internal: false + ticket_type_attributes: + type: list + data: + - type: ticket_type_attribute + id: '268' + workspace_id: this_is_an_id660_that_should_be_at_least_ + name: _default_title_ + description: ola + data_type: string + input_options: + order: 0 + required_to_create: true + required_to_create_for_contacts: false + visible_on_create: true + visible_to_contacts: false + default: false + ticket_type_id: 112 + archived: false + created_at: 1719493060 + updated_at: 1719493060 + - type: ticket_type_attribute + id: '269' + workspace_id: this_is_an_id660_that_should_be_at_least_ + name: _default_description_ + description: ola + data_type: string + input_options: + order: 0 + required_to_create: true + required_to_create_for_contacts: false + visible_on_create: true + visible_to_contacts: false + default: false + ticket_type_id: 112 + archived: false + created_at: 1719493060 + updated_at: 1719493060 + category: Back-office + contacts: + type: contact.list + contacts: + - type: contact + id: 667d61c48a68186f43bafe91 + external_id: '038050f6-d917-4b9d-89cb-539b1d371172' + admin_assignee_id: '0' + team_assignee_id: '0' + created_at: 1719493061 + updated_at: 1719493061 + ticket_parts: + type: ticket_part.list + ticket_parts: + - type: ticket_part + id: '134' + part_type: ticket_state_updated_by_admin + ticket_state: submitted + previous_ticket_state: submitted + created_at: 1719493061 + updated_at: 1719493061 + author: + id: '991267912' + type: admin + name: Ciaran445 Lee + email: admin445@email.com + attachments: [] + redacted: false + total_count: 1 + open: true + linked_objects: + type: list + data: [] + total_count: 0 + has_more: false + category: Back-office + is_shared: false + ticket_state_internal_label: Submitted + ticket_state_external_label: Submitted + schema: + "$ref": "#/components/schemas/ticket" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: e7ba89f2-3bc8-4fc3-97bc-56f62f342680 + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + "/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. + example: "123" + tags: + - Tickets + responses: + '400': + description: User reply + content: + application/json: + examples: + User reply: + value: + type: error.list + request_id: b8b42c55-347c-4704-b4c1-92220c01f4ac + errors: + - code: parameter_mismatch + message: User replies are not allowed on Backoffice tickets + schema: + "$ref": "#/components/schemas/error" + '200': + description: Admin quick_reply reply + content: + application/json: + examples: + Admin note reply: + value: + type: ticket_part + id: '122' + part_type: note + body: |- +

An Unordered HTML List

+ +

An Ordered HTML List

+
    +
  1. Coffee
    2. +
  2. Tea
    3. +
  3. Milk
    4. +
+ created_at: 1719493024 + updated_at: 1719493024 + author: + id: '991267829' + type: admin + name: Ciaran375 Lee + email: admin375@email.com + attachments: [] + redacted: false + Admin quick_reply reply: + value: + type: ticket_part + id: '124' + part_type: quick_reply + created_at: 1719493029 + updated_at: 1719493029 + author: + id: '991267834' + type: admin + name: Ciaran379 Lee + email: admin379@email.com + attachments: [] + redacted: false + schema: + "$ref": "#/components/schemas/ticket_reply" '404': - description: Assignee not found + description: Not found content: application/json: examples: - Admin not found: + Not found: value: type: error.list - request_id: 809aceaa-c073-4e2a-96c3-a25e15576946 + request_id: c23e8dab-6102-483c-bb1b-c62923be35ab errors: - - code: assignee_not_found - message: Assignee not found - Assignee not found: + - 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: 639b5b51-1eb9-4c06-8de4-d9b0e30fff05 + request_id: bb012854-cca8-4fa7-972e-6c38204e8294 errors: - - code: assignee_not_found - message: Assignee not found + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + requestBody: + content: + application/json: + schema: + oneOf: + - "$ref": "#/components/schemas/contact_reply_ticket_request" + - "$ref": "#/components/schemas/admin_reply_ticket_request" + examples: + user_reply: + summary: User reply + value: + message_type: comment + type: user + intercom_user_id: 667d619d8a68186f43bafe82 + body: Thanks again :) + admin_note_reply: + summary: Admin note reply + value: + message_type: note + type: admin + admin_id: 991267829 + body: "

An Unordered HTML List

An Ordered HTML List

+ \
  1. Coffee
  2. Tea
  3. Milk
+ \ " + admin_quick_reply_reply: + summary: Admin quick_reply reply + value: + message_type: quick_reply + type: admin + admin_id: 991267834 + reply_options: + - text: 'Yes' + uuid: 22d6d1f4-1a19-41d0-94c2-e54031f78aca + - text: 'No' + uuid: fbc3dbe0-ec0c-4fb6-826d-e19127191906 + not_found: + summary: Not found + value: + message_type: comment + type: user + intercom_user_id: 667d61a68a68186f43bafe85 + body: Thanks again :) + "/tickets/{ticket_id}/tags": + post: + summary: Add tag to a ticket + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + - name: ticket_id + in: path + description: ticket_id + example: '64619700005694' + required: true + schema: + type: string + tags: + - Tags + - Tickets + operationId: attachTagToTicket + description: You can tag a specific ticket. This will return a tag object for + the tag that was added to the ticket. + responses: + '200': + description: successful + content: + application/json: + examples: + successful: + value: + type: tag + id: '134' + name: Manual tag + schema: + "$ref": "#/components/schemas/tag" + '404': + description: Ticket not found + content: + application/json: + examples: + Ticket not found: + value: + type: error.list + request_id: e11d8f55-82fe-4c0d-b4c6-6f22c6a694e9 + errors: + - code: ticket_not_found + message: Ticket not found + schema: + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -10019,7 +10167,7 @@ paths: Unauthorized: value: type: error.list - request_id: e5202025-e8f9-400a-9107-192ae8bfd50c + request_id: a502f48f-c80d-48fd-bea5-cafe7e24d9f9 errors: - code: unauthorized message: Access Token Invalid @@ -10029,161 +10177,94 @@ paths: content: application/json: schema: - "$ref": "#/components/schemas/update_ticket_request" + type: object + required: + - id + - admin_id + properties: + id: + type: string + description: The unique identifier for the tag which is given by + Intercom + example: '7522907' + admin_id: + type: string + description: The unique identifier for the admin which is given + by Intercom. + example: '780' examples: - successful_response: - summary: Successful response - value: - ticket_attributes: - _default_title_: example - _default_description_: there is a problem - state: in_progress - assignment: - admin_id: '991267883' - assignee_id: '991267885' - open: true - snoozed_until: 1673609604 - admin_not_found: - summary: Admin not found + successful: + summary: successful value: - ticket_attributes: - _default_title_: example - _default_description_: there is a problem - state: in_progress - assignment: - admin_id: '123' - assignee_id: '991267893' - assignee_not_found: - summary: Assignee not found + id: 134 + admin_id: 991267844 + ticket_not_found: + summary: Ticket not found value: - ticket_attributes: - _default_title_: example - _default_description_: there is a problem - state: in_progress - assignment: - admin_id: '991267899' - assignee_id: '456' - get: - summary: Retrieve a ticket + id: 135 + admin_id: 991267847 + "/tickets/{ticket_id}/tags/{tag_id}": + delete: + summary: Remove tag from a ticket parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: id + - name: ticket_id in: path + description: ticket_id + example: '64619700005694' + 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 - description: The unique identifier for the ticket which is given by Intercom. schema: type: string tags: + - Tags - Tickets - operationId: getTicket - description: You can fetch the details of a single ticket. + operationId: detachTagFromTicket + description: You can remove tag from a specific ticket. This will return a tag + object for the tag that was removed from the ticket. responses: '200': - description: Ticket found + description: successful + content: + application/json: + examples: + successful: + value: + type: tag + id: '137' + name: Manual tag + schema: + "$ref": "#/components/schemas/tag" + '404': + description: Tag not found content: application/json: examples: - Ticket found: + Ticket not found: value: - type: ticket - id: '493' - ticket_id: '52' - ticket_attributes: - _default_title_: attribute_value - _default_description_: - ticket_state: submitted - ticket_type: - type: ticket_type - id: '112' - name: my-ticket-type-21 - description: my ticket type description is awesome. - icon: "\U0001F981" - workspace_id: this_is_an_id660_that_should_be_at_least_ - archived: false - created_at: 1719493060 - updated_at: 1719493060 - is_internal: false - ticket_type_attributes: - type: list - data: - - type: ticket_type_attribute - id: '268' - workspace_id: this_is_an_id660_that_should_be_at_least_ - name: _default_title_ - description: ola - data_type: string - input_options: - order: 0 - required_to_create: true - required_to_create_for_contacts: false - visible_on_create: true - visible_to_contacts: false - default: false - ticket_type_id: 112 - archived: false - created_at: 1719493060 - updated_at: 1719493060 - - type: ticket_type_attribute - id: '269' - workspace_id: this_is_an_id660_that_should_be_at_least_ - name: _default_description_ - description: ola - data_type: string - input_options: - order: 0 - required_to_create: true - required_to_create_for_contacts: false - visible_on_create: true - visible_to_contacts: false - default: false - ticket_type_id: 112 - archived: false - created_at: 1719493060 - updated_at: 1719493060 - category: Back-office - contacts: - type: contact.list - contacts: - - type: contact - id: 667d61c48a68186f43bafe91 - external_id: '038050f6-d917-4b9d-89cb-539b1d371172' - admin_assignee_id: '0' - team_assignee_id: '0' - created_at: 1719493061 - updated_at: 1719493061 - ticket_parts: - type: ticket_part.list - ticket_parts: - - type: ticket_part - id: '134' - part_type: ticket_state_updated_by_admin - ticket_state: submitted - previous_ticket_state: submitted - created_at: 1719493061 - updated_at: 1719493061 - author: - id: '991267912' - type: admin - name: Ciaran445 Lee - email: admin445@email.com - attachments: [] - redacted: false - total_count: 1 - open: true - linked_objects: - type: list - data: [] - total_count: 0 - has_more: false - category: Back-office - is_shared: false - ticket_state_internal_label: Submitted - ticket_state_external_label: Submitted + type: error.list + request_id: ffa08bb4-3994-4132-b9e3-14837e0723e8 + errors: + - code: ticket_not_found + message: Ticket not found + Tag not found: + value: + type: error.list + request_id: d2385995-502c-4c03-bf4b-93ef3d24037b + errors: + - code: tag_not_found + message: Tag not found schema: - "$ref": "#/components/schemas/ticket" + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -10192,12 +10273,38 @@ paths: Unauthorized: value: type: error.list - request_id: e7ba89f2-3bc8-4fc3-97bc-56f62f342680 + request_id: 0d3be117-0a9e-4e88-9a05-4fdd7f93d7bc errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" + requestBody: + content: + application/json: + schema: + type: object + required: + - admin_id + properties: + admin_id: + type: string + description: The unique identifier for the admin which is given + by Intercom. + example: '123' + examples: + successful: + summary: successful + value: + admin_id: 991267853 + ticket_not_found: + summary: Ticket not found + value: + admin_id: 991267856 + tag_not_found: + summary: Tag not found + value: + admin_id: 991267859 "/tickets/search": post: summary: Search tickets @@ -10757,7 +10864,6 @@ components: title: Activity Log type: object description: Activities performed by Admins. - nullable: true properties: id: type: string @@ -10772,6 +10878,8 @@ components: description: String representing the object's type. Always has the value `admin`. example: admin + enum: + - admin id: type: string description: The id representing the admin. @@ -10866,6 +10974,10 @@ components: type: string description: A sentence or two describing the activity. example: Admin updated the app's name to "My App". + required: + - id + - performed_by + - activity_type activity_log_list: title: Paginated Response type: object @@ -10876,6 +10988,8 @@ components: description: String representing the object's type. Always has the value `activity_log.list`. example: activity_log.list + enum: + - activity_log.list pages: "$ref": "#/components/schemas/cursor_pages" activity_logs: @@ -10883,11 +10997,13 @@ components: description: An array of activity logs items: "$ref": "#/components/schemas/activity_log" + required: + - type + - activity_logs activity_log_metadata: title: Activity Log Metadata type: object description: Additional data provided about Admin activity. - nullable: true properties: sign_in_method: type: string @@ -10940,7 +11056,6 @@ components: addressable_list: title: Addressable List type: object - nullable: false description: A list used to access other resources from a parent model. properties: type: @@ -10957,19 +11072,33 @@ components: format: uri description: Url to get more company resources for this contact example: "/contacts/5ba682d23d7cf92bef87bfd4/notes" + required: + - type + - id + - url admin: title: Admin type: object x-tags: - Admins description: Admins are teammate accounts that have access to a workspace. - nullable: true + required: + - id + - name + - email + - job_title + - away_mode_enabled + - away_mode_reassign + - has_inbox_seat + - team_ids properties: type: type: string description: String representing the object's type. Always has the value `admin`. example: admin + enum: + - admin id: type: string description: The id representing the admin. @@ -11025,15 +11154,19 @@ components: description: String representing the object's type. Always has the value `admin.list`. example: admin.list + enum: + - admin.list admins: type: array description: A list of admins associated with a given workspace. items: "$ref": "#/components/schemas/admin" + required: + - type + - admins admin_priority_level: title: Admin Priority Level type: object - nullable: true description: Admin priority levels for the team properties: primary_admin_ids: @@ -11168,13 +11301,14 @@ components: title: Admin type: object description: Admins are the teammate accounts that have access to a workspace - nullable: true properties: type: type: string description: String representing the object's type. Always has the value `admin`. example: admin + enum: + - admin id: type: string description: The id representing the admin. @@ -11222,6 +11356,8 @@ components: description: This is a string that identifies the type of the object. It will always have the value `avatar`. default: avatar + enum: + - avatar example: avatar image_url: type: string @@ -11238,6 +11374,16 @@ components: "$ref": "#/components/schemas/app" nullable: true description: App that the admin belongs to. + required: + - type + - id + - name + - email + - job_title + - away_mode_enabled + - away_mode_reassign + - has_inbox_seat + - team_ids ai_agent: title: AI Agent type: object @@ -11297,11 +11443,12 @@ components: nullable: true content_sources: "$ref": "#/components/schemas/content_sources_list" + required: + - source_type app: title: App type: object description: App is a workspace on Intercom - nullable: true properties: type: type: string @@ -11332,6 +11479,14 @@ components: type: boolean description: Whether or not the app uses identity verification. example: false + required: + - type + - id_code + - name + - region + - timezone + - created_at + - identity_verification article: title: Article type: object @@ -11350,16 +11505,13 @@ components: title: Article Content type: object description: The Content of an Article. - nullable: true properties: type: type: string description: The type of object - `article_content` . enum: - - - article_content example: article_content - nullable: true title: type: string description: The title of the article. @@ -11397,6 +11549,13 @@ components: type: string description: The URL of the article. example: http://intercom.test/help/en/articles/3-default-language + required: + - type + - title + - description + - body + - author_id + - state article_list: title: Articles type: object @@ -11419,9 +11578,29 @@ components: description: An array of Article objects items: "$ref": "#/components/schemas/article_list_item" + required: + - type + - total_count + - data article_list_item: title: Articles type: object + required: + - id + - workspace_id + - title + - description + - body + - author_id + - state + - created_at + - updated_at + - url + - parent_id + - parent_type + - default_locale + - translated_content + - statistics x-tags: - Articles description: The data returned about your articles when you list them. @@ -11573,7 +11752,11 @@ components: type: string description: The text of the title. example: my query - article_search_response: + required: + - article_id + - highlighted_title + - highlighted_summary + search_articles_response: title: Article Search Response type: object x-tags: @@ -11606,11 +11789,14 @@ components: "$ref": "#/components/schemas/article_search_highlights" pages: "$ref": "#/components/schemas/cursor_pages" + required: + - type + - total_count + - data article_statistics: title: Article Statistics type: object description: The statistics of an article. - nullable: true properties: type: type: string @@ -11649,21 +11835,26 @@ components: description: The percentage of sad reactions the article has received against other types of reaction. example: 20.0 + required: + - type + - views + - conversions + - reactions + - happy_reaction_percentage + - neutral_reaction_percentage + - sad_reaction_percentage article_translated_content: title: Article Translated Content type: object description: The Translated Content of an Article. The keys are the locale codes and the values are the translated content of the article. - nullable: true properties: type: type: string description: The type of object - article_translated_content. enum: - - - article_translated_content example: article_translated_content - nullable: true ar: description: The content of the article in Arabic "$ref": "#/components/schemas/article_content" @@ -11961,6 +12152,13 @@ components: nullable: true description: The id of the help center the collection is in. example: '123' + required: + - id + - workspace_id + - name + - created_at + - order + - default_locale collection_list: title: Collections type: object @@ -11983,6 +12181,10 @@ components: description: An array of collection objects items: "$ref": "#/components/schemas/collection" + required: + - type + - total_count + - data company: title: Company type: object @@ -11991,6 +12193,21 @@ components: 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. + required: + - company_id + - id + - app_id + - name + - remote_created_at + - created_at + - updated_at + - last_request_at + - monthly_spend + - session_count + - user_count + - size + - website + - industry properties: type: type: string @@ -12018,6 +12235,8 @@ components: type: string description: Value is always "plan" example: plan + enum: + - plan id: type: string description: The id of the plan @@ -12128,6 +12347,10 @@ components: example: 100 pages: "$ref": "#/components/schemas/cursor_pages" + required: + - type + - total_count + - data company_attached_segments: title: Company Attached Segments type: object @@ -12144,6 +12367,10 @@ components: description: An array containing Segment Objects items: "$ref": "#/components/schemas/segment" + required: + - type + - total_count + - data company_list: title: Companies type: object @@ -12166,13 +12393,16 @@ components: description: An array containing Company Objects. items: "$ref": "#/components/schemas/company" + required: + - type + - total_count + - data 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 @@ -12196,6 +12426,10 @@ components: description: The scroll parameter to use in the next request to fetch the next page of results. example: 25b649f7-4d33-4ef6-88f5-60e5b8244309 + required: + - type + - data + - total_count contact: title: Contact type: object @@ -12203,6 +12437,34 @@ components: - Contacts description: Contact are the objects that represent your leads and users in Intercom. + required: + - id + - workspace_id + - external_id + - role + - email + - phone + - name + - avatar + - owner_id + - social_profiles + - has_hard_bounced + - marked_email_as_spam + - unsubscribed_from_emails + - created_at + - updated_at + - signed_up_at + - 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 properties: type: type: string @@ -12458,6 +12720,10 @@ components: type: boolean description: Whether the contact is archived or not. example: true + required: + - type + - id + - archived contact_attached_companies: title: Contact Attached Companies type: object @@ -12480,10 +12746,13 @@ components: example: 100 pages: "$ref": "#/components/schemas/pages_link" + required: + - type + - companies + - total_count contact_companies: title: Contact companies type: object - nullable: false description: An object containing companies meta data about the companies that a contact has. Up to 10 will be displayed here. Use the url to get more. properties: @@ -12502,6 +12771,10 @@ components: description: Whether there's more Addressable Objects to be viewed. If true, use the url to view all example: true + required: + - url + - total_count + - has_more contact_deleted: title: Contact Deleted type: object @@ -12527,6 +12800,10 @@ components: type: boolean description: Whether the contact is deleted or not. example: true + required: + - type + - id + - deleted contact_list: title: Contact List type: object @@ -12549,17 +12826,21 @@ components: example: 100 pages: "$ref": "#/components/schemas/cursor_pages" + required: + - type + - data + - total_count 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 + enum: + - location country: type: string nullable: true @@ -12575,10 +12856,11 @@ components: nullable: true description: The city that the contact is located in example: Dublin + required: + - type 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: @@ -12602,6 +12884,11 @@ components: description: Whether there's more Addressable Objects to be viewed. If true, use the url to view all example: true + required: + - data + - url + - total_count + - has_more contact_reference: title: Contact Reference type: object @@ -12623,6 +12910,9 @@ components: description: The unique identifier for the contact which is provided by the Client. example: f3b87a2e09d514c6c2e79b9a + required: + - type + - id contact_reply_base_request: title: Contact Reply Base Object type: object @@ -12779,10 +13069,12 @@ components: description: Segment objects associated with the contact. items: "$ref": "#/components/schemas/segment" + required: + - type + - data contact_social_profiles: title: Social Profile type: object - nullable: false description: An object containing social profiles that a contact has. properties: data: @@ -12790,10 +13082,11 @@ components: description: A list of social profiles objects associated with the contact. items: "$ref": "#/components/schemas/social_profile" + required: + - data 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: @@ -12817,10 +13110,14 @@ components: description: Whether there's more Addressable Objects to be viewed. If true, use the url to view all example: true + required: + - data + - url + - total_count + - has_more 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: @@ -12844,6 +13141,11 @@ components: description: Whether there's more Addressable Objects to be viewed. If true, use the url to view all example: true + required: + - data + - url + - total_count + - has_more contact_unarchived: title: Contact Unarchived type: object @@ -12869,6 +13171,10 @@ components: type: boolean description: Whether the contact is archived or not. example: false + required: + - type + - id + - archived content_source: title: Content Source type: object @@ -12898,9 +13204,13 @@ components: type: string description: The ISO 639 language code of the content source. example: en + required: + - content_type + - url + - title + - locale content_sources_list: title: Content Source List - nullable: false properties: type: type: string @@ -12917,6 +13227,10 @@ components: description: The content sources used by AI Agent in the conversation. items: "$ref": "#/components/schemas/content_source" + required: + - type + - total_count + - content_sources conversation: title: Conversation type: object @@ -12925,11 +13239,30 @@ components: 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. + required: + - id + - created_at + - updated_at + - source + - contacts + - teammates + - title + - admin_assignee_id + - team_assignee_id + - custom_attributes + - topics + - open + - state + - read + - waiting_since + - snoozed_until properties: type: type: string description: Always conversation. example: conversation + enum: + - conversation id: type: string description: The id representing the conversation. @@ -13046,6 +13379,10 @@ components: type: string description: The name of the file. example: test.json + required: + - content_type + - data + - name conversation_contacts: title: Contacts type: object @@ -13055,7 +13392,6 @@ components: properties: type: type: string - description: '' enum: - contact.list example: contact.list @@ -13066,10 +13402,12 @@ components: conversation feature. items: "$ref": "#/components/schemas/contact_reference" + required: + - type + - contacts 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: @@ -13087,7 +13425,10 @@ components: nullable: true description: '' example: https://developers.intercom.com/ - conversation_list: + required: + - type + - created_at + paginated_conversation_response: title: Conversation List type: object description: Conversations are how you can communicate with users in Intercom. @@ -13111,6 +13452,10 @@ components: example: 12345 pages: "$ref": "#/components/schemas/cursor_pages" + required: + - type + - conversations + - total_count conversation_part: title: Conversation Part type: object @@ -13120,6 +13465,8 @@ components: type: string description: Always conversation_part example: conversation_part + enum: + - conversation_part id: type: string description: The id representing the conversation part. @@ -13171,6 +13518,14 @@ components: type: boolean description: Whether or not the conversation part has been redacted. example: false + required: + - type + - id + - part_type + - created_at + - notified_at + - author + - redacted conversation_part_author: title: Conversation part author type: object @@ -13195,6 +13550,11 @@ components: format: email description: The email of the author example: operator+abcd1234@intercom.io + required: + - type + - id + - name + - email conversation_parts: title: Conversation Parts type: object @@ -13220,10 +13580,13 @@ components: type: integer description: '' example: 2 + required: + - type + - conversation_parts + - total_count 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: @@ -13246,6 +13609,12 @@ components: "$ref": "#/components/schemas/contact_reference" teammate: "$ref": "#/components/schemas/reference" + required: + - rating + - remark + - created_at + - contact + - teammate conversation_source: title: Conversation source type: object @@ -13297,10 +13666,16 @@ components: description: Whether or not the source message has been redacted. Only applicable for contact initiated messages. example: false + required: + - type + - id + - delivered_as + - subject + - author + - redacted 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: @@ -13308,6 +13683,8 @@ components: type: string description: '' example: conversation_statistics + enum: + - conversation_statistics time_to_assignment: type: integer description: Duration until last assignment before first admin reply. In @@ -13395,10 +13772,11 @@ components: type: integer description: Total number of conversation parts. example: 1 + required: + - type 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: @@ -13412,6 +13790,9 @@ components: (wrote at least one conversation part). items: "$ref": "#/components/schemas/reference" + required: + - type + - teammates convert_conversation_to_ticket_request: description: You can convert a Conversation to a Ticket type: object @@ -13491,7 +13872,6 @@ components: description: You can create an Article type: object title: Create Article Request Payload - nullable: true properties: title: type: string @@ -13835,7 +14215,6 @@ components: description: You can create a message type: object title: Create Message Request Payload - nullable: true properties: message_type: type: string @@ -13924,7 +14303,6 @@ components: type: object title: Create Or Update Company Request Payload description: You can create or update a Company - nullable: true properties: name: type: string @@ -13993,7 +14371,6 @@ components: description: You can create an phone switch type: object title: Create Phone Switch Request Payload - nullable: true properties: phone: type: string @@ -14141,7 +14518,6 @@ components: 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 @@ -14179,7 +14555,6 @@ components: 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 @@ -14201,6 +14576,8 @@ components: type: integer description: Total number of pages example: 13 + required: + - type custom_attributes: title: Custom Attributes type: object @@ -14216,7 +14593,6 @@ components: 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 @@ -14240,6 +14616,9 @@ components: description: The custom attributes you have set on the custom object instance. additionalProperties: type: string + required: + - id + - type customer_request: type: object nullable: true @@ -14369,6 +14748,13 @@ components: type: string description: Teammate who created the attribute. Only applicable to CDAs example: '5712945' + required: + - type + - name + - full_name + - label + - description + - data_type data_attribute_list: title: Data Attribute List type: object @@ -14386,6 +14772,9 @@ components: description: A list of data attributes items: "$ref": "#/components/schemas/data_attribute" + required: + - type + - data data_event: title: Data Event type: object @@ -14464,6 +14853,9 @@ components: since: type: string example: https://api.intercom.io/events?intercom_user_id=63a0979a5eeebeaf28dd56ba&type=user&since=1389913941065 + required: + - type + - events data_event_summary: title: Data Event Summary type: object @@ -14492,11 +14884,16 @@ components: description: A summary of data events items: "$ref": "#/components/schemas/data_event_summary_item" + required: + - type + - email + - intercom_user_id + - user_id + - events 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 @@ -14518,6 +14915,12 @@ components: type: string description: The description of the event example: A user placed an order + required: + - name + - first + - last + - count + - description data_export: title: Data Export type: object @@ -14526,7 +14929,7 @@ components: description: The data export api is used to view all message sent & viewed in a given timeframe. properties: - job_identfier: + job_identifier: type: string description: The identifier for your job. example: orzzsbd7hk67xyu @@ -14549,6 +14952,11 @@ components: type: string description: The location where you can download your data. example: https://api.intercom.test/download/messages/data/example + required: + - job_identifier + - status + - download_expires_at + - download_url data_export_csv: title: Data Export CSV type: object @@ -14645,6 +15053,15 @@ components: first_hard_bounce: type: integer description: The first time this message hard bounced for this user + required: + - user_id + - company_id + - email + - name + - ruleset_id + - content_id + - content_type + - content_title deleted_article_object: title: Deleted Article Object type: object @@ -14665,6 +15082,10 @@ components: type: boolean description: Whether the article was deleted successfully or not. example: true + required: + - id + - object + - deleted deleted_collection_object: title: Deleted Collection Object type: object @@ -14685,6 +15106,10 @@ components: type: boolean description: Whether the collection was deleted successfully or not. example: true + required: + - id + - object + - deleted deleted_company_object: title: Deleted Company Object type: object @@ -14704,6 +15129,10 @@ components: type: boolean description: Whether the company was deleted successfully or not. example: true + required: + - id + - object + - deleted deleted_object: title: Deleted Object type: object @@ -14724,6 +15153,10 @@ components: type: boolean description: Whether the news item was deleted successfully or not. example: true + required: + - id + - object + - deleted detach_contact_from_conversation_request: properties: admin_id: @@ -14807,20 +15240,25 @@ components: type: integer description: The height of the file in pixels, if applicable example: 1964 + required: + - type + - name + - url + - content_type + - filesize + - width + - height 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. @@ -14829,19 +15267,20 @@ components: type: string description: The description of the collection. Only available for collections. example: " Collection description" + required: + - type + - name + - 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: @@ -14955,6 +15394,8 @@ components: zh-TW: description: The content of the group in Chinese (Taiwan) "$ref": "#/components/schemas/group_content" + required: + - type help_center: title: Help Center type: object @@ -14995,6 +15436,13 @@ components: type: string description: The display name of the Help Center only seen by teammates. example: Intercom Help Center + required: + - id + - workspace_id + - created_at + - identifier + - website_turned_on + - display_name help_center_list: title: Help Centers type: object @@ -15013,6 +15461,9 @@ components: description: An array of Help Center objects items: "$ref": "#/components/schemas/help_center" + required: + - type + - data intercom_version: description: Intercom API version.
By default, it's equal to the version set in the app package. @@ -15064,6 +15515,10 @@ components: - example: Customer nullable: true + required: + - type + - id + - category linked_object_list: title: Linked Objects type: object @@ -15089,6 +15544,11 @@ components: description: An array containing the linked conversations and linked tickets. items: "$ref": "#/components/schemas/linked_object" + required: + - type + - total_count + - has_more + - data merge_contacts_request: description: Merge contact data. type: object @@ -15104,6 +15564,9 @@ components: description: The unique identifier for the contact to merge into. Must be a user. example: 5ba682d23d7cf92bef87bfd4 + required: + - from + - into message: type: object title: Message @@ -15149,11 +15612,13 @@ components: description: The associated conversation_id example: '64619700005570' required: - - type - - id - - created_at - - body - - message_type + - type + - id + - created_at + - subject + - body + - message_type + - conversation_id multiple_filter_search_request: title: Multiple Filter Search Request description: Search using Intercoms Search APIs with more than one filter. @@ -15266,6 +15731,15 @@ components: format: timestamp description: Timestamp for when the news item was last updated. example: 1610589632 + required: + - type + - id + - workspace_id + - title + - body + - sender_id + - state + - created_at 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. @@ -15360,6 +15834,11 @@ components: format: timestamp description: Timestamp for when the newsfeed was last updated. example: 1674917488 + required: + - id + - type + - name + - created_at newsfeed_assignment: title: Newsfeed Assignment type: object @@ -15381,6 +15860,9 @@ components: news items). On write, this field will be ignored if the news item state is "draft". example: 1674917488 + required: + - newsfeed_id + - published_at note: title: Note type: object @@ -15393,6 +15875,8 @@ components: description: String representing the object's type. Always has the value `note`. example: note + enum: + - note id: type: string description: The id of the note. @@ -15411,6 +15895,8 @@ components: type: string description: String representing the object's type. Always has the value `contact`. + enum: + - contact id: type: string description: The id of the contact. @@ -15422,6 +15908,13 @@ components: type: string description: The body text of the note. example: "

Text for the note.

" + required: + - type + - id + - created_at + - contact + - author + - body note_list: title: Paginated Response type: object @@ -15432,6 +15925,8 @@ components: description: String representing the object's type. Always has the value `list`. example: list + enum: + - list data: type: array description: An array of notes. @@ -15443,6 +15938,10 @@ components: example: 1 pages: "$ref": "#/components/schemas/cursor_pages" + required: + - type + - data + - total_count open_conversation_request: title: Open Conversation Request type: object @@ -15488,31 +15987,63 @@ components: total_pages: type: integer example: 1 - paginated_response: - title: Paginated Response + required: + - type + - page + - per_page + - total_pages + paginated_news_item_response: + title: Paginated News Item Response type: object - description: Paginated Response + description: Paginated News Item 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. + description: A count of the total number of News Items. + example: 1 + data: + type: array + description: An array of News Items + items: + "$ref": "#/components/schemas/news_item" + required: + - type + - total_count + - data + paginated_newsfeed_response: + title: Paginated Newsfeed Response + type: object + description: Paginated Newsfeed Response + properties: + type: + type: string + description: The type of object + enum: + - list + example: list + pages: + "$ref": "#/components/schemas/cursor_pages" + total_count: + type: integer + description: A count of the total number of Newsfeeds. example: 1 data: type: array - description: An array of Objects + description: An array of Newsfeeds items: - anyOf: - - "$ref": "#/components/schemas/news_item" - - "$ref": "#/components/schemas/newsfeed" + "$ref": "#/components/schemas/newsfeed" + required: + - type + - total_count + - data part_attachment: title: Part attachment type: object @@ -15546,6 +16077,14 @@ components: type: integer description: The height of the attachment example: 100 + required: + - type + - name + - url + - content_type + - filesize + - width + - height phone_switch: title: Phone Switch type: object @@ -15564,6 +16103,9 @@ components: description: Phone number in E.164 format, that has received the SMS to continue the conversation in the Messenger. example: "+1 1234567890" + required: + - type + - phone redact_conversation_request: oneOf: - title: Redact Conversation Part Request @@ -15624,6 +16166,8 @@ components: nullable: true description: '' example: 1a2b3c + required: + - type reply_conversation_request: oneOf: - "$ref": "#/components/schemas/contact_reply_conversation_request" @@ -15650,6 +16194,12 @@ components: - Segments description: A segment is a group of your contacts defined by the rules that you set. + required: + - type + - id + - name + - created_at + - person_type properties: type: type: string @@ -15707,6 +16257,9 @@ components: type: object description: A pagination object, which may be empty, indicating no further pages to fetch. + required: + - type + - segments single_filter_search_request: title: Single Filter Search Request description: Search using Intercoms Search APIs with a single filter. @@ -15765,6 +16318,10 @@ components: - `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 + required: + - type + - sla_name + - sla_status snooze_conversation_request: title: Snooze Conversation Request type: object @@ -15807,6 +16364,10 @@ components: format: uri description: The name of the Social media profile example: http://twitter.com/th1sland + required: + - type + - name + - url starting_after_paging: title: 'Pagination: Starting After' type: object @@ -15822,6 +16383,8 @@ components: of results. nullable: true example: your-cursor-from-response + required: + - per_page subscription_type: title: Subscription Types type: object @@ -15872,6 +16435,14 @@ components: - email - sms_message example: email + required: + - type + - id + - state + - default_translation + - translations + - consent_type + - content_types subscription_type_list: title: Subscription Types type: object @@ -15889,6 +16460,9 @@ components: . items: "$ref": "#/components/schemas/subscription_type" + required: + - type + - data tag: title: Tag type: object @@ -15916,6 +16490,12 @@ components: example: 1663597223 applied_by: "$ref": "#/components/schemas/reference" + required: + - type + - id + - name + - applied_at + - applied_by tag_company_request: description: You can tag a single company or a list of companies. type: object @@ -15958,6 +16538,9 @@ components: description: A list of tags objects associated with the workspace . items: "$ref": "#/components/schemas/tag" + required: + - type + - data tag_multiple_users_request: description: You can tag a list of users. type: object @@ -15994,6 +16577,9 @@ components: description: A list of tags objects associated with the conversation. items: "$ref": "#/components/schemas/tag" + required: + - type + - tags team: title: Team type: object @@ -16005,6 +16591,8 @@ components: type: string description: Value is always "team" example: team + enum: + - team id: type: string description: The id of the team @@ -16022,6 +16610,11 @@ components: type: integer admin_priority_level: "$ref": "#/components/schemas/admin_priority_level" + required: + - type + - id + - name + - admin_ids team_list: title: Team List type: object @@ -16038,10 +16631,12 @@ components: description: A list of team objects items: "$ref": "#/components/schemas/team" + required: + - type + - teams team_priority_level: title: Team Priority Level type: object - nullable: true description: Admin priority levels for teams properties: primary_team_ids: @@ -16152,6 +16747,15 @@ components: 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. + required: + - type + - id + - ticket_id + - category + - ticket_attributes + - ticket_state + - ticket_type + - contacts ticket_contacts: title: Contacts type: object @@ -16170,6 +16774,9 @@ components: description: The list of contacts affected by this ticket. items: "$ref": "#/components/schemas/contact_reference" + required: + - type + - contacts ticket_custom_attributes: title: Ticket Attributes type: object @@ -16209,6 +16816,10 @@ components: example: 12345 pages: "$ref": "#/components/schemas/cursor_pages" + required: + - type + - tickets + - total_count ticket_part: title: Ticket Part type: object @@ -16220,6 +16831,8 @@ components: type: string description: Always ticket_part example: ticket_part + enum: + - ticket_part id: type: string description: The id representing the ticket part. @@ -16283,6 +16896,13 @@ components: type: boolean description: Whether or not the ticket part has been redacted. example: false + required: + - type + - id + - part_type + - body + - ticket_state + - created_at ticket_part_author: title: Ticket part author type: object @@ -16312,6 +16932,10 @@ components: format: email description: The email of the author example: operator+abcd1234@intercom.io + required: + - type + - id + - email ticket_parts: title: Ticket Parts type: object @@ -16335,6 +16959,10 @@ components: type: integer description: '' example: 2 + required: + - type + - ticket_parts + - total_count ticket_reply: title: A Ticket Part representing a note, comment, or quick_reply on a ticket type: object @@ -16386,6 +17014,11 @@ components: type: boolean description: Whether or not the ticket part has been redacted. example: false + required: + - type + - id + - part_type + - created_at ticket_request_custom_attributes: title: Ticket Attributes type: object @@ -16421,6 +17054,8 @@ components: description: String representing the object's type. Always has the value `ticket_type`. example: ticket_type + enum: + - ticket_type id: type: string description: The id representing the ticket type. @@ -16463,6 +17098,17 @@ components: type: integer format: timestamp description: The date and time the ticket type was last updated. + required: + - type + - id + - category + - name + - description + - icon + - workspace_id + - ticket_type_attributes + - archived + - created_at ticket_type_attribute: title: Ticket Type Attribute type: object @@ -16475,6 +17121,8 @@ components: description: String representing the object's type. Always has the value `ticket_type_attribute`. example: ticket_type_attribute + enum: + - ticket_type_attribute id: type: string description: The id representing the ticket type attribute. @@ -16545,6 +17193,23 @@ components: type: integer format: timestamp description: The date and time the ticket type attribute was last updated. + required: + - type + - id + - workspace_id + - name + - description + - data_type + - input_options + - order + - required_to_create + - required_to_create_for_contacts + - visible_on_create + - visible_to_contacts + - default + - ticket_type_id + - archived + - created_at ticket_type_attribute_list: title: Ticket Type Attributes type: object @@ -16554,12 +17219,17 @@ components: type: string description: String representing the object's type. Always has the value `ticket_type_attributes.list`. + enum: + - 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" + required: + - type + - ticket_type_attributes ticket_type_list: title: Ticket Types type: object @@ -16569,11 +17239,16 @@ components: type: string description: String representing the object's type. Always has the value `ticket_type.list`. + enum: + - ticket_type_attributes.list ticket_types: type: array description: A list of ticket_types associated with a given workspace. items: "$ref": "#/components/schemas/ticket_type" + required: + - type + - ticket_types translation: title: Translation type: object @@ -16593,6 +17268,10 @@ components: description: The two character identifier for the language of the translation object. example: en + required: + - name + - description + - locale untag_company_request: description: You can tag a single company or a list of companies. type: object @@ -16617,13 +17296,18 @@ components: untag: type: boolean description: Always set to true - example: 'true' + example: true + x-fern-type: literal + required: + - id + - company_id + - untag description: The id or company_id of the company can be passed as input parameters. required: - name - companies - update_article_request: + update_article_request_body: description: You can Update an Article type: object title: Update Article Request Payload @@ -16781,7 +17465,12 @@ components: description: To create list attributes. Provide a set of hashes with `value` as the key of the options you want to make. `data_type` must be `string`. items: - type: string + type: object + required: + - value + properties: + value: + type: string example: - option1 - option2 @@ -16893,7 +17582,7 @@ components: creation of the ticket (it will still be present on previously created tickets) example: false - update_ticket_type_request: + update_ticket_type_request_body: 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/) @@ -17211,6 +17900,17 @@ components: nullable: true description: Identifies if this visitor has do not track enabled. example: false + required: + - type + - id + - user_id + - anonymous + - email + - phone + - name + - app_id + - created_at + - signed_up_at visitor_deleted_object: title: Visitor Deleted Object type: object @@ -17230,6 +17930,10 @@ components: type: string description: Automatically generated identifier for the Visitor. example: 8a88a590-e1c3-41e2-a502-e0649dbf721c + required: + - type + - id + - user_id securitySchemes: bearerAuth: type: http diff --git a/fern/fern.config.json b/fern/fern.config.json index ce47bec..962929a 100644 --- a/fern/fern.config.json +++ b/fern/fern.config.json @@ -1,4 +1,4 @@ { "organization": "intercom", - "version": "0.42.14" + "version": "0.46.4" } \ No newline at end of file diff --git a/fern/generators.yml b/fern/generators.yml index a237418..cd11614 100644 --- a/fern/generators.yml +++ b/fern/generators.yml @@ -1,25 +1,28 @@ api: - path: ../descriptions/2.11/api.intercom.io.yaml - overrides: ./openapi-overrides.yml - settings: - use-title: false + specs: + - openapi: ../descriptions/2.11/api.intercom.io.yaml + overrides: ../openapi-overrides.yml + settings: + title-as-schema-name: false + inline-path-parameters: true groups: ts-sdk: generators: - name: fernapi/fern-typescript-node-sdk - version: 0.34.0 + version: 0.44.3 output: location: npm package-name: intercom-client token: ${FERN_NPM_TOKEN} github: repository: intercom/intercom-node - mode: push - branch: 6.0.0-alpha + mode: pull-request config: namespaceExport: Intercom allowCustomFetcher: true skipResponseValidation: true includeApiReference: true noSerdeLayer: true + enableInlineTypes: true + inlinePathParameters: true smart-casing: true diff --git a/fern/openapi-overrides.yml b/fern/openapi-overrides.yml index c2571a2..562b8be 100644 --- a/fern/openapi-overrides.yml +++ b/fern/openapi-overrides.yml @@ -1,211 +1,316 @@ -paths: +paths: /me: get: x-fern-sdk-group-name: - admins x-fern-sdk-method-name: identify - /admins/{id}/away: - put: - x-fern-sdk-group-name: - - admins - x-fern-sdk-method-name: away + x-fern-request-name: IdentifyAdminRequest /admins/activity_logs: get: x-fern-sdk-group-name: - admins x-fern-sdk-method-name: listAllActivityLogs + x-fern-request-name: ListAllActivityLogsRequest /admins: get: x-fern-sdk-group-name: - admins x-fern-sdk-method-name: list - /admins/{id}: + x-fern-request-name: ListAdminsRequest + /admins/{admin_id}: get: x-fern-sdk-group-name: - admins x-fern-sdk-method-name: find + x-fern-request-name: FindAdminRequest + /admins/{admin_id}/away: + put: + x-fern-sdk-group-name: + - admins + x-fern-sdk-method-name: away + x-fern-request-name: ConfigureAwayAdminRequest /articles: get: + x-fern-pagination: + offset: $request.page + results: $response.data x-fern-sdk-group-name: - articles x-fern-sdk-method-name: list + x-fern-request-name: ListArticlesRequest post: x-fern-sdk-group-name: - articles x-fern-sdk-method-name: create - /articles/{id}: + x-fern-request-name: CreateArticleRequest + /articles/{article_id}: get: x-fern-sdk-group-name: - articles x-fern-sdk-method-name: find + x-fern-request-name: FindArticleRequest put: x-fern-sdk-group-name: - articles x-fern-sdk-method-name: update + x-fern-request-name: UpdateArticleRequest delete: x-fern-sdk-group-name: - articles x-fern-sdk-method-name: delete + x-fern-request-name: DeleteArticleRequest /articles/search: get: x-fern-sdk-group-name: - articles x-fern-sdk-method-name: search + x-fern-request-name: SearchArticlesRequest /help_center/collections: get: + x-fern-pagination: + offset: $request.page + results: $response.data x-fern-sdk-group-name: - - helpCenter + - helpCenters - collections x-fern-sdk-method-name: list + x-fern-request-name: ListCollectionsRequest post: x-fern-sdk-group-name: - - helpCenter + - helpCenters - collections x-fern-sdk-method-name: create - /help_center/collections/{id}: + x-fern-request-name: CreateCollectionRequest + /help_center/collections/{collection_id}: get: x-fern-sdk-group-name: - - helpCenter + - helpCenters - collections x-fern-sdk-method-name: find + x-fern-request-name: FindCollectionRequest put: x-fern-sdk-group-name: - - helpCenter + - helpCenters - collections x-fern-sdk-method-name: update + x-fern-request-name: UpdateCollectionRequest delete: x-fern-sdk-group-name: - - helpCenter + - helpCenters - collections x-fern-sdk-method-name: delete - /help_center/help_centers/{id}: - get: - x-fern-sdk-group-name: - - helpCenter - x-fern-sdk-method-name: find + x-fern-request-name: DeleteCollectionRequest /help_center/help_centers: get: + x-fern-pagination: + offset: $request.page + results: $response.data x-fern-sdk-group-name: - - helpCenter + - helpCenters x-fern-sdk-method-name: list + x-fern-request-name: ListHelpCentersRequest + /help_center/help_centers/{help_center_id}: + get: + x-fern-sdk-group-name: + - helpCenters + x-fern-sdk-method-name: find + x-fern-request-name: FindHelpCenterRequest /companies: get: x-fern-sdk-group-name: - companies x-fern-sdk-method-name: retrieve + x-fern-request-name: RetrieveCompanyRequest post: x-fern-sdk-group-name: - companies - x-fern-sdk-method-name: create - /companies/{id}: + x-fern-sdk-method-name: createOrUpdate + x-fern-request-name: CreateOrUpdateCompanyRequest + /companies/{company_id}: get: x-fern-sdk-group-name: - companies x-fern-sdk-method-name: find + x-fern-request-name: FindCompanyRequest put: x-fern-sdk-group-name: - companies x-fern-sdk-method-name: update + x-fern-request-name: UpdateCompanyRequest delete: x-fern-sdk-group-name: - companies x-fern-sdk-method-name: delete - /companies/{id}/contacts: + x-fern-request-name: DeleteCompanyRequest + /companies/{company_id}/contacts: get: x-fern-sdk-group-name: - companies x-fern-sdk-method-name: listAttachedContacts - /companies/{id}/segments: + x-fern-request-name: ListAttachedContactsRequest + /companies/{company_id}/segments: get: x-fern-sdk-group-name: - companies x-fern-sdk-method-name: listAttachedSegments + x-fern-request-name: ListSegmentsAttachedToCompanyRequest /companies/list: - post: - x-fern-pagination: + post: + x-fern-pagination: offset: $request.page results: $response.data x-fern-sdk-group-name: - companies x-fern-sdk-method-name: list + x-fern-request-name: ListCompaniesRequest /companies/scroll: get: - x-fern-pagination: + x-fern-pagination: cursor: $request.scroll_param next_cursor: $response.scroll_param results: $response.data x-fern-sdk-group-name: - companies x-fern-sdk-method-name: scroll - /contacts/{id}/companies: + x-fern-request-name: ScrollCompaniesRequest + /contacts: + get: + x-fern-pagination: + cursor: $request.starting_after + next_cursor: $response.pages.next.starting_after + results: $response.data + x-fern-sdk-group-name: + - contacts + x-fern-sdk-method-name: list + x-fern-request-name: ListContactsRequest + post: + x-fern-sdk-group-name: + - contacts + x-fern-sdk-method-name: create + x-fern-request-name: CreateContactRequest + /contacts/{contact_id}: get: + x-fern-sdk-group-name: + - contacts + x-fern-sdk-method-name: find + x-fern-request-name: FindContactRequest + put: + x-fern-sdk-group-name: + - contacts + x-fern-sdk-method-name: update + x-fern-request-name: UpdateContactRequest + delete: + x-fern-sdk-group-name: + - contacts + x-fern-sdk-method-name: delete + x-fern-request-name: DeleteContactRequest + /contacts/{contact_id}/companies: + get: + x-fern-pagination: + offset: $request.page + results: $response.companies x-fern-sdk-group-name: - contacts x-fern-sdk-method-name: listAttachedCompanies + x-fern-request-name: ListAttachedCompaniesRequest post: x-fern-sdk-group-name: - companies x-fern-sdk-method-name: attachContact - /contacts/{contact_id}/companies/{id}: + x-fern-request-name: AttachContactToCompanyRequest + requestBody: + content: + application/json: + schema: + properties: + id: + x-fern-property-name: company_id + /contacts/{contact_id}/companies/{company_id}: delete: x-fern-sdk-group-name: - companies x-fern-sdk-method-name: detachContact - /contacts/{id}/notes: + x-fern-request-name: DetachContactFromCompanyRequest + /contacts/{contact_id}/notes: get: + x-fern-pagination: + offset: $request.page + results: $response.data x-fern-sdk-group-name: - notes x-fern-sdk-method-name: list + x-fern-request-name: ListContactNotesRequest post: x-fern-sdk-group-name: - notes x-fern-sdk-method-name: create + x-fern-request-name: CreateContactNoteRequest /contacts/{contact_id}/segments: get: x-fern-sdk-group-name: - contacts x-fern-sdk-method-name: listAttachedSegments + x-fern-request-name: ListSegmentsAttachedToContactRequest /contacts/{contact_id}/subscriptions: get: x-fern-sdk-group-name: - contacts - x-fern-sdk-method-name: listAttachedEmailSubscriptions + x-fern-sdk-method-name: listAttachedSubscriptions + x-fern-request-name: ListAttachedSubscriptionsRequest post: x-fern-sdk-group-name: - contacts - x-fern-sdk-method-name: attachToContact - /contacts/{contact_id}/subscriptions/{id}: + x-fern-sdk-method-name: attachSubscription + x-fern-request-name: AttachSubscriptionToContactRequest + requestBody: + content: + application/json: + schema: + properties: + id: + x-fern-property-name: subscription_id + /contacts/{contact_id}/subscriptions/{subscription_id}: delete: x-fern-sdk-group-name: - contacts - x-fern-sdk-method-name: detachFromContact + x-fern-sdk-method-name: detachSubscription + x-fern-request-name: DetachSubscriptionFromContactRequest /contacts/{contact_id}/tags: get: x-fern-sdk-group-name: - contacts x-fern-sdk-method-name: listAttachedTags + x-fern-request-name: ListTagsAttachedToContactRequest post: x-fern-sdk-group-name: - tags x-fern-sdk-method-name: tagContact - /contacts/{contact_id}/tags/{id}: + x-fern-request-name: TagContactRequest + requestBody: + content: + application/json: + schema: + properties: + id: + x-fern-property-name: tag_id + /contacts/{contact_id}/tags/{tag_id}: delete: x-fern-sdk-group-name: - tags x-fern-sdk-method-name: untagContact - /contacts/{id}: - get: - x-fern-sdk-group-name: - - contacts - x-fern-sdk-method-name: find - put: + x-fern-request-name: UntagContactRequest + /contacts/{contact_id}/archive: + post: x-fern-sdk-group-name: - contacts - x-fern-sdk-method-name: update - delete: + x-fern-sdk-method-name: archive + x-fern-request-name: ArchiveContactRequest + /contacts/{contact_id}/unarchive: + post: x-fern-sdk-group-name: - contacts - x-fern-sdk-method-name: delete + x-fern-sdk-method-name: unarchive + x-fern-request-name: UnarchiveContactRequest /contacts/merge: post: x-fern-sdk-group-name: @@ -213,70 +318,60 @@ paths: x-fern-sdk-method-name: mergeLeadInUser /contacts/search: post: - x-fern-pagination: + x-fern-pagination: cursor: $request.pagination.starting_after next_cursor: $response.pages.next.starting_after results: $response.data x-fern-sdk-group-name: - contacts x-fern-sdk-method-name: search - /contacts: - get: - x-fern-sdk-group-name: - - contacts - x-fern-sdk-method-name: list - post: - x-fern-sdk-group-name: - - contacts - x-fern-sdk-method-name: create - /contacts/{id}/archive: - post: - x-fern-sdk-group-name: - - contacts - x-fern-sdk-method-name: archive - /contacts/{id}/unarchive: - post: - x-fern-sdk-group-name: - - contacts - x-fern-sdk-method-name: unarchive + x-fern-request-name: SearchContactsRequest /conversations/{conversation_id}/tags: post: x-fern-sdk-group-name: - tags x-fern-sdk-method-name: tagConversation - /conversations/{conversation_id}/tags/{id}: + x-fern-request-name: TagConversationRequest + requestBody: + content: + application/json: + schema: + properties: + id: + x-fern-property-name: tag_id + /conversations/{conversation_id}/tags/{tag_id}: delete: x-fern-sdk-group-name: - tags x-fern-sdk-method-name: untagConversation + x-fern-request-name: UntagConversationRequest /conversations: get: + x-fern-pagination: + cursor: $request.starting_after + next_cursor: $response.pages.next.starting_after + results: $response.conversations x-fern-sdk-group-name: - conversations x-fern-sdk-method-name: list + x-fern-request-name: ListConversationsRequest post: x-fern-sdk-group-name: - conversations x-fern-sdk-method-name: create - /conversations/{id}: + x-fern-request-name: CreateConversationRequest + /conversations/{conversation_id}: get: x-fern-sdk-group-name: - conversations x-fern-sdk-method-name: find + x-fern-request-name: FindConversationRequest put: x-fern-sdk-group-name: - conversations x-fern-sdk-method-name: update - /conversations/search: - post: - x-fern-pagination: - cursor: $request.pagination.starting_after - next_cursor: $response.pages.next.starting_after - results: $response.conversations - x-fern-sdk-group-name: - - conversations - x-fern-sdk-method-name: search - /conversations/{id}/reply: + x-fern-request-name: UpdateConversationRequest + /conversations/{conversation_id}/reply: post: requestBody: content: @@ -291,84 +386,154 @@ paths: x-fern-sdk-group-name: - conversations x-fern-sdk-method-name: reply - /conversations/{id}/parts: + x-fern-request-name: ReplyToConversationRequest + /conversations/{conversation_id}/parts: post: x-fern-sdk-group-name: - conversations x-fern-sdk-method-name: manage - /conversations/{id}/run_assignment_rules: + x-fern-request-name: ManageConversationPartsRequest + /conversations/{conversation_id}/run_assignment_rules: post: x-fern-sdk-group-name: - conversations - x-fern-sdk-method-name: assign - /conversations/{id}/customers: + x-fern-sdk-method-name: runAssignmentRules + x-fern-request-name: AutoAssignConversationRequest + /conversations/{conversation_id}/customers: post: x-fern-sdk-group-name: - conversations - x-fern-sdk-method-name: attachContact + x-fern-sdk-method-name: attachContactAsAdmin + x-fern-request-name: AttachContactToConversationRequest /conversations/{conversation_id}/customers/{contact_id}: delete: x-fern-sdk-group-name: - conversations x-fern-sdk-method-name: detachContactAsAdmin - /conversations/redact: + x-fern-request-name: DetachContactFromConversationRequest + /conversations/{conversation_id}/convert: post: x-fern-sdk-group-name: - conversations - x-fern-sdk-method-name: redactConversationPart - /conversations/{id}/convert: + x-fern-sdk-method-name: convertToTicket + x-fern-request-name: ConvertConversationToTicketRequest + /conversations/search: post: + x-fern-pagination: + cursor: $request.pagination.starting_after + next_cursor: $response.pages.next.starting_after + results: $response.conversations x-fern-sdk-group-name: - conversations - x-fern-sdk-method-name: convertToTicket + x-fern-sdk-method-name: search + x-fern-request-name: SearchConversationsRequest + /conversations/redact: + post: + x-fern-sdk-group-name: + - conversations + x-fern-sdk-method-name: redactConversationPart + x-fern-request-name: RedactConversationPartRequest /data_attributes: get: x-fern-sdk-group-name: - dataAttributes x-fern-sdk-method-name: list + x-fern-request-name: ListDataAttributesRequest post: x-fern-sdk-group-name: - dataAttributes x-fern-sdk-method-name: create - /data_attributes/{id}: + x-fern-request-name: CreateDataAttributeRequest + /data_attributes/{data_attribute_id}: put: x-fern-sdk-group-name: - dataAttributes x-fern-sdk-method-name: update + x-fern-request-name: UpdateDataAttributeRequest /events: get: x-fern-sdk-group-name: - events x-fern-sdk-method-name: list + x-fern-request-name: ListEventsRequest + + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + - name: user_id + in: query + required: false + description: user_id query parameter + schema: + type: string + - name: intercom_user_id + in: query + required: false + description: intercom_user_id query parameter + schema: + type: string + - name: email + in: query + required: false + description: email query parameter + schema: + type: string + - 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 + - name: per_page + in: query + required: false + description: How many results to display per page. Defaults to 15 + example: 15 + schema: + type: integer post: x-fern-sdk-group-name: - events x-fern-sdk-method-name: create + x-fern-request-name: CreateEventRequest /events/summaries: post: x-fern-sdk-group-name: - events x-fern-sdk-method-name: summaries + x-fern-request-name: ListEventSummariesRequest /export/content/data: post: x-fern-sdk-group-name: - dataExport x-fern-sdk-method-name: create + x-fern-request-name: CreateDataExportRequest /export/content/data/{job_identifier}: get: x-fern-sdk-group-name: - dataExport x-fern-sdk-method-name: find + x-fern-request-name: FindDataExportRequest /export/cancel/{job_identifier}: post: x-fern-sdk-group-name: - dataExport x-fern-sdk-method-name: cancel + x-fern-request-name: CancelDataExportRequest /download/content/data/{job_identifier}: get: x-fern-sdk-group-name: - dataExport x-fern-sdk-method-name: download + x-fern-request-name: DownloadDataExportRequest /messages: post: requestBody: @@ -384,125 +549,178 @@ paths: x-fern-sdk-group-name: - messages x-fern-sdk-method-name: create + x-fern-request-name: CreateMessageRequest /news/news_items: get: x-fern-sdk-group-name: - news - x-fern-sdk-method-name: listItems + - items + x-fern-sdk-method-name: list + x-fern-request-name: ListNewsItemsRequest post: x-fern-sdk-group-name: - news - x-fern-sdk-method-name: createItem - /news/news_items/{id}: + - items + x-fern-sdk-method-name: create + x-fern-request-name: CreateNewsItemRequest + /news/news_items/{news_item_id}: get: x-fern-sdk-group-name: - news - x-fern-sdk-method-name: findItem + - items + x-fern-sdk-method-name: find + x-fern-request-name: FindNewsItemRequest put: x-fern-sdk-group-name: - news - x-fern-sdk-method-name: updateItem + - items + x-fern-sdk-method-name: update + x-fern-request-name: UpdateNewsItemRequest delete: x-fern-sdk-group-name: - news - x-fern-sdk-method-name: deleteItem - /news/newsfeeds/{id}/items: - get: - x-fern-sdk-group-name: - - news - x-fern-sdk-method-name: listLiveItems + - items + x-fern-sdk-method-name: delete + x-fern-request-name: DeleteNewsItemRequest /news/newsfeeds: get: x-fern-sdk-group-name: - news + - feeds x-fern-sdk-method-name: list - /news/newsfeeds/{id}: + x-fern-request-name: ListNewsFeedsRequest + /news/newsfeeds/{newsfeed_id}: get: x-fern-sdk-group-name: - news + - feeds x-fern-sdk-method-name: find - /notes/{id}: + x-fern-request-name: FindNewsFeedRequest + /news/newsfeeds/{newsfeed_id}/items: + get: + x-fern-sdk-group-name: + - news + - feeds + x-fern-sdk-method-name: listItems + x-fern-request-name: ListNewsFeedItemsRequest + /notes/{note_id}: get: x-fern-sdk-group-name: - notes x-fern-sdk-method-name: find + x-fern-request-name: FindNoteRequest /segments: get: x-fern-sdk-group-name: - segments x-fern-sdk-method-name: list - /segments/{id}: + x-fern-request-name: ListSegmentsRequest + /segments/{segment_id}: get: x-fern-sdk-group-name: - segments x-fern-sdk-method-name: find + x-fern-request-name: FindSegmentRequest /subscription_types: get: x-fern-sdk-group-name: - - subscriptions - x-fern-sdk-method-name: listTypes + - subscriptionTypes + x-fern-sdk-method-name: list + x-fern-request-name: ListSubscriptionTypesRequest /phone_call_redirects: post: x-fern-sdk-group-name: - - phoneCallRedirect + - phoneCallRedirects x-fern-sdk-method-name: create + x-fern-request-name: CreatePhoneCallRedirectRequest /tags: get: x-fern-sdk-group-name: - tags x-fern-sdk-method-name: list + x-fern-request-name: ListTagsRequest post: x-fern-sdk-group-name: - tags x-fern-sdk-method-name: create - /tags/{id}: + x-fern-request-name: CreateTagRequest + /tags/{tag_id}: get: x-fern-sdk-group-name: - tags x-fern-sdk-method-name: find + x-fern-request-name: FindTagRequest delete: x-fern-sdk-group-name: - tags x-fern-sdk-method-name: delete + x-fern-request-name: DeleteTagRequest /teams: get: x-fern-sdk-group-name: - teams x-fern-sdk-method-name: list - /teams/{id}: + x-fern-request-name: ListTeamsRequest + /teams/{team_id}: get: x-fern-sdk-group-name: - teams x-fern-sdk-method-name: find - /ticket_types/{ticket_type_id}/attributes: - post: - x-fern-sdk-group-name: - - ticketTypeAttributes - x-fern-sdk-method-name: create - /ticket_types/{ticket_type_id}/attributes/{id}: - put: - x-fern-sdk-group-name: - - ticketTypeAttributes - x-fern-sdk-method-name: update + x-fern-request-name: FindTeamRequest /ticket_types: get: x-fern-sdk-group-name: - ticketTypes x-fern-sdk-method-name: list + x-fern-request-name: ListTicketTypesRequest post: x-fern-sdk-group-name: - ticketTypes x-fern-sdk-method-name: create - /ticket_types/{id}: + x-fern-request-name: CreateTicketTypeRequest + /ticket_types/{ticket_type_id}: get: x-fern-sdk-group-name: - ticketTypes x-fern-sdk-method-name: get + x-fern-request-name: FindTicketTypeRequest + put: + x-fern-sdk-group-name: + - ticketTypes + x-fern-sdk-method-name: update + x-fern-request-name: UpdateTicketTypeRequest + /ticket_types/{ticket_type_id}/attributes: + post: + x-fern-sdk-group-name: + - ticketTypes + - attributes + x-fern-sdk-method-name: create + x-fern-request-name: CreateTicketTypeAttributeRequest + /ticket_types/{ticket_type_id}/attributes/{attribute_id}: put: x-fern-sdk-group-name: - ticketTypes + - attributes x-fern-sdk-method-name: update - /tickets/{id}/reply: + x-fern-request-name: UpdateTicketTypeAttributeRequest + /tickets: + post: + x-fern-sdk-group-name: + - tickets + x-fern-sdk-method-name: create + x-fern-request-name: CreateTicketRequest + /tickets/{ticket_id}: + get: + x-fern-sdk-group-name: + - tickets + x-fern-sdk-method-name: get + x-fern-request-name: FindTicketRequest + put: + x-fern-sdk-group-name: + - tickets + x-fern-sdk-method-name: update + x-fern-request-name: UpdateTicketRequest + /tickets/{ticket_id}/reply: post: requestBody: content: @@ -517,53 +735,53 @@ paths: x-fern-sdk-group-name: - tickets x-fern-sdk-method-name: reply + x-fern-request-name: ReplyToTicketRequest /tickets/{ticket_id}/tags: post: x-fern-sdk-group-name: - tags - x-fern-sdk-method-name: attach - /tickets/{ticket_id}/tags/{id}: + x-fern-sdk-method-name: tagTicket + x-fern-request-name: TagTicketRequest + requestBody: + content: + application/json: + schema: + properties: + id: + x-fern-property-name: tag_id + /tickets/{ticket_id}/tags/{tag_id}: delete: x-fern-sdk-group-name: - tags - x-fern-sdk-method-name: detach - /tickets: - post: - x-fern-sdk-group-name: - - tickets - x-fern-sdk-method-name: create - /tickets/{id}: - get: - x-fern-sdk-group-name: - - tickets - x-fern-sdk-method-name: get - put: - x-fern-sdk-group-name: - - tickets - x-fern-sdk-method-name: update + x-fern-sdk-method-name: untagTicket + x-fern-request-name: UntagTicketRequest /tickets/search: post: - x-fern-pagination: + x-fern-pagination: cursor: $request.pagination.starting_after next_cursor: $response.pages.next.starting_after results: $response.tickets x-fern-sdk-group-name: - tickets x-fern-sdk-method-name: search + x-fern-request-name: SearchTicketsRequest /visitors: get: x-fern-sdk-group-name: - visitors x-fern-sdk-method-name: find + x-fern-request-name: FindVisitorRequest put: x-fern-sdk-group-name: - visitors x-fern-sdk-method-name: update + x-fern-request-name: UpdateVisitorRequest /visitors/convert: post: x-fern-sdk-group-name: - visitors x-fern-sdk-method-name: mergeToContact + x-fern-request-name: MergeVisitorToContactRequest components: schemas: intercom_version: @@ -627,13 +845,15 @@ components: type: integer format: date-time nullable: true - description: The time when the contact was last seen (either where the Intercom + 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 + description: + The id of an admin that has been assigned account ownership of the contact example: 123 unsubscribed_from_emails: @@ -678,13 +898,15 @@ components: type: integer format: date-time nullable: true - description: The time when the contact was last seen (either where the Intercom + 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 + description: + The id of an admin that has been assigned account ownership of the contact example: 123 unsubscribed_from_emails: @@ -729,13 +951,15 @@ components: type: integer format: date-time nullable: true - description: The time when the contact was last seen (either where the Intercom + 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 + description: + The id of an admin that has been assigned account ownership of the contact example: 123 unsubscribed_from_emails: @@ -757,14 +981,16 @@ components: properties: id: type: string - description: The unique identifier for the contact (lead or user) which + description: + The unique identifier for the contact (lead or user) which is given by Intercom. example: 8a88a590-e1c3-41e2-a502-e0649dbf721c user_id: null email: null event_name: type: string - description: The name of the event that occurred. This is presented to your + 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`. @@ -791,12 +1017,13 @@ components: user_id: type: string description: Your identifier for the user. - example: '314159' + example: "314159" id: null email: null event_name: type: string - description: The name of the event that occurred. This is presented to your + 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`. @@ -822,14 +1049,16 @@ components: properties: email: type: string - description: An email address for your user. An email should only be used + 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 user_id: null id: null event_name: type: string - description: The name of the event that occurred. This is presented to your + 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`. @@ -854,13 +1083,13 @@ components: properties: null anyOf: - x-fern-type-name: CreateMessageRequestWithEmail - title: 'message_type: `email`.' + title: "message_type: `email`." properties: message_type: type: string - description: 'The kind of message being created.' + description: "The kind of message being created." enum: - - email + - email example: email subject: type: string @@ -872,32 +1101,35 @@ components: example: Hello there template: type: string - description: The style of the outgoing message. Possible values `plain` + description: + The style of the outgoing message. Possible values `plain` or `personal`. example: plain from: x-fern-type-name: CreateMessageRequestFrom type: object - description: The sender of the message. If not provided, the default sender + description: + The sender of the message. If not provided, the default sender will be used. properties: type: type: string description: Always `admin`. enum: - - admin + - admin example: admin id: type: integer description: The identifier for the admin which is given by Intercom. example: 394051 required: - - type - - id + - type + - id to: x-fern-type-name: CreateMessageRequestTo type: object - description: The sender of the message. If not provided, the default sender + description: + The sender of the message. If not provided, the default sender will be used. properties: type: @@ -905,24 +1137,26 @@ components: type: string description: The role associated to the contact - `user` or `lead`. enum: - - user - - lead + - user + - lead example: user id: type: string description: The identifier for the contact which is given by Intercom. example: 536e564f316c83104c000020 required: - - type - - id + - type + - id created_at: type: integer - description: The time the message was created. If not provided, the current + 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 + 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 @@ -934,13 +1168,13 @@ components: - from - to - x-fern-type-name: CreateMessageRequestWithInapp - title: 'message_type: `inapp`.' + title: "message_type: `inapp`." properties: message_type: type: string - description: 'The kind of message being created.' + description: "The kind of message being created." enum: - - inapp + - inapp example: inapp subject: type: string @@ -952,32 +1186,35 @@ components: example: Hello there template: type: string - description: The style of the outgoing message. Possible values `plain` + description: + The style of the outgoing message. Possible values `plain` or `personal`. example: plain from: x-fern-type-name: CreateMessageRequestFrom type: object - description: The sender of the message. If not provided, the default sender + description: + The sender of the message. If not provided, the default sender will be used. properties: type: type: string description: Always `admin`. enum: - - admin + - admin example: admin id: type: integer description: The identifier for the admin which is given by Intercom. example: 394051 required: - - type - - id + - type + - id to: x-fern-type-name: CreateMessageRequestTo type: object - description: The sender of the message. If not provided, the default sender + description: + The sender of the message. If not provided, the default sender will be used. properties: type: @@ -985,24 +1222,26 @@ components: type: string description: The role associated to the contact - `user` or `lead`. enum: - - user - - lead + - user + - lead example: user id: type: string description: The identifier for the contact which is given by Intercom. example: 536e564f316c83104c000020 required: - - type - - id + - type + - id created_at: type: integer - description: The time the message was created. If not provided, the current + 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 + 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 @@ -1020,7 +1259,8 @@ components: properties: id: type: string - description: The unique identifier for the contact which is given by + description: + The unique identifier for the contact which is given by Intercom. example: 8a88a590-e1c3-41e2-a502-e0649dbf721c user_id: null @@ -1050,7 +1290,8 @@ components: properties: id: type: string - description: The unique identifier for the contact which is given by + description: + The unique identifier for the contact which is given by Intercom. example: 8a88a590-e1c3-41e2-a502-e0649dbf721c user_id: null @@ -1087,6 +1328,10 @@ components: description: A unique identified for the visitor which is given by Intercom. example: 8a88a590-e user_id: null + 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. @@ -1104,7 +1349,15 @@ components: user_id: type: string description: A unique identified for the visitor which is given by you. - example: '123' + example: "123" + 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. @@ -1116,6 +1369,12 @@ components: team_mates: 9 required: - user_id + merge_contacts_request: + properties: + from: + x-fern-property-name: lead_id + into: + x-fern-property-name: contact_id securitySchemes: bearerAuth: x-fern-bearer: From 27eba402965114a8c06c797d358c5008e0900ee2 Mon Sep 17 00:00:00 2001 From: Niels Swimberghe <3382717+Swimburger@users.noreply.github.com> Date: Thu, 19 Dec 2024 16:16:25 -0500 Subject: [PATCH 2/2] Reorder OpenAPI spec back to original order --- descriptions/2.11/api.intercom.io.yaml | 5746 ++++++++++++------------ 1 file changed, 2873 insertions(+), 2873 deletions(-) diff --git a/descriptions/2.11/api.intercom.io.yaml b/descriptions/2.11/api.intercom.io.yaml index 678f499..525ad6f 100644 --- a/descriptions/2.11/api.intercom.io.yaml +++ b/descriptions/2.11/api.intercom.io.yaml @@ -56,18 +56,24 @@ paths: has_inbox_seat: true schema: "$ref": "#/components/schemas/admin_with_app" - "/admins": - get: - summary: List all admins + "/admins/{admin_id}/away": + put: + summary: Set an admin to away parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" + - name: admin_id + in: path + required: true + description: The unique identifier of a given admin + schema: + type: string tags: - Admins - operationId: listAdmins - description: You can fetch a list of admins for a given workspace. + operationId: setAwayAdmin + description: You can set an Admin as away for the Inbox. responses: '200': description: Successful response @@ -76,18 +82,30 @@ paths: examples: Successful response: value: - type: admin.list - admins: - - type: admin - email: admin7@email.com - id: '991267397' - name: Ciaran7 Lee - away_mode_enabled: false - away_mode_reassign: false - has_inbox_seat: true - team_ids: [] + type: admin + id: '991267391' + name: Ciaran2 Lee + email: admin2@email.com + away_mode_enabled: true + away_mode_reassign: true + has_inbox_seat: true + team_ids: [] schema: - "$ref": "#/components/schemas/admin_list" + "$ref": "#/components/schemas/admin" + '404': + description: Admin not found + content: + application/json: + examples: + Admin not found: + value: + type: error.list + request_id: 9818bd03-9cc6-4ab8-8e7c-20a45ac58e97 + errors: + - code: admin_not_found + message: Admin for admin_id not found + schema: + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -96,12 +114,49 @@ paths: Unauthorized: value: type: error.list - request_id: 4ba8121e-4a4a-4668-adb2-363c561f3c52 + request_id: 18722269-a019-46c4-87d7-50d0f6f8a990 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" + requestBody: + content: + application/json: + schema: + type: object + required: + - away_mode_enabled + - away_mode_reassign + properties: + away_mode_enabled: + type: boolean + description: Set to "true" to change the status of the admin to + away. + example: true + default: true + away_mode_reassign: + type: boolean + description: Set to "true" to assign any new conversation replies + to your default inbox. + example: false + default: false + examples: + successful_response: + summary: Successful response + value: + away_mode_enabled: true + away_mode_reassign: true + admin_not_found: + summary: Admin not found + value: + away_mode_enabled: true + away_mode_reassign: true + unauthorized: + summary: Unauthorized + value: + away_mode_enabled: true + away_mode_reassign: true "/admins/activity_logs": get: summary: List all activity logs @@ -192,57 +247,38 @@ paths: message: Access Token Invalid schema: "$ref": "#/components/schemas/error" - "/admins/{admin_id}": + "/admins": get: - summary: Retrieve an admin + summary: List all admins parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: admin_id - in: path - required: true - description: The unique identifier of a given admin - example: "123" - schema: - type: string tags: - Admins - operationId: retrieveAdmin - description: You can retrieve the details of a single admin. + operationId: listAdmins + description: You can fetch a list of admins for a given workspace. responses: '200': - description: Admin found - content: - application/json: - examples: - Admin found: - value: - type: admin - id: '991267399' - name: Ciaran9 Lee - email: admin9@email.com - away_mode_enabled: false - away_mode_reassign: false - has_inbox_seat: true - team_ids: [] - schema: - "$ref": "#/components/schemas/admin" - '404': - description: Admin not found + description: Successful response content: application/json: examples: - Admin not found: + Successful response: value: - type: error.list - request_id: 989bdb0b-1e8c-46cc-8953-9733dad40562 - errors: - - code: admin_not_found - message: Admin not found + type: admin.list + admins: + - type: admin + email: admin7@email.com + id: '991267397' + name: Ciaran7 Lee + away_mode_enabled: false + away_mode_reassign: false + has_inbox_seat: true + team_ids: [] schema: - "$ref": "#/components/schemas/error" + "$ref": "#/components/schemas/admin_list" '401': description: Unauthorized content: @@ -251,15 +287,15 @@ paths: Unauthorized: value: type: error.list - request_id: 83978032-1473-4696-b755-b497d46a23cf + request_id: 4ba8121e-4a4a-4668-adb2-363c561f3c52 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" - "/admins/{admin_id}/away": - put: - summary: Set an admin to away + "/admins/{admin_id}": + get: + summary: Retrieve an admin parameters: - name: Intercom-Version in: header @@ -269,26 +305,27 @@ paths: in: path required: true description: The unique identifier of a given admin + example: "123" schema: type: string tags: - Admins - operationId: setAwayAdmin - description: You can set an Admin as away for the Inbox. + operationId: retrieveAdmin + description: You can retrieve the details of a single admin. responses: '200': - description: Successful response + description: Admin found content: application/json: examples: - Successful response: + Admin found: value: type: admin - id: '991267391' - name: Ciaran2 Lee - email: admin2@email.com - away_mode_enabled: true - away_mode_reassign: true + id: '991267399' + name: Ciaran9 Lee + email: admin9@email.com + away_mode_enabled: false + away_mode_reassign: false has_inbox_seat: true team_ids: [] schema: @@ -301,10 +338,10 @@ paths: Admin not found: value: type: error.list - request_id: 9818bd03-9cc6-4ab8-8e7c-20a45ac58e97 + request_id: 989bdb0b-1e8c-46cc-8953-9733dad40562 errors: - code: admin_not_found - message: Admin for admin_id not found + message: Admin not found schema: "$ref": "#/components/schemas/error" '401': @@ -315,49 +352,12 @@ paths: Unauthorized: value: type: error.list - request_id: 18722269-a019-46c4-87d7-50d0f6f8a990 + request_id: 83978032-1473-4696-b755-b497d46a23cf errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" - requestBody: - content: - application/json: - schema: - type: object - required: - - away_mode_enabled - - away_mode_reassign - properties: - away_mode_enabled: - type: boolean - description: Set to "true" to change the status of the admin to - away. - example: true - default: true - away_mode_reassign: - type: boolean - description: Set to "true" to assign any new conversation replies - to your default inbox. - example: false - default: false - examples: - successful_response: - summary: Successful response - value: - away_mode_enabled: true - away_mode_reassign: true - admin_not_found: - summary: Admin not found - value: - away_mode_enabled: true - away_mode_reassign: true - unauthorized: - summary: Unauthorized - value: - away_mode_enabled: true - away_mode_reassign: true "/articles": get: summary: List all articles @@ -536,119 +536,29 @@ paths: description: Description of the Article body: Body of the Article state: published - "/articles/search": + "/articles/{article_id}": get: - summary: Search for articles + summary: Retrieve an article parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: phrase - in: query - required: false - description: The phrase within your articles to search for. - example: Getting started - schema: - type: string - - name: state - in: query - required: false - description: The state of the Articles returned. One of `published`, `draft` - or `all`. - example: published + - name: article_id + in: path + required: true + description: The unique identifier for the article which is given by Intercom. + example: "123" schema: type: string - - name: help_center_id - in: query - required: false - description: The ID of the Help Center to search in. - example: 123 - schema: - type: integer - - name: highlight - in: query - required: false - description: Return a highlighted version of the matching content within your - articles. Refer to the response schema for more details. - example: false - schema: - type: boolean tags: - Articles - operationId: searchArticles - description: You can search for articles by making a GET request to `https://api.intercom.io/articles/search`. + operationId: retrieveArticle + description: You can fetch the details of a single article by making a GET request + to `https://api.intercom.io/articles/`. responses: '200': - description: Search successful - content: - application/json: - examples: - Search successful: - value: - type: list - total_count: 1 - data: - articles: - - id: '55' - type: article - workspace_id: this_is_an_id61_that_should_be_at_least_4 - parent_id: - parent_type: - parent_ids: [] - title: Title 1 - description: '' - body: '' - author_id: 991267431 - state: draft - created_at: 1719492719 - updated_at: 1719492719 - url: - highlights: [] - pages: - type: pages - page: 1 - total_pages: 1 - per_page: 10 - schema: - "$ref": "#/components/schemas/search_articles_response" - '401': - description: Unauthorized - content: - application/json: - examples: - Unauthorized: - value: - type: error.list - request_id: 626c6766-ee1a-489d-b87a-230d9b980c7d - errors: - - code: unauthorized - message: Access Token Invalid - schema: - "$ref": "#/components/schemas/error" - "/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: string - 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/`. - responses: - '200': - description: Article found + description: Article found content: application/json: examples: @@ -860,6 +770,96 @@ paths: message: Access Token Invalid schema: "$ref": "#/components/schemas/error" + "/articles/search": + get: + summary: Search for articles + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + - name: phrase + in: query + required: false + description: The phrase within your articles to search for. + example: Getting started + schema: + type: string + - name: state + in: query + required: false + description: The state of the Articles returned. One of `published`, `draft` + or `all`. + example: published + schema: + type: string + - name: help_center_id + in: query + required: false + description: The ID of the Help Center to search in. + example: 123 + schema: + type: integer + - name: highlight + in: query + required: false + description: Return a highlighted version of the matching content within your + articles. Refer to the response schema for more details. + example: false + schema: + type: boolean + tags: + - Articles + operationId: searchArticles + description: You can search for articles by making a GET request to `https://api.intercom.io/articles/search`. + responses: + '200': + description: Search successful + content: + application/json: + examples: + Search successful: + value: + type: list + total_count: 1 + data: + articles: + - id: '55' + type: article + workspace_id: this_is_an_id61_that_should_be_at_least_4 + parent_id: + parent_type: + parent_ids: [] + title: Title 1 + description: '' + body: '' + author_id: 991267431 + state: draft + created_at: 1719492719 + updated_at: 1719492719 + url: + highlights: [] + pages: + type: pages + page: 1 + total_pages: 1 + per_page: 10 + schema: + "$ref": "#/components/schemas/search_articles_response" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: 626c6766-ee1a-489d-b87a-230d9b980c7d + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" "/help_center/collections": get: summary: List all collections @@ -1228,58 +1228,6 @@ paths: message: Access Token Invalid schema: "$ref": "#/components/schemas/error" - "/help_center/help_centers": - get: - summary: List all Help Centers - 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 15 - example: 15 - schema: - type: integer - tags: - - Help Center - operationId: listHelpCenters - description: You can list all Help Centers by making a GET request to `https://api.intercom.io/help_center/help_centers`. - responses: - '200': - description: Help Centers found - content: - application/json: - examples: - Help Centers found: - value: - type: list - data: [] - schema: - "$ref": "#/components/schemas/help_center_list" - '401': - description: Unauthorized - content: - application/json: - examples: - Unauthorized: - value: - type: error.list - request_id: c96a4779-a06d-45bb-aa39-eb96c587c2c7 - errors: - - code: unauthorized - message: Access Token Invalid - schema: - "$ref": "#/components/schemas/error" "/help_center/help_centers/{help_center_id}": get: summary: Retrieve a Help Center @@ -1345,42 +1293,94 @@ paths: message: Access Token Invalid schema: "$ref": "#/components/schemas/error" - "/companies": - post: - summary: Create or Update a company + "/help_center/help_centers": + get: + summary: List all Help Centers 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 15 + example: 15 + schema: + type: integer tags: - - Companies - operationId: createOrUpdateCompany - description: | - You can create or update a company. - - Companies will be only visible in Intercom when there is at least one associated user. - - Companies are looked up via `company_id` in a `POST` request, if not found via `company_id`, the new company will be created, if found, that company will be updated. - - {% admonition type="attention" name="Using `company_id`" %} - You can set a unique `company_id` value when creating a company. However, it is not possible to update `company_id`. Be sure to set a unique value once upon creation of the company. - {% /admonition %} + - Help Center + operationId: listHelpCenters + description: You can list all Help Centers by making a GET request to `https://api.intercom.io/help_center/help_centers`. responses: '200': - description: Successful + description: Help Centers found content: application/json: examples: - Successful: + Help Centers found: value: - type: company - company_id: company_remote_id - id: 667d607c8a68186f43bafd1e - app_id: this_is_an_id116_that_should_be_at_least_ - name: my company - remote_created_at: 1374138000 - created_at: 1719492732 + type: list + data: [] + schema: + "$ref": "#/components/schemas/help_center_list" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: c96a4779-a06d-45bb-aa39-eb96c587c2c7 + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + "/companies": + post: + summary: Create or Update a company + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + tags: + - Companies + operationId: createOrUpdateCompany + description: | + You can create or update a company. + + Companies will be only visible in Intercom when there is at least one associated user. + + Companies are looked up via `company_id` in a `POST` request, if not found via `company_id`, the new company will be created, if found, that company will be updated. + + {% admonition type="attention" name="Using `company_id`" %} + You can set a unique `company_id` value when creating a company. However, it is not possible to update `company_id`. Be sure to set a unique value once upon creation of the company. + {% /admonition %} + responses: + '200': + description: Successful + content: + application/json: + examples: + Successful: + value: + type: company + company_id: company_remote_id + id: 667d607c8a68186f43bafd1e + app_id: this_is_an_id116_that_should_be_at_least_ + name: my company + remote_created_at: 1374138000 + created_at: 1719492732 updated_at: 1719492732 monthly_spend: 0 session_count: 0 @@ -2100,10 +2100,131 @@ paths: message: Access Token Invalid schema: "$ref": "#/components/schemas/error" - "/contacts": + "/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: 667d608d8a68186f43bafd70 + app_id: this_is_an_id166_that_should_be_at_least_ + name: company6 + remote_created_at: 1719492749 + created_at: 1719492749 + updated_at: 1719492749 + 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: 9297dcfc-1896-43a3-a3f9-131238422ed2 + errors: + - code: parameter_not_found + message: company not specified + schema: + "$ref": "#/components/schemas/error" + '404': + description: Company Not Found + content: + application/json: + examples: + Company Not Found: + value: + type: error.list + request_id: 32d121d8-fcbf-4c59-9c60-204f7d602f36 + 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: 99739bbd-2dbe-4ce3-ae91-af23379b5cd7 + 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: 667d608d8a68186f43bafd70 + bad_request: + summary: Bad Request + value: + company_not_found: + summary: Company Not Found + value: + id: '123' get: - summary: List all contacts + 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: @@ -2122,21 +2243,11 @@ paths: example: 15 schema: type: integer - - name: starting_after - in: query - required: false - description: String used to get the next page of conversations. - schema: - type: string tags: - Contacts - operationId: ListContacts - description: | - You can fetch a list of all contacts (ie. users or leads) in your workspace. - {% admonition type="warning" name="Pagination" %} - You can use 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/#pagination-for-list-apis) for more details on how to use the `starting_after` param. - {% /admonition %} + - Companies + operationId: listCompaniesForAContact + description: You can fetch a list of companies that are associated to a contact. responses: '200': description: successful @@ -2146,15 +2257,50 @@ paths: successful: value: type: list - data: [] - total_count: 0 + data: + - type: company + company_id: '1' + id: 667d60938a68186f43bafd91 + app_id: this_is_an_id182_that_should_be_at_least_ + name: company12 + remote_created_at: 1719492755 + created_at: 1719492755 + updated_at: 1719492755 + last_request_at: 1719319955 + 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: 10 - total_pages: 0 + per_page: 50 + total_pages: 1 + total_count: 1 schema: - "$ref": "#/components/schemas/contact_list" + "$ref": "#/components/schemas/contact_attached_companies" + '404': + description: Contact not found + content: + application/json: + examples: + Contact not found: + value: + type: error.list + request_id: b9d7374d-1780-4668-bb62-0e1ff9cdab45 + errors: + - code: not_found + message: User Not Found + schema: + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -2163,118 +2309,89 @@ paths: Unauthorized: value: type: error.list - request_id: d5bac7ff-7961-4fe5-8aed-6f1b031b38af + request_id: d211ec8c-df9b-420c-86df-23c27ad54bc5 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" - post: - summary: Create contact + "/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" - tags: - - Contacts - operationId: CreateContact - description: You can create a new contact (ie. user or lead). - responses: - '200': - description: successful - content: - application/json: + - 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: + Successful: value: - type: contact - id: 667d60b08a68186f43bafdbf - workspace_id: this_is_an_id272_that_should_be_at_least_ - external_id: - role: user - email: joebloggs@intercom.io - phone: - name: - avatar: - owner_id: - social_profiles: - type: list - data: [] - has_hard_bounced: false - marked_email_as_spam: false - unsubscribed_from_emails: false - created_at: 1719492784 - updated_at: 1719492784 - signed_up_at: - 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: {} + type: company + company_id: '1' + id: 667d60918a68186f43bafd80 + app_id: this_is_an_id174_that_should_be_at_least_ + name: company8 + remote_created_at: 1719492753 + created_at: 1719492753 + updated_at: 1719492753 + monthly_spend: 0 + session_count: 0 + user_count: 0 tags: - type: list - data: [] - url: "/contacts/667d60b08a68186f43bafdbf/tags" - total_count: 0 - has_more: false - notes: - type: list - data: [] - url: "/contacts/667d60b08a68186f43bafdbf/notes" - total_count: 0 - has_more: false - companies: - type: list - data: [] - url: "/contacts/667d60b08a68186f43bafdbf/companies" - total_count: 0 - has_more: false - opted_out_subscription_types: - type: list - data: [] - url: "/contacts/667d60b08a68186f43bafdbf/subscriptions" - total_count: 0 - has_more: false - opted_in_subscription_types: - type: list - data: [] - url: "/contacts/667d60b08a68186f43bafdbf/subscriptions" - total_count: 0 - has_more: false - utm_campaign: - utm_content: - utm_medium: - utm_source: - utm_term: - referrer: + type: tag.list + tags: [] + segments: + type: segment.list + segments: [] + plan: {} + custom_attributes: {} schema: - "$ref": "#/components/schemas/contact" + "$ref": "#/components/schemas/company" + '404': + description: Contact Not Found + content: + application/json: + examples: + Company Not Found: + value: + type: error.list + request_id: cd4f1648-724c-45f0-b6e1-72a1bc6479ee + errors: + - code: company_not_found + message: Company Not Found + Contact Not Found: + value: + type: error.list + request_id: d316defc-0a2f-49e7-b8ff-4cb6ccf46c90 + errors: + - code: not_found + message: User Not Found + schema: + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -2283,165 +2400,122 @@ paths: Unauthorized: value: type: error.list - request_id: c18ca0d4-ad2c-41e7-9a71-1df806f9c954 + request_id: d8c1ab2d-4044-4c4f-98f0-176860747112 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" - requestBody: - content: - application/json: - schema: - oneOf: - - "$ref": "#/components/schemas/create_contact_request" - examples: - successful: - summary: successful - value: - email: joebloggs@intercom.io - "/contacts/{contact_id}": - put: - summary: Update a contact + "/contacts/{contact_id}/notes": + get: + summary: List all notes parameters: - - name: Intercom-Version - in: header - schema: - "$ref": "#/components/schemas/intercom_version" - name: contact_id in: path - description: id - example: 63a07ddf05a32042dffac965 required: true + description: The unique identifier of a contact. schema: type: string + - 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 15 + example: 15 + schema: + type: integer tags: + - Notes - Contacts - operationId: UpdateContact - description: You can update an existing contact (ie. user or lead). + operationId: listNotes + description: You can fetch a list of notes that are associated to a contact. responses: '200': - description: successful + description: Successful response content: application/json: examples: - successful: + Successful response: value: - type: contact - id: 667d60a88a68186f43bafdb8 - workspace_id: this_is_an_id248_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: 1719492776 - updated_at: 1719492776 - signed_up_at: 1719492776 - 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/667d60a88a68186f43bafdb8/tags" - total_count: 0 - has_more: false - notes: - type: list - data: [] - url: "/contacts/667d60a88a68186f43bafdb8/notes" - total_count: 0 - has_more: false - companies: - type: list - data: [] - url: "/contacts/667d60a88a68186f43bafdb8/companies" - total_count: 0 - has_more: false - opted_out_subscription_types: - type: list - data: [] - url: "/contacts/667d60a88a68186f43bafdb8/subscriptions" - total_count: 0 - has_more: false - opted_in_subscription_types: - type: list - data: [] - url: "/contacts/667d60a88a68186f43bafdb8/subscriptions" - total_count: 0 - has_more: false - utm_campaign: - utm_content: - utm_medium: - utm_source: - utm_term: - referrer: + type: list + data: + - type: note + id: '29' + created_at: 1718887958 + contact: + type: contact + id: 667d60968a68186f43bafd9c + author: + type: admin + id: '991267491' + name: Ciaran101 Lee + email: admin101@email.com + away_mode_enabled: false + away_mode_reassign: false + body: "

This is a note.

" + - type: note + id: '28' + created_at: 1718801558 + contact: + type: contact + id: 667d60968a68186f43bafd9c + author: + type: admin + id: '991267491' + name: Ciaran101 Lee + email: admin101@email.com + away_mode_enabled: false + away_mode_reassign: false + body: "

This is a note.

" + - type: note + id: '27' + created_at: 1718801558 + contact: + type: contact + id: 667d60968a68186f43bafd9c + author: + type: admin + id: '991267491' + name: Ciaran101 Lee + email: admin101@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/contact" - '401': - description: Unauthorized + "$ref": "#/components/schemas/note_list" + '404': + description: Contact not found content: application/json: - examples: - Unauthorized: - value: - type: error.list - request_id: b1b88e2d-938c-4a26-b65d-26ff65a0af36 - 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 - get: - summary: Get a contact + examples: + Contact not found: + value: + type: error.list + request_id: e93f90a6-4c85-4dbf-b063-96b649318371 + errors: + - code: not_found + message: User Not Found + schema: + "$ref": "#/components/schemas/error" + post: + summary: Create a note parameters: - name: Intercom-Version in: header @@ -2449,141 +2523,116 @@ paths: "$ref": "#/components/schemas/intercom_version" - name: contact_id in: path - description: id - example: 63a07ddf05a32042dffac965 required: true + description: The unique identifier of a given contact. + example: "123" schema: type: string tags: + - Notes - Contacts - operationId: ShowContact - description: You can fetch the details of a single contact. + operationId: createNote + description: You can add a note to a single contact. responses: '200': - description: successful + description: Successful response content: application/json: examples: - successful: + Successful response: value: - type: contact - id: 667d60a98a68186f43bafdb9 - workspace_id: this_is_an_id252_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: 1719492777 - updated_at: 1719492777 - signed_up_at: 1719492777 - 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/667d60a98a68186f43bafdb9/tags" - total_count: 0 - has_more: false - notes: - type: list - data: [] - url: "/contacts/667d60a98a68186f43bafdb9/notes" - total_count: 0 - has_more: false - companies: - type: list - data: [] - url: "/contacts/667d60a98a68186f43bafdb9/companies" - total_count: 0 - has_more: false - opted_out_subscription_types: - type: list - data: [] - url: "/contacts/667d60a98a68186f43bafdb9/subscriptions" - total_count: 0 - has_more: false - opted_in_subscription_types: - type: list - data: [] - url: "/contacts/667d60a98a68186f43bafdb9/subscriptions" - total_count: 0 - has_more: false - utm_campaign: - utm_content: - utm_medium: - utm_source: - utm_term: - referrer: + type: note + id: '34' + created_at: 1719492759 + contact: + type: contact + id: 667d60978a68186f43bafd9e + author: + type: admin + id: '991267493' + name: Ciaran103 Lee + email: admin103@email.com + away_mode_enabled: false + away_mode_reassign: false + body: "

Hello

" schema: - "$ref": "#/components/schemas/contact" - '401': - description: Unauthorized + "$ref": "#/components/schemas/note" + '404': + description: Contact not found content: application/json: examples: - Unauthorized: + Admin not found: value: type: error.list - request_id: f70085f1-f655-43ee-9585-d2061b260fcd + request_id: d7c69ce6-3195-46be-b2cb-0dce355d2919 errors: - - code: unauthorized - message: Access Token Invalid + - code: not_found + message: Resource Not Found + Contact not found: + value: + type: error.list + request_id: 2e3bd274-9ac6-43c3-a419-bcc8e6a03a1d + errors: + - code: not_found + message: User Not Found schema: "$ref": "#/components/schemas/error" - delete: - summary: Delete a contact + 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: 667d60978a68186f43bafd9e + admin_id: 991267493 + body: Hello + admin_not_found: + summary: Admin not found + value: + contact_id: 667d60988a68186f43bafd9f + admin_id: 123 + body: Hello + contact_not_found: + summary: Contact not found + value: + contact_id: 123 + admin_id: 991267495 + body: Hello + "/contacts/{contact_id}/segments": + get: + summary: List attached segments for contact parameters: - - name: Intercom-Version - in: header - schema: - "$ref": "#/components/schemas/intercom_version" - name: contact_id in: path - description: id + 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 - operationId: DeleteContact - description: You can delete a single contact. + - Segments + operationId: listSegmentsForAContact + description: You can fetch a list of segments that are associated to a contact. responses: '200': description: successful @@ -2592,12 +2641,30 @@ paths: examples: successful: value: - id: 667d60aa8a68186f43bafdba - external_id: '70' - type: contact - deleted: true + type: list + data: + - type: segment + id: 667d60998a68186f43bafda1 + name: segment + created_at: 1719492761 + updated_at: 1719492761 + person_type: user schema: - "$ref": "#/components/schemas/contact_deleted" + "$ref": "#/components/schemas/contact_segments" + '404': + description: Contact not found + content: + application/json: + examples: + Contact not found: + value: + type: error.list + request_id: 7d4ab1a9-5990-4338-b5d9-0f3f55f1acb7 + errors: + - code: not_found + message: User Not Found + schema: + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -2606,85 +2673,79 @@ paths: Unauthorized: value: type: error.list - request_id: 0bce3945-d2ec-4b8e-a790-b16fd52d9f11 + request_id: d2927c64-9c5a-4593-997b-381f8c2356ea errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" - "/contacts/{contact_id}/companies": + "/contacts/{contact_id}/subscriptions": get: - summary: List attached companies for contact + 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" - - 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 15 - example: 15 + description: The unique identifier for the contact which is given by Intercom + example: 63a07ddf05a32042dffac965 + required: true schema: - type: integer + 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. + - 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 + description: Successful content: application/json: examples: - successful: + Successful: value: type: list data: - - type: company - company_id: '1' - id: 667d60938a68186f43bafd91 - app_id: this_is_an_id182_that_should_be_at_least_ - name: company12 - remote_created_at: 1719492755 - created_at: 1719492755 - updated_at: 1719492755 - last_request_at: 1719319955 - 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 + - type: subscription + id: '93' + 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: '95' + 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/contact_attached_companies" + "$ref": "#/components/schemas/subscription_type_list" '404': description: Contact not found content: @@ -2693,7 +2754,7 @@ paths: Contact not found: value: type: error.list - request_id: b9d7374d-1780-4668-bb62-0e1ff9cdab45 + request_id: 3f481052-cf49-4b95-a492-734223865981 errors: - code: not_found message: User Not Found @@ -2707,14 +2768,17 @@ paths: Unauthorized: value: type: error.list - request_id: d211ec8c-df9b-420c-86df-23c27ad54bc5 + request_id: 82a95655-569d-4e5d-b0d9-f8a6c7a379f3 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" post: - summary: Attach a Contact to a Company + summary: Add subscription to a contact + tags: + - Subscription Types + - Contacts parameters: - name: Intercom-Version in: header @@ -2722,15 +2786,20 @@ paths: "$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: 63a07ddf05a32042dffac965 + required: true schema: type: string - tags: - - Companies - - Contacts - operationId: attachContactToACompany - description: You can attach a company to a single contact. + 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 @@ -2739,53 +2808,41 @@ paths: examples: Successful: value: - type: company - company_id: '1' - id: 667d608d8a68186f43bafd70 - app_id: this_is_an_id166_that_should_be_at_least_ - name: company6 - remote_created_at: 1719492749 - created_at: 1719492749 - updated_at: 1719492749 - monthly_spend: 0 - session_count: 0 - user_count: 1 - tags: - type: tag.list - tags: [] - segments: - type: segment.list - segments: [] - plan: {} - custom_attributes: {} + type: subscription + id: '108' + 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/company" - '400': - description: Bad Request + "$ref": "#/components/schemas/subscription_type" + '404': + description: Resource not found content: application/json: examples: - Bad Request: + Contact not found: value: type: error.list - request_id: 9297dcfc-1896-43a3-a3f9-131238422ed2 + request_id: cf0f6fd6-7c5e-492b-909d-f60b35eea1c4 errors: - - code: parameter_not_found - message: company not specified - schema: - "$ref": "#/components/schemas/error" - '404': - description: Company Not Found - content: - application/json: - examples: - Company Not Found: + - code: not_found + message: User Not Found + Resource not found: value: type: error.list - request_id: 32d121d8-fcbf-4c59-9c60-204f7d602f36 + request_id: 3f852f45-1a80-4ade-9bc6-72b377d2bbd8 errors: - - code: company_not_found - message: Company Not Found + - code: not_found + message: Resource Not Found schema: "$ref": "#/components/schemas/error" '401': @@ -2796,7 +2853,7 @@ paths: Unauthorized: value: type: error.list - request_id: 99739bbd-2dbe-4ce3-ae91-af23379b5cd7 + request_id: 377d162e-82a5-4148-a26f-29c9c760dadc errors: - code: unauthorized message: Access Token Invalid @@ -2809,27 +2866,39 @@ paths: type: object required: - id + - consent_type properties: id: type: string - description: The unique identifier for the company which is given - by Intercom - example: 58a430d35458202d41b1e65b + 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: 667d608d8a68186f43bafd70 - bad_request: - summary: Bad Request + id: 108 + consent_type: opt_in + contact_not_found: + summary: Contact not found value: - company_not_found: - summary: Company Not Found + id: 112 + consent_type: opt_in + resource_not_found: + summary: Resource not found value: - id: '123' - "/contacts/{contact_id}/companies/{company_id}": + id: invalid_id + consent_type: opt_in + "/contacts/{contact_id}/subscriptions/{subscription_id}": delete: - summary: Detach a contact from a company + summary: Remove subscription from a contact + tags: + - Subscription Types + - Contacts parameters: - name: Intercom-Version in: header @@ -2837,23 +2906,23 @@ paths: "$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 + example: 63a07ddf05a32042dffac965 + required: true schema: type: string - - name: company_id + - name: subscription_id in: path + description: The unique identifier for the subscription type which is given + by Intercom + example: '37846' 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. + 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 @@ -2862,46 +2931,41 @@ paths: examples: Successful: value: - type: company - company_id: '1' - id: 667d60918a68186f43bafd80 - app_id: this_is_an_id174_that_should_be_at_least_ - name: company8 - remote_created_at: 1719492753 - created_at: 1719492753 - updated_at: 1719492753 - monthly_spend: 0 - session_count: 0 - user_count: 0 - tags: - type: tag.list - tags: [] - segments: - type: segment.list - segments: [] - plan: {} - custom_attributes: {} + type: subscription + id: '124' + 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/company" + "$ref": "#/components/schemas/subscription_type" '404': - description: Contact Not Found + description: Resource not found content: application/json: examples: - Company Not Found: + Contact not found: value: type: error.list - request_id: cd4f1648-724c-45f0-b6e1-72a1bc6479ee + request_id: 7bc429e4-e887-4f53-b69c-94e6e55d2125 errors: - - code: company_not_found - message: Company Not Found - Contact Not Found: + - code: not_found + message: User Not Found + Resource not found: value: type: error.list - request_id: d316defc-0a2f-49e7-b8ff-4cb6ccf46c90 + request_id: 66ebc1f5-5e02-4584-8028-f2559a41e8df errors: - code: not_found - message: User Not Found + message: Resource Not Found schema: "$ref": "#/components/schemas/error" '401': @@ -2912,106 +2976,48 @@ paths: Unauthorized: value: type: error.list - request_id: d8c1ab2d-4044-4c4f-98f0-176860747112 + request_id: 99fba0c6-2252-4658-abd2-1d2ff16a508b errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" - "/contacts/{contact_id}/notes": + "/contacts/{contact_id}/tags": get: - summary: List all notes + summary: List tags attached to a contact + tags: + - Contacts + - Tags 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" - - 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 15 - example: 15 + - name: contact_id + in: path + description: The unique identifier for the contact which is given by Intercom + example: 63a07ddf05a32042dffac965 + required: true schema: - type: integer - tags: - - Notes - - Contacts - operationId: listNotes - description: You can fetch a list of notes that are associated to a contact. + type: string + operationId: listTagsForAContact + description: You can fetch a list of all tags that are attached to a specific + contact. responses: '200': - description: Successful response + description: successful content: application/json: examples: - Successful response: + successful: value: type: list data: - - type: note - id: '29' - created_at: 1718887958 - contact: - type: contact - id: 667d60968a68186f43bafd9c - author: - type: admin - id: '991267491' - name: Ciaran101 Lee - email: admin101@email.com - away_mode_enabled: false - away_mode_reassign: false - body: "

This is a note.

" - - type: note - id: '28' - created_at: 1718801558 - contact: - type: contact - id: 667d60968a68186f43bafd9c - author: - type: admin - id: '991267491' - name: Ciaran101 Lee - email: admin101@email.com - away_mode_enabled: false - away_mode_reassign: false - body: "

This is a note.

" - - type: note - id: '27' - created_at: 1718801558 - contact: - type: contact - id: 667d60968a68186f43bafd9c - author: - type: admin - id: '991267491' - name: Ciaran101 Lee - email: admin101@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 + - type: tag + id: '93' + name: Manual tag schema: - "$ref": "#/components/schemas/note_list" + "$ref": "#/components/schemas/tag_list" '404': description: Contact not found content: @@ -3020,115 +3026,36 @@ paths: Contact not found: value: type: error.list - request_id: e93f90a6-4c85-4dbf-b063-96b649318371 + request_id: 2b513026-b78c-4c67-b073-da0266f62cc7 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: string - 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: '34' - created_at: 1719492759 - contact: - type: contact - id: 667d60978a68186f43bafd9e - author: - type: admin - id: '991267493' - name: Ciaran103 Lee - email: admin103@email.com - away_mode_enabled: false - away_mode_reassign: false - body: "

Hello

" - schema: - "$ref": "#/components/schemas/note" - '404': - description: Contact not found + '401': + description: Unauthorized content: application/json: examples: - Admin not found: - value: - type: error.list - request_id: d7c69ce6-3195-46be-b2cb-0dce355d2919 - errors: - - code: not_found - message: Resource Not Found - Contact not found: + Unauthorized: value: type: error.list - request_id: 2e3bd274-9ac6-43c3-a419-bcc8e6a03a1d + request_id: 97383559-0fb0-4084-8a9a-8e3407c46108 errors: - - code: not_found - message: User Not Found + - code: unauthorized + message: Access Token Invalid 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: 667d60978a68186f43bafd9e - admin_id: 991267493 - body: Hello - admin_not_found: - summary: Admin not found - value: - contact_id: 667d60988a68186f43bafd9f - admin_id: 123 - body: Hello - contact_not_found: - summary: Contact not found - value: - contact_id: 123 - admin_id: 991267495 - body: Hello - "/contacts/{contact_id}/segments": - get: - summary: List attached segments for contact + 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 @@ -3136,15 +3063,9 @@ paths: 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. + 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 @@ -3153,28 +3074,30 @@ paths: examples: successful: value: - type: list - data: - - type: segment - id: 667d60998a68186f43bafda1 - name: segment - created_at: 1719492761 - updated_at: 1719492761 - person_type: user + type: tag + id: '94' + name: Manual tag schema: - "$ref": "#/components/schemas/contact_segments" + "$ref": "#/components/schemas/tag" '404': - description: Contact not found + description: Tag not found content: application/json: examples: Contact not found: value: type: error.list - request_id: 7d4ab1a9-5990-4338-b5d9-0f3f55f1acb7 + request_id: 1bbd7e4b-718e-46f4-b682-a429aea78f01 errors: - code: not_found message: User Not Found + Tag not found: + value: + type: error.list + request_id: a1a28017-728a-423b-adc0-2705d375f533 + errors: + - code: not_found + message: Resource Not Found schema: "$ref": "#/components/schemas/error" '401': @@ -3185,16 +3108,49 @@ paths: Unauthorized: value: type: error.list - request_id: d2927c64-9c5a-4593-997b-381f8c2356ea + request_id: 63a2828f-107e-4d51-9398-a220b81a7bce errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" - "/contacts/{contact_id}/subscriptions": - get: - summary: List subscriptions for a contact + 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: 94 + contact_not_found: + summary: Contact not found + value: + id: 95 + 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 @@ -3202,74 +3158,48 @@ paths: required: true schema: type: string - - name: Intercom-Version - in: header + - name: tag_id + in: path + description: The unique identifier for the tag which is given by Intercom + example: '7522907' + required: true 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. + 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 + description: successful content: application/json: examples: - Successful: + successful: value: - type: list - data: - - type: subscription - id: '93' - 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: '95' - 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 + type: tag + id: '97' + name: Manual tag schema: - "$ref": "#/components/schemas/subscription_type_list" + "$ref": "#/components/schemas/tag" '404': - description: Contact not found + description: Tag not found content: application/json: examples: Contact not found: value: type: error.list - request_id: 3f481052-cf49-4b95-a492-734223865981 + request_id: 6f735483-c309-4e94-b9ab-143aedc0c691 errors: - code: not_found message: User Not Found + Tag not found: + value: + type: error.list + request_id: 9e780671-29b3-4913-b4be-15234ea0bc6a + errors: + - code: not_found + message: Resource Not Found schema: "$ref": "#/components/schemas/error" '401': @@ -3280,17 +3210,15 @@ paths: Unauthorized: value: type: error.list - request_id: 82a95655-569d-4e5d-b0d9-f8a6c7a379f3 + request_id: e97d9f1b-8c9e-4caf-b473-3bce411c697e errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" - post: - summary: Add subscription to a contact - tags: - - Subscription Types - - Contacts + "/contacts/{contact_id}": + put: + summary: Update a contact parameters: - name: Intercom-Version in: header @@ -3298,65 +3226,110 @@ paths: "$ref": "#/components/schemas/intercom_version" - name: contact_id in: path - description: The unique identifier for the contact which is given by Intercom + description: id 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. + tags: + - Contacts + operationId: UpdateContact + description: You can update an existing contact (ie. user or lead). responses: '200': - description: Successful - content: - application/json: - examples: - Successful: - value: - type: subscription - id: '108' - 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 + description: successful content: application/json: examples: - Contact not found: - value: - type: error.list - request_id: cf0f6fd6-7c5e-492b-909d-f60b35eea1c4 - errors: - - code: not_found - message: User Not Found - Resource not found: + successful: value: - type: error.list - request_id: 3f852f45-1a80-4ade-9bc6-72b377d2bbd8 - errors: - - code: not_found - message: Resource Not Found + type: contact + id: 667d60a88a68186f43bafdb8 + workspace_id: this_is_an_id248_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: 1719492776 + updated_at: 1719492776 + signed_up_at: 1719492776 + 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/667d60a88a68186f43bafdb8/tags" + total_count: 0 + has_more: false + notes: + type: list + data: [] + url: "/contacts/667d60a88a68186f43bafdb8/notes" + total_count: 0 + has_more: false + companies: + type: list + data: [] + url: "/contacts/667d60a88a68186f43bafdb8/companies" + total_count: 0 + has_more: false + opted_out_subscription_types: + type: list + data: [] + url: "/contacts/667d60a88a68186f43bafdb8/subscriptions" + total_count: 0 + has_more: false + opted_in_subscription_types: + type: list + data: [] + url: "/contacts/667d60a88a68186f43bafdb8/subscriptions" + total_count: 0 + has_more: false + utm_campaign: + utm_content: + utm_medium: + utm_source: + utm_term: + referrer: schema: - "$ref": "#/components/schemas/error" + "$ref": "#/components/schemas/contact" '401': description: Unauthorized content: @@ -3365,7 +3338,7 @@ paths: Unauthorized: value: type: error.list - request_id: 377d162e-82a5-4148-a26f-29c9c760dadc + request_id: b1b88e2d-938c-4a26-b65d-26ff65a0af36 errors: - code: unauthorized message: Access Token Invalid @@ -3375,42 +3348,16 @@ paths: 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 + oneOf: + - "$ref": "#/components/schemas/update_contact_request" examples: successful: - summary: Successful - value: - id: 108 - consent_type: opt_in - contact_not_found: - summary: Contact not found - value: - id: 112 - consent_type: opt_in - resource_not_found: - summary: Resource not found + summary: successful 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 + email: joebloggs@intercom.io + name: joe bloggs + get: + summary: Get a contact parameters: - name: Intercom-Version in: header @@ -3418,68 +3365,110 @@ paths: "$ref": "#/components/schemas/intercom_version" - name: contact_id in: path - description: The unique identifier for the contact which is given by Intercom + description: id 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. + 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: subscription - id: '124' - 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 + description: successful content: application/json: examples: - Contact not found: - value: - type: error.list - request_id: 7bc429e4-e887-4f53-b69c-94e6e55d2125 - errors: - - code: not_found - message: User Not Found - Resource not found: + successful: value: - type: error.list - request_id: 66ebc1f5-5e02-4584-8028-f2559a41e8df - errors: - - code: not_found - message: Resource Not Found + type: contact + id: 667d60a98a68186f43bafdb9 + workspace_id: this_is_an_id252_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: 1719492777 + updated_at: 1719492777 + signed_up_at: 1719492777 + 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/667d60a98a68186f43bafdb9/tags" + total_count: 0 + has_more: false + notes: + type: list + data: [] + url: "/contacts/667d60a98a68186f43bafdb9/notes" + total_count: 0 + has_more: false + companies: + type: list + data: [] + url: "/contacts/667d60a98a68186f43bafdb9/companies" + total_count: 0 + has_more: false + opted_out_subscription_types: + type: list + data: [] + url: "/contacts/667d60a98a68186f43bafdb9/subscriptions" + total_count: 0 + has_more: false + opted_in_subscription_types: + type: list + data: [] + url: "/contacts/667d60a98a68186f43bafdb9/subscriptions" + total_count: 0 + has_more: false + utm_campaign: + utm_content: + utm_medium: + utm_source: + utm_term: + referrer: schema: - "$ref": "#/components/schemas/error" + "$ref": "#/components/schemas/contact" '401': description: Unauthorized content: @@ -3488,18 +3477,14 @@ paths: Unauthorized: value: type: error.list - request_id: 99fba0c6-2252-4658-abd2-1d2ff16a508b + request_id: f70085f1-f655-43ee-9585-d2061b260fcd 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 + delete: + summary: Delete a contact parameters: - name: Intercom-Version in: header @@ -3507,14 +3492,14 @@ paths: "$ref": "#/components/schemas/intercom_version" - name: contact_id in: path - description: The unique identifier for the contact which is given by Intercom - example: 63a07ddf05a32042dffac965 + description: id required: true schema: type: string - operationId: listTagsForAContact - description: You can fetch a list of all tags that are attached to a specific - contact. + tags: + - Contacts + operationId: DeleteContact + description: You can delete a single contact. responses: '200': description: successful @@ -3523,27 +3508,12 @@ paths: examples: successful: value: - type: list - data: - - type: tag - id: '93' - name: Manual tag - schema: - "$ref": "#/components/schemas/tag_list" - '404': - description: Contact not found - content: - application/json: - examples: - Contact not found: - value: - type: error.list - request_id: 2b513026-b78c-4c67-b073-da0266f62cc7 - errors: - - code: not_found - message: User Not Found + id: 667d60aa8a68186f43bafdba + external_id: '70' + type: contact + deleted: true schema: - "$ref": "#/components/schemas/error" + "$ref": "#/components/schemas/contact_deleted" '401': description: Unauthorized content: @@ -3552,32 +3522,25 @@ paths: Unauthorized: value: type: error.list - request_id: 97383559-0fb0-4084-8a9a-8e3407c46108 + request_id: 0bce3945-d2ec-4b8e-a790-b16fd52d9f11 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" + "/contacts/merge": post: - summary: Add tag to a contact - tags: - - Tags - - Contacts + summary: Merge a lead and a user 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. + 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 @@ -3586,32 +3549,93 @@ paths: examples: successful: value: - type: tag - id: '94' - name: Manual tag - schema: - "$ref": "#/components/schemas/tag" - '404': - description: Tag not found - content: - application/json: - examples: - Contact not found: - value: - type: error.list - request_id: 1bbd7e4b-718e-46f4-b682-a429aea78f01 - errors: - - code: not_found - message: User Not Found - Tag not found: - value: - type: error.list - request_id: a1a28017-728a-423b-adc0-2705d375f533 - errors: - - code: not_found - message: Resource Not Found + type: contact + id: 667d60ac8a68186f43bafdbc + workspace_id: this_is_an_id260_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: 1719492780 + updated_at: 1719492780 + signed_up_at: 1719492780 + 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/667d60ac8a68186f43bafdbc/tags" + total_count: 0 + has_more: false + notes: + type: list + data: [] + url: "/contacts/667d60ac8a68186f43bafdbc/notes" + total_count: 0 + has_more: false + companies: + type: list + data: [] + url: "/contacts/667d60ac8a68186f43bafdbc/companies" + total_count: 0 + has_more: false + opted_out_subscription_types: + type: list + data: [] + url: "/contacts/667d60ac8a68186f43bafdbc/subscriptions" + total_count: 0 + has_more: false + opted_in_subscription_types: + type: list + data: [] + url: "/contacts/667d60ac8a68186f43bafdbc/subscriptions" + total_count: 0 + has_more: false + utm_campaign: + utm_content: + utm_medium: + utm_source: + utm_term: + referrer: schema: - "$ref": "#/components/schemas/error" + "$ref": "#/components/schemas/contact" '401': description: Unauthorized content: @@ -3620,7 +3644,7 @@ paths: Unauthorized: value: type: error.list - request_id: 63a2828f-107e-4d51-9398-a220b81a7bce + request_id: 57b64228-0e60-4e35-833d-39c4e4067dde errors: - code: unauthorized message: Access Token Invalid @@ -3630,56 +3654,125 @@ paths: 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' + "$ref": "#/components/schemas/merge_contacts_request" examples: successful: summary: successful value: - id: 94 - contact_not_found: - summary: Contact not found - value: - id: 95 - 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 + from: 667d60ac8a68186f43bafdbb + into: 667d60ac8a68186f43bafdbc + "/contacts/search": + post: + summary: Search 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. + 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 | String
Accepts user or lead | + | name | String | + | avatar | String | + | owner_id | Integer | + | email | String | + | email_domain | String | + | phone | String | + | formatted_phone | String | + | external_id | String | + | created_at | Date (UNIX Timestamp) | + | signed_up_at | Date (UNIX Timestamp) | + | updated_at | Date (UNIX Timestamp) | + | last_seen_at | Date (UNIX Timestamp) | + | last_contacted_at | Date (UNIX Timestamp) | + | last_replied_at | Date (UNIX Timestamp) | + | last_email_opened_at | Date (UNIX Timestamp) | + | last_email_clicked_at | Date (UNIX Timestamp) | + | language_override | String | + | browser | String | + | browser_language | String | + | os | String | + | location.country | String | + | location.region | String | + | location.city | String | + | unsubscribed_from_emails | Boolean | + | marked_email_as_spam | Boolean | + | has_hard_bounced | Boolean | + | ios_last_seen_at | Date (UNIX Timestamp) | + | ios_app_version | String | + | ios_device | String | + | ios_app_device | String | + | ios_os_version | String | + | ios_app_name | String | + | ios_sdk_version | String | + | android_last_seen_at | Date (UNIX Timestamp) | + | android_app_version | String | + | android_device | String | + | android_app_name | String | + | andoid_sdk_version | String | + | segment_id | String | + | tag_id | String | + | custom_attributes.{attribute_name} | String | + + ### Accepted Operators + + {% admonition type="attention" name="Searching based on `created_at`" %} + You cannot use the `<=` or `>=` operators to search by `created_at`. + {% /admonition %} + + The table below shows the operators you can use to define how you want to search for the value. The operator should be put in as a string (`"="`). The operator has to be compatible with the field's type (eg. you cannot search with `>` for a given string value as it's only compatible for integer's and dates). + + | Operator | Valid Types | Description | + | :------- | :------------------------------- | :--------------------------------------------------------------- | + | = | All | Equals | + | != | All | Doesn't Equal | + | IN | All | In
Shortcut for `OR` queries
Values must be in Array | + | NIN | All | Not In
Shortcut for `OR !` queries
Values must be in Array | + | > | Integer
Date (UNIX Timestamp) | Greater than | + | < | Integer
Date (UNIX Timestamp) | Lower than | + | ~ | String | Contains | + | !~ | String | Doesn't Contain | + | ^ | String | Starts With | + | $ | String | Ends With | responses: '200': description: successful @@ -3688,32 +3781,16 @@ paths: examples: successful: value: - type: tag - id: '97' - name: Manual tag - schema: - "$ref": "#/components/schemas/tag" - '404': - description: Tag not found - content: - application/json: - examples: - Contact not found: - value: - type: error.list - request_id: 6f735483-c309-4e94-b9ab-143aedc0c691 - errors: - - code: not_found - message: User Not Found - Tag not found: - value: - type: error.list - request_id: 9e780671-29b3-4913-b4be-15234ea0bc6a - errors: - - code: not_found - message: Resource Not Found + type: list + data: [] + total_count: 0 + pages: + type: pages + page: 1 + per_page: 5 + total_pages: 0 schema: - "$ref": "#/components/schemas/error" + "$ref": "#/components/schemas/contact_list" '401': description: Unauthorized content: @@ -3722,31 +3799,66 @@ paths: Unauthorized: value: type: error.list - request_id: e97d9f1b-8c9e-4caf-b473-3bce411c697e + request_id: 2b28c47b-8fa3-4e17-8fc1-6ba80f1cc844 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" - "/contacts/{contact_id}/archive": - post: - summary: Archive contact + 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 + "/contacts": + get: + summary: List all contacts parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: contact_id - in: path - description: id - example: 63a07ddf05a32042dffac965 - required: true + - 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 15 + example: 15 + schema: + type: integer + - name: starting_after + in: query + required: false + description: String used to get the next page of conversations. schema: type: string tags: - Contacts - operationId: ArchiveContact - description: You can archive a single contact. + operationId: ListContacts + description: | + You can fetch a list of all contacts (ie. users or leads) in your workspace. + {% admonition type="warning" name="Pagination" %} + You can use 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/#pagination-for-list-apis) for more details on how to use the `starting_after` param. + {% /admonition %} responses: '200': description: successful @@ -3755,48 +3867,32 @@ paths: examples: successful: value: - id: 667d60b18a68186f43bafdc0 - external_id: '70' - type: contact - archived: true + type: list + data: [] + total_count: 0 + pages: + type: pages + page: 1 + per_page: 10 + total_pages: 0 schema: - "$ref": "#/components/schemas/contact_archived" - "/contacts/{contact_id}/unarchive": - post: - summary: Unarchive 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 - operationId: UnarchiveContact - description: You can unarchive a single contact. - responses: - '200': - description: successful + "$ref": "#/components/schemas/contact_list" + '401': + description: Unauthorized content: application/json: examples: - successful: + Unauthorized: value: - id: 667d60b28a68186f43bafdc1 - external_id: '70' - type: contact - archived: false + type: error.list + request_id: d5bac7ff-7961-4fe5-8aed-6f1b031b38af + errors: + - code: unauthorized + message: Access Token Invalid schema: - "$ref": "#/components/schemas/contact_unarchived" - "/contacts/merge": + "$ref": "#/components/schemas/error" post: - summary: Merge a lead and a user + summary: Create contact parameters: - name: Intercom-Version in: header @@ -3804,9 +3900,8 @@ paths: "$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`. + operationId: CreateContact + description: You can create a new contact (ie. user or lead). responses: '200': description: successful @@ -3816,13 +3911,13 @@ paths: successful: value: type: contact - id: 667d60ac8a68186f43bafdbc - workspace_id: this_is_an_id260_that_should_be_at_least_ - external_id: '70' + id: 667d60b08a68186f43bafdbf + workspace_id: this_is_an_id272_that_should_be_at_least_ + external_id: role: user - email: joe@bloggs.com + email: joebloggs@intercom.io phone: - name: Joe Bloggs + name: avatar: owner_id: social_profiles: @@ -3831,9 +3926,9 @@ paths: has_hard_bounced: false marked_email_as_spam: false unsubscribed_from_emails: false - created_at: 1719492780 - updated_at: 1719492780 - signed_up_at: 1719492780 + created_at: 1719492784 + updated_at: 1719492784 + signed_up_at: last_seen_at: last_replied_at: last_contacted_at: @@ -3867,31 +3962,31 @@ paths: tags: type: list data: [] - url: "/contacts/667d60ac8a68186f43bafdbc/tags" + url: "/contacts/667d60b08a68186f43bafdbf/tags" total_count: 0 has_more: false notes: type: list data: [] - url: "/contacts/667d60ac8a68186f43bafdbc/notes" + url: "/contacts/667d60b08a68186f43bafdbf/notes" total_count: 0 has_more: false companies: type: list data: [] - url: "/contacts/667d60ac8a68186f43bafdbc/companies" + url: "/contacts/667d60b08a68186f43bafdbf/companies" total_count: 0 has_more: false opted_out_subscription_types: type: list data: [] - url: "/contacts/667d60ac8a68186f43bafdbc/subscriptions" + url: "/contacts/667d60b08a68186f43bafdbf/subscriptions" total_count: 0 has_more: false opted_in_subscription_types: type: list data: [] - url: "/contacts/667d60ac8a68186f43bafdbc/subscriptions" + url: "/contacts/667d60b08a68186f43bafdbf/subscriptions" total_count: 0 has_more: false utm_campaign: @@ -3901,7 +3996,146 @@ paths: utm_term: referrer: schema: - "$ref": "#/components/schemas/contact" + "$ref": "#/components/schemas/contact" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: c18ca0d4-ad2c-41e7-9a71-1df806f9c954 + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + requestBody: + content: + application/json: + schema: + oneOf: + - "$ref": "#/components/schemas/create_contact_request" + examples: + successful: + summary: successful + value: + email: joebloggs@intercom.io + "/contacts/{contact_id}/archive": + post: + summary: Archive 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 + operationId: ArchiveContact + description: You can archive a single contact. + responses: + '200': + description: successful + content: + application/json: + examples: + successful: + value: + id: 667d60b18a68186f43bafdc0 + external_id: '70' + type: contact + archived: true + schema: + "$ref": "#/components/schemas/contact_archived" + "/contacts/{contact_id}/unarchive": + post: + summary: Unarchive 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 + operationId: UnarchiveContact + description: You can unarchive a single contact. + responses: + '200': + description: successful + content: + application/json: + examples: + successful: + value: + id: 667d60b28a68186f43bafdc1 + external_id: '70' + type: contact + archived: false + schema: + "$ref": "#/components/schemas/contact_unarchived" + "/conversations/{conversation_id}/tags": + post: + summary: Add tag to a conversation + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + - name: conversation_id + in: path + description: conversation_id + example: '64619700005694' + required: true + schema: + type: string + tags: + - Tags + - Conversations + operationId: attachTagToConversation + description: You can tag a specific conversation. This will return a tag object + for the tag that was added to the conversation. + responses: + '200': + description: successful + content: + application/json: + examples: + successful: + value: + type: tag + id: '99' + name: Manual tag + schema: + "$ref": "#/components/schemas/tag" + '404': + description: Conversation not found + content: + application/json: + examples: + Conversation not found: + value: + type: error.list + request_id: 840d35aa-2414-402a-b3c6-763a410e0d16 + errors: + - code: not_found + message: Conversation not found + schema: + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -3910,7 +4144,7 @@ paths: Unauthorized: value: type: error.list - request_id: 57b64228-0e60-4e35-833d-39c4e4067dde + request_id: 95cacea0-4744-4de8-a2bf-da4419f75732 errors: - code: unauthorized message: Access Token Invalid @@ -3920,125 +4154,60 @@ paths: content: application/json: schema: - "$ref": "#/components/schemas/merge_contacts_request" + type: object + required: + - id + - admin_id + properties: + id: + type: string + description: The unique identifier for the tag which is given by + Intercom + example: '7522907' + admin_id: + type: string + description: The unique identifier for the admin which is given + by Intercom. + example: '780' examples: successful: summary: successful value: - from: 667d60ac8a68186f43bafdbb - into: 667d60ac8a68186f43bafdbc - "/contacts/search": - post: - summary: Search contacts + id: 99 + admin_id: 991267526 + conversation_not_found: + summary: Conversation not found + value: + id: 100 + admin_id: 991267528 + "/conversations/{conversation_id}/tags/{tag_id}": + delete: + summary: Remove tag from a conversation parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" + - name: conversation_id + in: path + description: conversation_id + example: '64619700005694' + required: true + schema: + type: string + - name: tag_id + in: path + description: id + example: '7522907' + required: true + schema: + type: string 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 | String
Accepts user or lead | - | name | String | - | avatar | String | - | owner_id | Integer | - | email | String | - | email_domain | String | - | phone | String | - | formatted_phone | String | - | external_id | String | - | created_at | Date (UNIX Timestamp) | - | signed_up_at | Date (UNIX Timestamp) | - | updated_at | Date (UNIX Timestamp) | - | last_seen_at | Date (UNIX Timestamp) | - | last_contacted_at | Date (UNIX Timestamp) | - | last_replied_at | Date (UNIX Timestamp) | - | last_email_opened_at | Date (UNIX Timestamp) | - | last_email_clicked_at | Date (UNIX Timestamp) | - | language_override | String | - | browser | String | - | browser_language | String | - | os | String | - | location.country | String | - | location.region | String | - | location.city | String | - | unsubscribed_from_emails | Boolean | - | marked_email_as_spam | Boolean | - | has_hard_bounced | Boolean | - | ios_last_seen_at | Date (UNIX Timestamp) | - | ios_app_version | String | - | ios_device | String | - | ios_app_device | String | - | ios_os_version | String | - | ios_app_name | String | - | ios_sdk_version | String | - | android_last_seen_at | Date (UNIX Timestamp) | - | android_app_version | String | - | android_device | String | - | android_app_name | String | - | andoid_sdk_version | String | - | segment_id | String | - | tag_id | String | - | custom_attributes.{attribute_name} | String | - - ### Accepted Operators - - {% admonition type="attention" name="Searching based on `created_at`" %} - You cannot use the `<=` or `>=` operators to search by `created_at`. - {% /admonition %} - - The table below shows the operators you can use to define how you want to search for the value. The operator should be put in as a string (`"="`). The operator has to be compatible with the field's type (eg. you cannot search with `>` for a given string value as it's only compatible for integer's and dates). - - | Operator | Valid Types | Description | - | :------- | :------------------------------- | :--------------------------------------------------------------- | - | = | All | Equals | - | != | All | Doesn't Equal | - | IN | All | In
Shortcut for `OR` queries
Values must be in Array | - | NIN | All | Not In
Shortcut for `OR !` queries
Values must be in Array | - | > | Integer
Date (UNIX Timestamp) | Greater than | - | < | Integer
Date (UNIX Timestamp) | Lower than | - | ~ | String | Contains | - | !~ | String | Doesn't Contain | - | ^ | String | Starts With | - | $ | String | Ends With | + - Tags + - Conversations + operationId: detachTagFromConversation + description: You can remove tag from a specific conversation. This will return + a tag object for the tag that was removed from the conversation. responses: '200': description: successful @@ -4047,16 +4216,32 @@ paths: examples: successful: value: - type: list - data: [] - total_count: 0 - pages: - type: pages - page: 1 - per_page: 5 - total_pages: 0 + type: tag + id: '102' + name: Manual tag + schema: + "$ref": "#/components/schemas/tag" + '404': + description: Tag not found + content: + application/json: + examples: + Conversation not found: + value: + type: error.list + request_id: f78f63ba-911d-47b8-a389-b33e3ccbe77e + errors: + - code: not_found + message: Conversation not found + Tag not found: + value: + type: error.list + request_id: 0d00d069-2cf1-496f-b887-a4db74ee320d + errors: + - code: tag_not_found + message: Tag not found schema: - "$ref": "#/components/schemas/contact_list" + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -4065,7 +4250,7 @@ paths: Unauthorized: value: type: error.list - request_id: 2b28c47b-8fa3-4e17-8fc1-6ba80f1cc844 + request_id: f083d6b1-e9d2-43b3-86df-67539007fc3e errors: - code: unauthorized message: Access Token Invalid @@ -4075,19 +4260,28 @@ paths: content: application/json: schema: - "$ref": "#/components/schemas/search_request" + type: object + required: + - admin_id + properties: + admin_id: + type: string + description: The unique identifier for the admin which is given + by Intercom. + example: '123' examples: successful: summary: successful value: - query: - operator: AND - value: - - field: created_at - operator: ">" - value: '1306054154' - pagination: - per_page: 5 + admin_id: 991267530 + conversation_not_found: + summary: Conversation not found + value: + admin_id: 991267532 + tag_not_found: + summary: Tag not found + value: + admin_id: 991267533 "/conversations": get: summary: List all conversations @@ -4580,231 +4774,29 @@ paths: updated_at: 1719492834 notified_at: 1719492834 assigned_to: - author: - id: '991267562' - type: bot - name: Operator - email: operator+this_is_an_id321_that_should_be_at_least_@intercom.io - attachments: [] - external_id: - redacted: false - total_count: 2 - schema: - "$ref": "#/components/schemas/conversation" - '404': - description: Not found - content: - application/json: - examples: - Not found: - value: - type: error.list - request_id: e4c692dd-cccd-46bf-834a-cda7a3a9029c - 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: 58e6b9ee-4a28-4597-9c20-faf34b6894dc - 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: cf6fb162-88c9-45ec-9f97-c3fcad93b7c1 - 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 - custom_attributes: - issue_type: Billing - priority: High - not_found: - summary: Not found - value: - read: true - custom_attributes: - issue_type: Billing - priority: High - "/conversations/{conversation_id}/tags": - post: - summary: Add tag to a conversation - parameters: - - name: Intercom-Version - in: header - schema: - "$ref": "#/components/schemas/intercom_version" - - name: conversation_id - in: path - description: conversation_id - example: '64619700005694' - required: true - schema: - type: string - tags: - - Tags - - Conversations - operationId: attachTagToConversation - description: You can tag a specific conversation. This will return a tag object - for the tag that was added to the conversation. - responses: - '200': - description: successful - content: - application/json: - examples: - successful: - value: - type: tag - id: '99' - name: Manual tag - schema: - "$ref": "#/components/schemas/tag" - '404': - description: Conversation not found - content: - application/json: - examples: - Conversation not found: - value: - type: error.list - request_id: 840d35aa-2414-402a-b3c6-763a410e0d16 - errors: - - code: not_found - message: Conversation not found - schema: - "$ref": "#/components/schemas/error" - '401': - description: Unauthorized - content: - application/json: - examples: - Unauthorized: - value: - type: error.list - request_id: 95cacea0-4744-4de8-a2bf-da4419f75732 - errors: - - code: unauthorized - message: Access Token Invalid - schema: - "$ref": "#/components/schemas/error" - requestBody: - content: - application/json: - schema: - type: object - required: - - id - - admin_id - properties: - id: - type: string - description: The unique identifier for the tag which is given by - Intercom - example: '7522907' - admin_id: - type: string - description: The unique identifier for the admin which is given - by Intercom. - example: '780' - examples: - successful: - summary: successful - value: - id: 99 - admin_id: 991267526 - conversation_not_found: - summary: Conversation not found - value: - id: 100 - admin_id: 991267528 - "/conversations/{conversation_id}/tags/{tag_id}": - delete: - summary: Remove tag from a conversation - parameters: - - name: Intercom-Version - in: header - schema: - "$ref": "#/components/schemas/intercom_version" - - name: conversation_id - in: path - description: conversation_id - example: '64619700005694' - required: true - schema: - type: string - - name: tag_id - in: path - description: id - example: '7522907' - required: true - schema: - type: string - tags: - - Tags - - Conversations - operationId: detachTagFromConversation - description: You can remove tag from a specific conversation. This will return - a tag object for the tag that was removed from the conversation. - responses: - '200': - description: successful - content: - application/json: - examples: - successful: - value: - type: tag - id: '102' - name: Manual tag + author: + id: '991267562' + type: bot + name: Operator + email: operator+this_is_an_id321_that_should_be_at_least_@intercom.io + attachments: [] + external_id: + redacted: false + total_count: 2 schema: - "$ref": "#/components/schemas/tag" + "$ref": "#/components/schemas/conversation" '404': - description: Tag not found + description: Not found content: application/json: examples: - Conversation not found: + Not found: value: type: error.list - request_id: f78f63ba-911d-47b8-a389-b33e3ccbe77e + request_id: e4c692dd-cccd-46bf-834a-cda7a3a9029c errors: - code: not_found - message: Conversation not found - Tag not found: - value: - type: error.list - request_id: 0d00d069-2cf1-496f-b887-a4db74ee320d - errors: - - code: tag_not_found - message: Tag not found + message: Resource Not Found schema: "$ref": "#/components/schemas/error" '401': @@ -4815,38 +4807,243 @@ paths: Unauthorized: value: type: error.list - request_id: f083d6b1-e9d2-43b3-86df-67539007fc3e + request_id: 58e6b9ee-4a28-4597-9c20-faf34b6894dc 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: cf6fb162-88c9-45ec-9f97-c3fcad93b7c1 + errors: + - code: api_plan_restricted + message: Active subscription needed. + schema: + "$ref": "#/components/schemas/error" requestBody: content: application/json: schema: - type: object - required: - - admin_id - properties: - admin_id: - type: string - description: The unique identifier for the admin which is given - by Intercom. - example: '123' + "$ref": "#/components/schemas/update_conversation_request" examples: - successful: - summary: successful + conversation_found: + summary: conversation found value: - admin_id: 991267530 - conversation_not_found: - summary: Conversation not found + read: true + custom_attributes: + issue_type: Billing + priority: High + not_found: + summary: Not found value: - admin_id: 991267532 - tag_not_found: - summary: Tag not found + read: true + custom_attributes: + issue_type: Billing + priority: High + "/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 as part of the The conversation model is 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 | String
Accepted fields are `conversation`, `email`, `facebook`, `instagram`, `phone_call`, `phone_switch`, `push`, `sms`, `twitter` and `whatsapp`. | + | source.id | String | + | source.delivered_as | String | + | source.subject | String | + | source.body | String | + | source.author.id | String | + | source.author.type | String | + | source.author.name | String | + | source.author.email | String | + | source.url | String | + | contact_ids | String | + | teammate_ids | String | + | admin_assignee_id | String | + | team_assignee_id | String | + | channel_initiated | String | + | open | Boolean | + | read | Boolean | + | state | String | + | waiting_since | Date (UNIX timestamp) | + | snoozed_until | Date (UNIX timestamp) | + | tag_ids | String | + | priority | String | + | statistics.time_to_assignment | Integer | + | statistics.time_to_admin_reply | Integer | + | statistics.time_to_first_close | Integer | + | statistics.time_to_last_close | Integer | + | statistics.median_time_to_reply | Integer | + | statistics.first_contact_reply_at | Date (UNIX timestamp) | + | statistics.first_assignment_at | Date (UNIX timestamp) | + | statistics.first_admin_reply_at | Date (UNIX timestamp) | + | statistics.first_close_at | Date (UNIX timestamp) | + | statistics.last_assignment_at | Date (UNIX timestamp) | + | statistics.last_assignment_admin_reply_at | Date (UNIX timestamp) | + | statistics.last_contact_reply_at | Date (UNIX timestamp) | + | statistics.last_admin_reply_at | Date (UNIX timestamp) | + | statistics.last_close_at | Date (UNIX timestamp) | + | statistics.last_closed_by_id | String | + | statistics.count_reopens | Integer | + | statistics.count_assignments | Integer | + | statistics.count_conversation_parts | Integer | + | conversation_rating.requested_at | Date (UNIX timestamp) | + | conversation_rating.replied_at | Date (UNIX timestamp) | + | conversation_rating.score | Integer | + | conversation_rating.remark | String | + | conversation_rating.contact_id | String | + | conversation_rating.admin_d | String | + | ai_agent_participated | Boolean | + | ai_agent.resolution_state | String | + | ai_agent.last_answer_type | String | + | ai_agent.rating | Integer | + | ai_agent.rating_remark | String | + | ai_agent.source_type | String | + | ai_agent.source_title | String | + + ### Accepted Operators + + The table below shows the operators you can use to define how you want to search for the value. The operator should be put in as a string (`"="`). The operator has to be compatible with the field's type (eg. you cannot search with `>` for a given string value as it's only compatible for integer's and dates). + + | Operator | Valid Types | Description | + | :------- | :----------------------------- | :----------------------------------------------------------- | + | = | All | Equals | + | != | All | Doesn't Equal | + | IN | All | In Shortcut for `OR` queries Values most be in Array | + | NIN | All | Not In Shortcut for `OR !` queries Values must be in Array | + | > | Integer Date (UNIX Timestamp) | Greater (or equal) than | + | < | Integer Date (UNIX Timestamp) | Lower (or equal) than | + | ~ | String | Contains | + | !~ | String | Doesn't Contain | + | ^ | String | Starts With | + | $ | String | Ends With | + responses: + '200': + description: successful + content: + application/json: + examples: + successful: + value: + type: conversation.list + pages: + type: pages + page: 1 + per_page: 5 + total_pages: 1 + total_count: 1 + conversations: + - type: conversation + id: '378' + created_at: 1719492843 + updated_at: 1719492843 + waiting_since: + snoozed_until: + source: + type: conversation + id: '403918266' + delivered_as: admin_initiated + subject: '' + body: "

this is the message body

" + author: + type: admin + id: '991267591' + name: Ciaran180 Lee + email: admin180@email.com + attachments: [] + url: + redacted: false + contacts: + type: contact.list + contacts: + - type: contact + id: 667d60ea8a68186f43bafdec + 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/paginated_conversation_response" + requestBody: + content: + application/json: + schema: + "$ref": "#/components/schemas/search_request" + examples: + successful: + summary: successful value: - admin_id: 991267533 + query: + operator: AND + value: + - field: created_at + operator: ">" + value: '1306054154' + pagination: + per_page: 5 "/conversations/{conversation_id}/reply": post: summary: Reply to a conversation @@ -5986,134 +6183,6 @@ paths: admin_id: 991267648 customer: intercom_user_id: 667d61338a68186f43bafe2a - "/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: string - 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: '474' - ticket_id: '37' - ticket_attributes: {} - ticket_state: submitted - ticket_type: - type: ticket_type - id: '79' - name: my-ticket-type-1 - description: my ticket type description is awesome. - icon: "\U0001F981" - workspace_id: this_is_an_id404_that_should_be_at_least_ - archived: false - created_at: 1719492947 - updated_at: 1719492947 - is_internal: false - ticket_type_attributes: - type: list - data: [] - category: Customer - contacts: - type: contact.list - contacts: - - type: contact - id: 667d61518a68186f43bafe45 - external_id: '70' - admin_assignee_id: '0' - team_assignee_id: '0' - created_at: 1719492945 - updated_at: 1719492947 - ticket_parts: - type: ticket_part.list - ticket_parts: - - type: ticket_part - id: '117' - part_type: comment - body: "

Comment for message

" - created_at: 1719492945 - updated_at: 1719492945 - author: - id: 667d61518a68186f43bafe45 - type: user - name: Joe Bloggs - email: joe@bloggs.com - attachments: [] - redacted: false - - type: ticket_part - id: '118' - part_type: ticket_state_updated_by_admin - ticket_state: submitted - previous_ticket_state: submitted - created_at: 1719492947 - updated_at: 1719492947 - author: - id: '991267667' - type: bot - name: Operator - email: operator+this_is_an_id404_that_should_be_at_least_@intercom.io - attachments: [] - redacted: false - total_count: 2 - open: true - linked_objects: - type: list - data: [] - total_count: 0 - has_more: false - category: Customer - is_shared: true - ticket_state_internal_label: Submitted - ticket_state_external_label: Submitted - schema: - "$ref": "#/components/schemas/ticket" - '400': - description: Bad request - content: - application/json: - examples: - Bad request: - value: - type: error.list - request_id: 74656c1a-0a17-4c80-a7b9-66fa45c6d71b - 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: '79' - bad_request: - summary: Bad request - value: - ticket_type_id: '80' "/conversations/redact": post: summary: Redact a conversation part @@ -6258,121 +6327,29 @@ paths: conversation_part_id: 115 not_found: summary: Not found - value: - type: conversation_part - conversation_id: really_123_doesnt_exist - conversation_part_id: really_123_doesnt_exist - "/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 as part of the The conversation model is 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 | String
Accepted fields are `conversation`, `email`, `facebook`, `instagram`, `phone_call`, `phone_switch`, `push`, `sms`, `twitter` and `whatsapp`. | - | source.id | String | - | source.delivered_as | String | - | source.subject | String | - | source.body | String | - | source.author.id | String | - | source.author.type | String | - | source.author.name | String | - | source.author.email | String | - | source.url | String | - | contact_ids | String | - | teammate_ids | String | - | admin_assignee_id | String | - | team_assignee_id | String | - | channel_initiated | String | - | open | Boolean | - | read | Boolean | - | state | String | - | waiting_since | Date (UNIX timestamp) | - | snoozed_until | Date (UNIX timestamp) | - | tag_ids | String | - | priority | String | - | statistics.time_to_assignment | Integer | - | statistics.time_to_admin_reply | Integer | - | statistics.time_to_first_close | Integer | - | statistics.time_to_last_close | Integer | - | statistics.median_time_to_reply | Integer | - | statistics.first_contact_reply_at | Date (UNIX timestamp) | - | statistics.first_assignment_at | Date (UNIX timestamp) | - | statistics.first_admin_reply_at | Date (UNIX timestamp) | - | statistics.first_close_at | Date (UNIX timestamp) | - | statistics.last_assignment_at | Date (UNIX timestamp) | - | statistics.last_assignment_admin_reply_at | Date (UNIX timestamp) | - | statistics.last_contact_reply_at | Date (UNIX timestamp) | - | statistics.last_admin_reply_at | Date (UNIX timestamp) | - | statistics.last_close_at | Date (UNIX timestamp) | - | statistics.last_closed_by_id | String | - | statistics.count_reopens | Integer | - | statistics.count_assignments | Integer | - | statistics.count_conversation_parts | Integer | - | conversation_rating.requested_at | Date (UNIX timestamp) | - | conversation_rating.replied_at | Date (UNIX timestamp) | - | conversation_rating.score | Integer | - | conversation_rating.remark | String | - | conversation_rating.contact_id | String | - | conversation_rating.admin_d | String | - | ai_agent_participated | Boolean | - | ai_agent.resolution_state | String | - | ai_agent.last_answer_type | String | - | ai_agent.rating | Integer | - | ai_agent.rating_remark | String | - | ai_agent.source_type | String | - | ai_agent.source_title | String | - - ### Accepted Operators - - The table below shows the operators you can use to define how you want to search for the value. The operator should be put in as a string (`"="`). The operator has to be compatible with the field's type (eg. you cannot search with `>` for a given string value as it's only compatible for integer's and dates). - - | Operator | Valid Types | Description | - | :------- | :----------------------------- | :----------------------------------------------------------- | - | = | All | Equals | - | != | All | Doesn't Equal | - | IN | All | In Shortcut for `OR` queries Values most be in Array | - | NIN | All | Not In Shortcut for `OR !` queries Values must be in Array | - | > | Integer Date (UNIX Timestamp) | Greater (or equal) than | - | < | Integer Date (UNIX Timestamp) | Lower (or equal) than | - | ~ | String | Contains | - | !~ | String | Doesn't Contain | - | ^ | String | Starts With | - | $ | String | Ends With | + 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: string + tags: + - Conversations + description: You can convert a conversation to a ticket. + operationId: convertConversationToTicket responses: '200': description: successful @@ -6381,84 +6358,107 @@ paths: examples: successful: value: - type: conversation.list - pages: - type: pages - page: 1 - per_page: 5 - total_pages: 1 - total_count: 1 - conversations: - - type: conversation - id: '378' - created_at: 1719492843 - updated_at: 1719492843 - waiting_since: - snoozed_until: - source: - type: conversation - id: '403918266' - delivered_as: admin_initiated - subject: '' - body: "

this is the message body

" + type: ticket + id: '474' + ticket_id: '37' + ticket_attributes: {} + ticket_state: submitted + ticket_type: + type: ticket_type + id: '79' + name: my-ticket-type-1 + description: my ticket type description is awesome. + icon: "\U0001F981" + workspace_id: this_is_an_id404_that_should_be_at_least_ + archived: false + created_at: 1719492947 + updated_at: 1719492947 + is_internal: false + ticket_type_attributes: + type: list + data: [] + category: Customer + contacts: + type: contact.list + contacts: + - type: contact + id: 667d61518a68186f43bafe45 + external_id: '70' + admin_assignee_id: '0' + team_assignee_id: '0' + created_at: 1719492945 + updated_at: 1719492947 + ticket_parts: + type: ticket_part.list + ticket_parts: + - type: ticket_part + id: '117' + part_type: comment + body: "

Comment for message

" + created_at: 1719492945 + updated_at: 1719492945 author: - type: admin - id: '991267591' - name: Ciaran180 Lee - email: admin180@email.com + id: 667d61518a68186f43bafe45 + type: user + name: Joe Bloggs + email: joe@bloggs.com attachments: [] - url: redacted: false - contacts: - type: contact.list - contacts: - - type: contact - id: 667d60ea8a68186f43bafdec - 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 + - type: ticket_part + id: '118' + part_type: ticket_state_updated_by_admin + ticket_state: submitted + previous_ticket_state: submitted + created_at: 1719492947 + updated_at: 1719492947 + author: + id: '991267667' + type: bot + name: Operator + email: operator+this_is_an_id404_that_should_be_at_least_@intercom.io + attachments: [] + redacted: false + total_count: 2 + open: true + linked_objects: + type: list + data: [] + total_count: 0 + has_more: false + category: Customer + is_shared: true + ticket_state_internal_label: Submitted + ticket_state_external_label: Submitted schema: - "$ref": "#/components/schemas/paginated_conversation_response" + "$ref": "#/components/schemas/ticket" + '400': + description: Bad request + content: + application/json: + examples: + Bad request: + value: + type: error.list + request_id: 74656c1a-0a17-4c80-a7b9-66fa45c6d71b + 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/search_request" + "$ref": "#/components/schemas/convert_conversation_to_ticket_request" examples: successful: summary: successful value: - query: - operator: AND - value: - - field: created_at - operator: ">" - value: '1306054154' - pagination: - per_page: 5 + ticket_type_id: '79' + bad_request: + summary: Bad request + value: + ticket_type_id: '80' "/data_attributes": get: summary: List all data attributes @@ -7954,18 +7954,27 @@ paths: message: Access Token Invalid schema: "$ref": "#/components/schemas/error" - "/news/newsfeeds": + "/news/newsfeeds/{newsfeed_id}/items": get: - summary: List all newsfeeds + 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: listNewsfeeds - description: You can fetch a list of all newsfeeds + operationId: listLiveNewsfeedItems + description: You can fetch a list of all news items that are live on a given + newsfeed responses: '200': description: successful @@ -7977,23 +7986,13 @@ paths: type: list pages: page: 1 - per_page: 10 - total_pages: 1 + per_page: 20 + total_pages: 0 type: pages - data: - - id: '68' - type: newsfeed - name: Visitor Feed - created_at: 1719492987 - updated_at: 1719492987 - - id: '69' - type: newsfeed - name: Visitor Feed - created_at: 1719492987 - updated_at: 1719492987 - total_count: 2 + data: [] + total_count: 0 schema: - "$ref": "#/components/schemas/paginated_newsfeed_response" + "$ref": "#/components/schemas/paginated_news_item_response" '401': description: Unauthorized content: @@ -8002,32 +8001,24 @@ paths: Unauthorized: value: type: error.list - request_id: d00f8d67-1e7c-464b-b0b7-b2409d706076 + request_id: de07bbcf-64ff-4fc8-a7e5-fcbe772b85a5 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" - "/news/newsfeeds/{newsfeed_id}": + "/news/newsfeeds": get: - summary: Retrieve a newsfeed + summary: List all newsfeeds 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 + operationId: listNewsfeeds + description: You can fetch a list of all newsfeeds responses: '200': description: successful @@ -8036,13 +8027,26 @@ paths: examples: successful: value: - id: '72' - type: newsfeed - name: Visitor Feed - created_at: 1719492988 - updated_at: 1719492988 + type: list + pages: + page: 1 + per_page: 10 + total_pages: 1 + type: pages + data: + - id: '68' + type: newsfeed + name: Visitor Feed + created_at: 1719492987 + updated_at: 1719492987 + - id: '69' + type: newsfeed + name: Visitor Feed + created_at: 1719492987 + updated_at: 1719492987 + total_count: 2 schema: - "$ref": "#/components/schemas/newsfeed" + "$ref": "#/components/schemas/paginated_newsfeed_response" '401': description: Unauthorized content: @@ -8051,15 +8055,15 @@ paths: Unauthorized: value: type: error.list - request_id: 185ce494-34e2-4cda-85cb-c51ad7281292 + request_id: d00f8d67-1e7c-464b-b0b7-b2409d706076 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" - "/news/newsfeeds/{newsfeed_id}/items": + "/news/newsfeeds/{newsfeed_id}": get: - summary: List all live newsfeed items + summary: Retrieve a newsfeed parameters: - name: Intercom-Version in: header @@ -8075,9 +8079,8 @@ paths: type: string tags: - News - operationId: listLiveNewsfeedItems - description: You can fetch a list of all news items that are live on a given - newsfeed + operationId: retrieveNewsfeed + description: You can fetch the details of a single newsfeed responses: '200': description: successful @@ -8086,16 +8089,13 @@ paths: examples: successful: value: - type: list - pages: - page: 1 - per_page: 20 - total_pages: 0 - type: pages - data: [] - total_count: 0 + id: '72' + type: newsfeed + name: Visitor Feed + created_at: 1719492988 + updated_at: 1719492988 schema: - "$ref": "#/components/schemas/paginated_news_item_response" + "$ref": "#/components/schemas/newsfeed" '401': description: Unauthorized content: @@ -8104,7 +8104,7 @@ paths: Unauthorized: value: type: error.list - request_id: de07bbcf-64ff-4fc8-a7e5-fcbe772b85a5 + request_id: 185ce494-34e2-4cda-85cb-c51ad7281292 errors: - code: unauthorized message: Access Token Invalid @@ -8835,6 +8835,154 @@ paths: 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: '210' + workspace_id: this_is_an_id600_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: 81 + archived: false + created_at: 1719493013 + updated_at: 1719493013 + schema: + "$ref": "#/components/schemas/ticket_type_attribute" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: 3bc672fa-e051-4ede-b6e9-79f518231ba9 + 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: '215' + workspace_id: this_is_an_id604_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: 83 + archived: false + created_at: 1719493013 + updated_at: 1719493014 + schema: + "$ref": "#/components/schemas/ticket_type_attribute" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: 6e45414c-e627-4769-bdbd-d51f2c19e1e9 + 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 @@ -9269,130 +9417,104 @@ paths: summary: Ticket type updated value: name: Bug Report 2 - "/ticket_types/{ticket_type_id}/attributes": + "/tickets/{ticket_id}/reply": post: - summary: Create a new attribute for a ticket type + 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_type_id + - name: ticket_id in: path required: true - description: The unique identifier for the ticket type which is given by Intercom. schema: + title: Ticket ID type: string + description: The id of the ticket to target. + example: "123" tags: - - Ticket Type Attributes - description: You can create a new attribute for a ticket type. - operationId: createTicketTypeAttribute + - Tickets responses: + '400': + description: User reply + content: + application/json: + examples: + User reply: + value: + type: error.list + request_id: b8b42c55-347c-4704-b4c1-92220c01f4ac + errors: + - code: parameter_mismatch + message: User replies are not allowed on Backoffice tickets + schema: + "$ref": "#/components/schemas/error" '200': - description: Ticket Type Attribute created + description: Admin quick_reply reply content: application/json: examples: - Ticket Type Attribute created: + Admin note reply: value: - type: ticket_type_attribute - id: '210' - workspace_id: this_is_an_id600_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: 81 - archived: false - created_at: 1719493013 - updated_at: 1719493013 + type: ticket_part + id: '122' + part_type: note + body: |- +

An Unordered HTML List

+
    +
  • Coffee
    • +
  • Tea
    • +
  • Milk
    • +
+

An Ordered HTML List

+
    +
  1. Coffee
    2. +
  2. Tea
    3. +
  3. Milk
    4. +
+ created_at: 1719493024 + updated_at: 1719493024 + author: + id: '991267829' + type: admin + name: Ciaran375 Lee + email: admin375@email.com + attachments: [] + redacted: false + Admin quick_reply reply: + value: + type: ticket_part + id: '124' + part_type: quick_reply + created_at: 1719493029 + updated_at: 1719493029 + author: + id: '991267834' + type: admin + name: Ciaran379 Lee + email: admin379@email.com + attachments: [] + redacted: false schema: - "$ref": "#/components/schemas/ticket_type_attribute" - '401': - description: Unauthorized + "$ref": "#/components/schemas/ticket_reply" + '404': + description: Not found content: application/json: examples: - Unauthorized: + Not found: value: type: error.list - request_id: 3bc672fa-e051-4ede-b6e9-79f518231ba9 + request_id: c23e8dab-6102-483c-bb1b-c62923be35ab errors: - - code: unauthorized - message: Access Token Invalid + - code: not_found + message: Resource Not Found 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: '215' - workspace_id: this_is_an_id604_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: 83 - archived: false - created_at: 1719493013 - updated_at: 1719493014 - schema: - "$ref": "#/components/schemas/ticket_type_attribute" '401': description: Unauthorized content: @@ -9401,7 +9523,7 @@ paths: Unauthorized: value: type: error.list - request_id: 6e45414c-e627-4769-bdbd-d51f2c19e1e9 + request_id: bb012854-cca8-4fa7-972e-6c38204e8294 errors: - code: unauthorized message: Access Token Invalid @@ -9411,128 +9533,93 @@ paths: content: application/json: schema: - "$ref": "#/components/schemas/update_ticket_type_attribute_request" + oneOf: + - "$ref": "#/components/schemas/contact_reply_ticket_request" + - "$ref": "#/components/schemas/admin_reply_ticket_request" examples: - ticket_type_attribute_updated: - summary: Ticket Type Attribute updated + user_reply: + summary: User reply value: - description: New Attribute Description - "/tickets": + message_type: comment + type: user + intercom_user_id: 667d619d8a68186f43bafe82 + body: Thanks again :) + admin_note_reply: + summary: Admin note reply + value: + message_type: note + type: admin + admin_id: 991267829 + body: "

An Unordered HTML List

  • Coffee
    • + \
  • Tea
  • Milk

An Ordered HTML List

+ \
  1. Coffee
  2. Tea
  3. Milk
+ \ " + admin_quick_reply_reply: + summary: Admin quick_reply reply + value: + message_type: quick_reply + type: admin + admin_id: 991267834 + reply_options: + - text: 'Yes' + uuid: 22d6d1f4-1a19-41d0-94c2-e54031f78aca + - text: 'No' + uuid: fbc3dbe0-ec0c-4fb6-826d-e19127191906 + not_found: + summary: Not found + value: + message_type: comment + type: user + intercom_user_id: 667d61a68a68186f43bafe85 + body: Thanks again :) + "/tickets/{ticket_id}/tags": post: - summary: Create a ticket + summary: Add tag to a ticket parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" + - name: ticket_id + in: path + description: ticket_id + example: '64619700005694' + required: true + schema: + type: string tags: + - Tags - Tickets - description: You can create a new ticket. - operationId: createTicket + operationId: attachTagToTicket + description: You can tag a specific ticket. This will return a tag object for + the tag that was added to the ticket. responses: '200': - description: Successful response + description: successful content: application/json: examples: - Successful response: + successful: value: - type: ticket - id: '489' - ticket_id: '48' - ticket_attributes: - _default_title_: example - _default_description_: there is a problem - ticket_state: submitted - ticket_type: - type: ticket_type - id: '106' - name: my-ticket-type-15 - description: my ticket type description is awesome. - icon: "\U0001F981" - workspace_id: this_is_an_id648_that_should_be_at_least_ - archived: false - created_at: 1719493047 - updated_at: 1719493047 - is_internal: false - ticket_type_attributes: - type: list - data: - - type: ticket_type_attribute - id: '252' - workspace_id: this_is_an_id648_that_should_be_at_least_ - name: _default_title_ - description: ola - data_type: string - input_options: - order: 0 - required_to_create: true - required_to_create_for_contacts: false - visible_on_create: true - visible_to_contacts: false - default: false - ticket_type_id: 106 - archived: false - created_at: 1719493047 - updated_at: 1719493047 - - type: ticket_type_attribute - id: '253' - workspace_id: this_is_an_id648_that_should_be_at_least_ - name: _default_description_ - description: ola - data_type: string - input_options: - order: 0 - required_to_create: true - required_to_create_for_contacts: false - visible_on_create: true - visible_to_contacts: false - default: false - ticket_type_id: 106 - archived: false - created_at: 1719493047 - updated_at: 1719493047 - category: Back-office - contacts: - type: contact.list - contacts: - - type: contact - id: 667d61b78a68186f43bafe8d - external_id: '70' - admin_assignee_id: '0' - team_assignee_id: '0' - created_at: 1719493048 - updated_at: 1719493048 - ticket_parts: - type: ticket_part.list - ticket_parts: - - type: ticket_part - id: '125' - part_type: ticket_state_updated_by_admin - ticket_state: submitted - previous_ticket_state: submitted - created_at: 1719493048 - updated_at: 1719493048 - author: - id: '991267871' - type: bot - name: Operator - email: operator+this_is_an_id648_that_should_be_at_least_@intercom.io - attachments: [] - redacted: false - total_count: 1 - open: true - linked_objects: - type: list - data: [] - total_count: 0 - has_more: false - category: Back-office - is_shared: false - ticket_state_internal_label: Submitted - ticket_state_external_label: Submitted + type: tag + id: '134' + name: Manual tag + schema: + "$ref": "#/components/schemas/tag" + '404': + description: Ticket not found + content: + application/json: + examples: + Ticket not found: + value: + type: error.list + request_id: e11d8f55-82fe-4c0d-b4c6-6f22c6a694e9 + errors: + - code: ticket_not_found + message: Ticket not found schema: - "$ref": "#/components/schemas/ticket" + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -9541,7 +9628,7 @@ paths: Unauthorized: value: type: error.list - request_id: 745c921a-7c5a-40d4-ab28-6d28a8d2ed47 + request_id: a502f48f-c80d-48fd-bea5-cafe7e24d9f9 errors: - code: unauthorized message: Access Token Invalid @@ -9551,20 +9638,35 @@ paths: content: application/json: schema: - "$ref": "#/components/schemas/create_ticket_request" + type: object + required: + - id + - admin_id + properties: + id: + type: string + description: The unique identifier for the tag which is given by + Intercom + example: '7522907' + admin_id: + type: string + description: The unique identifier for the admin which is given + by Intercom. + example: '780' examples: - successful_response: - summary: Successful response + successful: + summary: successful value: - ticket_type_id: 106 - contacts: - - id: 667d61b78a68186f43bafe8d - ticket_attributes: - _default_title_: example - _default_description_: there is a problem - "/tickets/{ticket_id}": - put: - summary: Update a ticket + id: 134 + admin_id: 991267844 + ticket_not_found: + summary: Ticket not found + value: + id: 135 + admin_id: 991267847 + "/tickets/{ticket_id}/tags/{tag_id}": + delete: + summary: Remove tag from a ticket parameters: - name: Intercom-Version in: header @@ -9572,203 +9674,58 @@ paths: "$ref": "#/components/schemas/intercom_version" - name: ticket_id in: path + description: ticket_id + example: '64619700005694' + 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 - description: The unique identifier for the ticket which is given by Intercom schema: type: string tags: + - Tags - Tickets - operationId: updateTicket - description: You can update a ticket. + operationId: detachTagFromTicket + description: You can remove tag from a specific ticket. This will return a tag + object for the tag that was removed from the ticket. responses: '200': - description: Successful response + description: successful content: application/json: examples: - Successful response: + successful: value: - type: ticket - id: '490' - ticket_id: '49' - ticket_attributes: - _default_title_: example - _default_description_: there is a problem - ticket_state: in_progress - ticket_type: - type: ticket_type - id: '108' - name: my-ticket-type-17 - description: my ticket type description is awesome. - icon: "\U0001F981" - workspace_id: this_is_an_id652_that_should_be_at_least_ - archived: false - created_at: 1719493050 - updated_at: 1719493050 - is_internal: false - ticket_type_attributes: - type: list - data: - - type: ticket_type_attribute - id: '257' - workspace_id: this_is_an_id652_that_should_be_at_least_ - name: _default_title_ - description: ola - data_type: string - input_options: - order: 0 - required_to_create: true - required_to_create_for_contacts: false - visible_on_create: true - visible_to_contacts: false - default: false - ticket_type_id: 108 - archived: false - created_at: 1719493050 - updated_at: 1719493050 - - type: ticket_type_attribute - id: '258' - workspace_id: this_is_an_id652_that_should_be_at_least_ - name: _default_description_ - description: ola - data_type: string - input_options: - order: 0 - required_to_create: true - required_to_create_for_contacts: false - visible_on_create: true - visible_to_contacts: false - default: false - ticket_type_id: 108 - archived: false - created_at: 1719493050 - updated_at: 1719493050 - category: Back-office - contacts: - type: contact.list - contacts: - - type: contact - id: 667d61bb8a68186f43bafe8e - external_id: cd63b6b5-ea75-4ad9-b72c-9d7a647baf08 - admin_assignee_id: '991267885' - team_assignee_id: '0' - created_at: 1719493051 - updated_at: 1719493054 - ticket_parts: - type: ticket_part.list - ticket_parts: - - type: ticket_part - id: '126' - part_type: ticket_state_updated_by_admin - ticket_state: submitted - previous_ticket_state: submitted - created_at: 1719493051 - updated_at: 1719493051 - author: - id: '991267883' - type: admin - name: Ciaran419 Lee - email: admin419@email.com - attachments: [] - redacted: false - - type: ticket_part - id: '127' - part_type: ticket_attribute_updated_by_admin - created_at: 1719493053 - updated_at: 1719493053 - author: - id: '991267884' - type: bot - name: Operator - email: operator+this_is_an_id652_that_should_be_at_least_@intercom.io - attachments: [] - redacted: false - - type: ticket_part - id: '128' - part_type: ticket_attribute_updated_by_admin - created_at: 1719493053 - updated_at: 1719493053 - author: - id: '991267884' - type: bot - name: Operator - email: operator+this_is_an_id652_that_should_be_at_least_@intercom.io - attachments: [] - redacted: false - - type: ticket_part - id: '129' - part_type: ticket_state_updated_by_admin - ticket_state: in_progress - previous_ticket_state: submitted - created_at: 1719493053 - updated_at: 1719493053 - author: - id: '991267884' - type: bot - name: Operator - email: operator+this_is_an_id652_that_should_be_at_least_@intercom.io - attachments: [] - redacted: false - - type: ticket_part - id: '130' - part_type: assignment - created_at: 1719493054 - updated_at: 1719493054 - assigned_to: - type: admin - id: '991267885' - author: - id: '991267883' - type: admin - name: Ciaran419 Lee - email: admin419@email.com - attachments: [] - redacted: false - - type: ticket_part - id: '131' - part_type: snoozed - created_at: 1719493054 - updated_at: 1719493054 - author: - id: '991267884' - type: bot - name: Operator - email: operator+this_is_an_id652_that_should_be_at_least_@intercom.io - attachments: [] - redacted: false - total_count: 6 - open: true - snoozed_until: 1719590400 - linked_objects: - type: list - data: [] - total_count: 0 - has_more: false - category: Back-office - is_shared: false - ticket_state_internal_label: In progress - ticket_state_external_label: In progress + type: tag + id: '137' + name: Manual tag schema: - "$ref": "#/components/schemas/ticket" + "$ref": "#/components/schemas/tag" '404': - description: Assignee not found + description: Tag not found content: application/json: examples: - Admin not found: + Ticket not found: value: type: error.list - request_id: 809aceaa-c073-4e2a-96c3-a25e15576946 + request_id: ffa08bb4-3994-4132-b9e3-14837e0723e8 errors: - - code: assignee_not_found - message: Assignee not found - Assignee not found: + - code: ticket_not_found + message: Ticket not found + Tag not found: value: type: error.list - request_id: 639b5b51-1eb9-4c06-8de4-d9b0e30fff05 + request_id: d2385995-502c-4c03-bf4b-93ef3d24037b errors: - - code: assignee_not_found - message: Assignee not found + - code: tag_not_found + message: Tag not found + schema: + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -9777,7 +9734,7 @@ paths: Unauthorized: value: type: error.list - request_id: e5202025-e8f9-400a-9107-192ae8bfd50c + request_id: 0d3be117-0a9e-4e88-9a05-4fdd7f93d7bc errors: - code: unauthorized message: Access Token Invalid @@ -9787,89 +9744,72 @@ paths: content: application/json: schema: - "$ref": "#/components/schemas/update_ticket_request" + type: object + required: + - admin_id + properties: + admin_id: + type: string + description: The unique identifier for the admin which is given + by Intercom. + example: '123' examples: - successful_response: - summary: Successful response + successful: + summary: successful value: - ticket_attributes: - _default_title_: example - _default_description_: there is a problem - state: in_progress - assignment: - admin_id: '991267883' - assignee_id: '991267885' - open: true - snoozed_until: 1673609604 - admin_not_found: - summary: Admin not found + admin_id: 991267853 + ticket_not_found: + summary: Ticket not found value: - ticket_attributes: - _default_title_: example - _default_description_: there is a problem - state: in_progress - assignment: - admin_id: '123' - assignee_id: '991267893' - assignee_not_found: - summary: Assignee not found + admin_id: 991267856 + tag_not_found: + summary: Tag not found value: - ticket_attributes: - _default_title_: example - _default_description_: there is a problem - state: in_progress - assignment: - admin_id: '991267899' - assignee_id: '456' - get: - summary: Retrieve a ticket + admin_id: 991267859 + "/tickets": + post: + summary: Create a ticket parameters: - name: Intercom-Version in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: ticket_id - in: path - required: true - description: The unique identifier for the ticket which is given by Intercom. - schema: - type: string tags: - Tickets - operationId: getTicket - description: You can fetch the details of a single ticket. + description: You can create a new ticket. + operationId: createTicket responses: '200': - description: Ticket found + description: Successful response content: application/json: examples: - Ticket found: + Successful response: value: type: ticket - id: '493' - ticket_id: '52' + id: '489' + ticket_id: '48' ticket_attributes: - _default_title_: attribute_value - _default_description_: + _default_title_: example + _default_description_: there is a problem ticket_state: submitted ticket_type: type: ticket_type - id: '112' - name: my-ticket-type-21 + id: '106' + name: my-ticket-type-15 description: my ticket type description is awesome. icon: "\U0001F981" - workspace_id: this_is_an_id660_that_should_be_at_least_ + workspace_id: this_is_an_id648_that_should_be_at_least_ archived: false - created_at: 1719493060 - updated_at: 1719493060 + created_at: 1719493047 + updated_at: 1719493047 is_internal: false ticket_type_attributes: type: list data: - type: ticket_type_attribute - id: '268' - workspace_id: this_is_an_id660_that_should_be_at_least_ + id: '252' + workspace_id: this_is_an_id648_that_should_be_at_least_ name: _default_title_ description: ola data_type: string @@ -9880,13 +9820,13 @@ paths: visible_on_create: true visible_to_contacts: false default: false - ticket_type_id: 112 + ticket_type_id: 106 archived: false - created_at: 1719493060 - updated_at: 1719493060 + created_at: 1719493047 + updated_at: 1719493047 - type: ticket_type_attribute - id: '269' - workspace_id: this_is_an_id660_that_should_be_at_least_ + id: '253' + workspace_id: this_is_an_id648_that_should_be_at_least_ name: _default_description_ description: ola data_type: string @@ -9897,163 +9837,51 @@ paths: visible_on_create: true visible_to_contacts: false default: false - ticket_type_id: 112 + ticket_type_id: 106 archived: false - created_at: 1719493060 - updated_at: 1719493060 + created_at: 1719493047 + updated_at: 1719493047 category: Back-office contacts: type: contact.list contacts: - type: contact - id: 667d61c48a68186f43bafe91 - external_id: '038050f6-d917-4b9d-89cb-539b1d371172' + id: 667d61b78a68186f43bafe8d + external_id: '70' admin_assignee_id: '0' team_assignee_id: '0' - created_at: 1719493061 - updated_at: 1719493061 - ticket_parts: - type: ticket_part.list - ticket_parts: - - type: ticket_part - id: '134' - part_type: ticket_state_updated_by_admin - ticket_state: submitted - previous_ticket_state: submitted - created_at: 1719493061 - updated_at: 1719493061 - author: - id: '991267912' - type: admin - name: Ciaran445 Lee - email: admin445@email.com - attachments: [] - redacted: false - total_count: 1 - open: true - linked_objects: - type: list - data: [] - total_count: 0 - has_more: false - category: Back-office - is_shared: false - ticket_state_internal_label: Submitted - ticket_state_external_label: Submitted - schema: - "$ref": "#/components/schemas/ticket" - '401': - description: Unauthorized - content: - application/json: - examples: - Unauthorized: - value: - type: error.list - request_id: e7ba89f2-3bc8-4fc3-97bc-56f62f342680 - errors: - - code: unauthorized - message: Access Token Invalid - schema: - "$ref": "#/components/schemas/error" - "/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. - example: "123" - tags: - - Tickets - responses: - '400': - description: User reply - content: - application/json: - examples: - User reply: - value: - type: error.list - request_id: b8b42c55-347c-4704-b4c1-92220c01f4ac - errors: - - code: parameter_mismatch - message: User replies are not allowed on Backoffice tickets - schema: - "$ref": "#/components/schemas/error" - '200': - description: Admin quick_reply reply - content: - application/json: - examples: - Admin note reply: - value: - type: ticket_part - id: '122' - part_type: note - body: |- -

An Unordered HTML List

-
    -
  • Coffee
    • -
  • Tea
    • -
  • Milk
    • -
-

An Ordered HTML List

-
    -
  1. Coffee
    2. -
  2. Tea
    3. -
  3. Milk
    4. -
- created_at: 1719493024 - updated_at: 1719493024 - author: - id: '991267829' - type: admin - name: Ciaran375 Lee - email: admin375@email.com - attachments: [] - redacted: false - Admin quick_reply reply: - value: - type: ticket_part - id: '124' - part_type: quick_reply - created_at: 1719493029 - updated_at: 1719493029 - author: - id: '991267834' - type: admin - name: Ciaran379 Lee - email: admin379@email.com - attachments: [] - redacted: false - schema: - "$ref": "#/components/schemas/ticket_reply" - '404': - description: Not found - content: - application/json: - examples: - Not found: - value: - type: error.list - request_id: c23e8dab-6102-483c-bb1b-c62923be35ab - errors: - - code: not_found - message: Resource Not Found + created_at: 1719493048 + updated_at: 1719493048 + ticket_parts: + type: ticket_part.list + ticket_parts: + - type: ticket_part + id: '125' + part_type: ticket_state_updated_by_admin + ticket_state: submitted + previous_ticket_state: submitted + created_at: 1719493048 + updated_at: 1719493048 + author: + id: '991267871' + type: bot + name: Operator + email: operator+this_is_an_id648_that_should_be_at_least_@intercom.io + attachments: [] + redacted: false + total_count: 1 + open: true + linked_objects: + type: list + data: [] + total_count: 0 + has_more: false + category: Back-office + is_shared: false + ticket_state_internal_label: Submitted + ticket_state_external_label: Submitted schema: - "$ref": "#/components/schemas/error" + "$ref": "#/components/schemas/ticket" '401': description: Unauthorized content: @@ -10062,7 +9890,7 @@ paths: Unauthorized: value: type: error.list - request_id: bb012854-cca8-4fa7-972e-6c38204e8294 + request_id: 745c921a-7c5a-40d4-ab28-6d28a8d2ed47 errors: - code: unauthorized message: Access Token Invalid @@ -10072,48 +9900,20 @@ paths: content: application/json: schema: - oneOf: - - "$ref": "#/components/schemas/contact_reply_ticket_request" - - "$ref": "#/components/schemas/admin_reply_ticket_request" + "$ref": "#/components/schemas/create_ticket_request" examples: - user_reply: - summary: User reply - value: - message_type: comment - type: user - intercom_user_id: 667d619d8a68186f43bafe82 - body: Thanks again :) - admin_note_reply: - summary: Admin note reply - value: - message_type: note - type: admin - admin_id: 991267829 - body: "

An Unordered HTML List

  • Coffee
    • - \
  • Tea
  • Milk

An Ordered HTML List

- \
  1. Coffee
  2. Tea
  3. Milk
- \ " - admin_quick_reply_reply: - summary: Admin quick_reply reply - value: - message_type: quick_reply - type: admin - admin_id: 991267834 - reply_options: - - text: 'Yes' - uuid: 22d6d1f4-1a19-41d0-94c2-e54031f78aca - - text: 'No' - uuid: fbc3dbe0-ec0c-4fb6-826d-e19127191906 - not_found: - summary: Not found + successful_response: + summary: Successful response value: - message_type: comment - type: user - intercom_user_id: 667d61a68a68186f43bafe85 - body: Thanks again :) - "/tickets/{ticket_id}/tags": - post: - summary: Add tag to a ticket + ticket_type_id: 106 + contacts: + - id: 667d61b78a68186f43bafe8d + ticket_attributes: + _default_title_: example + _default_description_: there is a problem + "/tickets/{ticket_id}": + put: + summary: Update a ticket parameters: - name: Intercom-Version in: header @@ -10121,44 +9921,203 @@ paths: "$ref": "#/components/schemas/intercom_version" - name: ticket_id in: path - description: ticket_id - example: '64619700005694' required: true + description: The unique identifier for the ticket which is given by Intercom schema: type: string tags: - - Tags - Tickets - operationId: attachTagToTicket - description: You can tag a specific ticket. This will return a tag object for - the tag that was added to the ticket. + operationId: updateTicket + description: You can update a ticket. responses: '200': - description: successful + description: Successful response content: application/json: examples: - successful: + Successful response: value: - type: tag - id: '134' - name: Manual tag + type: ticket + id: '490' + ticket_id: '49' + ticket_attributes: + _default_title_: example + _default_description_: there is a problem + ticket_state: in_progress + ticket_type: + type: ticket_type + id: '108' + name: my-ticket-type-17 + description: my ticket type description is awesome. + icon: "\U0001F981" + workspace_id: this_is_an_id652_that_should_be_at_least_ + archived: false + created_at: 1719493050 + updated_at: 1719493050 + is_internal: false + ticket_type_attributes: + type: list + data: + - type: ticket_type_attribute + id: '257' + workspace_id: this_is_an_id652_that_should_be_at_least_ + name: _default_title_ + description: ola + data_type: string + input_options: + order: 0 + required_to_create: true + required_to_create_for_contacts: false + visible_on_create: true + visible_to_contacts: false + default: false + ticket_type_id: 108 + archived: false + created_at: 1719493050 + updated_at: 1719493050 + - type: ticket_type_attribute + id: '258' + workspace_id: this_is_an_id652_that_should_be_at_least_ + name: _default_description_ + description: ola + data_type: string + input_options: + order: 0 + required_to_create: true + required_to_create_for_contacts: false + visible_on_create: true + visible_to_contacts: false + default: false + ticket_type_id: 108 + archived: false + created_at: 1719493050 + updated_at: 1719493050 + category: Back-office + contacts: + type: contact.list + contacts: + - type: contact + id: 667d61bb8a68186f43bafe8e + external_id: cd63b6b5-ea75-4ad9-b72c-9d7a647baf08 + admin_assignee_id: '991267885' + team_assignee_id: '0' + created_at: 1719493051 + updated_at: 1719493054 + ticket_parts: + type: ticket_part.list + ticket_parts: + - type: ticket_part + id: '126' + part_type: ticket_state_updated_by_admin + ticket_state: submitted + previous_ticket_state: submitted + created_at: 1719493051 + updated_at: 1719493051 + author: + id: '991267883' + type: admin + name: Ciaran419 Lee + email: admin419@email.com + attachments: [] + redacted: false + - type: ticket_part + id: '127' + part_type: ticket_attribute_updated_by_admin + created_at: 1719493053 + updated_at: 1719493053 + author: + id: '991267884' + type: bot + name: Operator + email: operator+this_is_an_id652_that_should_be_at_least_@intercom.io + attachments: [] + redacted: false + - type: ticket_part + id: '128' + part_type: ticket_attribute_updated_by_admin + created_at: 1719493053 + updated_at: 1719493053 + author: + id: '991267884' + type: bot + name: Operator + email: operator+this_is_an_id652_that_should_be_at_least_@intercom.io + attachments: [] + redacted: false + - type: ticket_part + id: '129' + part_type: ticket_state_updated_by_admin + ticket_state: in_progress + previous_ticket_state: submitted + created_at: 1719493053 + updated_at: 1719493053 + author: + id: '991267884' + type: bot + name: Operator + email: operator+this_is_an_id652_that_should_be_at_least_@intercom.io + attachments: [] + redacted: false + - type: ticket_part + id: '130' + part_type: assignment + created_at: 1719493054 + updated_at: 1719493054 + assigned_to: + type: admin + id: '991267885' + author: + id: '991267883' + type: admin + name: Ciaran419 Lee + email: admin419@email.com + attachments: [] + redacted: false + - type: ticket_part + id: '131' + part_type: snoozed + created_at: 1719493054 + updated_at: 1719493054 + author: + id: '991267884' + type: bot + name: Operator + email: operator+this_is_an_id652_that_should_be_at_least_@intercom.io + attachments: [] + redacted: false + total_count: 6 + open: true + snoozed_until: 1719590400 + linked_objects: + type: list + data: [] + total_count: 0 + has_more: false + category: Back-office + is_shared: false + ticket_state_internal_label: In progress + ticket_state_external_label: In progress schema: - "$ref": "#/components/schemas/tag" + "$ref": "#/components/schemas/ticket" '404': - description: Ticket not found + description: Assignee not found content: application/json: examples: - Ticket not found: + Admin not found: value: type: error.list - request_id: e11d8f55-82fe-4c0d-b4c6-6f22c6a694e9 + request_id: 809aceaa-c073-4e2a-96c3-a25e15576946 errors: - - code: ticket_not_found - message: Ticket not found - schema: - "$ref": "#/components/schemas/error" + - code: assignee_not_found + message: Assignee not found + Assignee not found: + value: + type: error.list + request_id: 639b5b51-1eb9-4c06-8de4-d9b0e30fff05 + errors: + - code: assignee_not_found + message: Assignee not found '401': description: Unauthorized content: @@ -10167,7 +10126,7 @@ paths: Unauthorized: value: type: error.list - request_id: a502f48f-c80d-48fd-bea5-cafe7e24d9f9 + request_id: e5202025-e8f9-400a-9107-192ae8bfd50c errors: - code: unauthorized message: Access Token Invalid @@ -10177,35 +10136,42 @@ paths: content: application/json: schema: - type: object - required: - - id - - admin_id - properties: - id: - type: string - description: The unique identifier for the tag which is given by - Intercom - example: '7522907' - admin_id: - type: string - description: The unique identifier for the admin which is given - by Intercom. - example: '780' + "$ref": "#/components/schemas/update_ticket_request" examples: - successful: - summary: successful + successful_response: + summary: Successful response value: - id: 134 - admin_id: 991267844 - ticket_not_found: - summary: Ticket not found + ticket_attributes: + _default_title_: example + _default_description_: there is a problem + state: in_progress + assignment: + admin_id: '991267883' + assignee_id: '991267885' + open: true + snoozed_until: 1673609604 + admin_not_found: + summary: Admin not found value: - id: 135 - admin_id: 991267847 - "/tickets/{ticket_id}/tags/{tag_id}": - delete: - summary: Remove tag from a ticket + ticket_attributes: + _default_title_: example + _default_description_: there is a problem + state: in_progress + assignment: + admin_id: '123' + assignee_id: '991267893' + assignee_not_found: + summary: Assignee not found + value: + ticket_attributes: + _default_title_: example + _default_description_: there is a problem + state: in_progress + assignment: + admin_id: '991267899' + assignee_id: '456' + get: + summary: Retrieve a ticket parameters: - name: Intercom-Version in: header @@ -10213,58 +10179,118 @@ paths: "$ref": "#/components/schemas/intercom_version" - name: ticket_id in: path - description: ticket_id - example: '64619700005694' - 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 + description: The unique identifier for the ticket which is given by Intercom. schema: type: string tags: - - Tags - Tickets - operationId: detachTagFromTicket - description: You can remove tag from a specific ticket. This will return a tag - object for the tag that was removed from the ticket. + operationId: getTicket + description: You can fetch the details of a single ticket. responses: '200': - description: successful - content: - application/json: - examples: - successful: - value: - type: tag - id: '137' - name: Manual tag - schema: - "$ref": "#/components/schemas/tag" - '404': - description: Tag not found + description: Ticket found content: application/json: examples: - Ticket not found: - value: - type: error.list - request_id: ffa08bb4-3994-4132-b9e3-14837e0723e8 - errors: - - code: ticket_not_found - message: Ticket not found - Tag not found: + Ticket found: value: - type: error.list - request_id: d2385995-502c-4c03-bf4b-93ef3d24037b - errors: - - code: tag_not_found - message: Tag not found + type: ticket + id: '493' + ticket_id: '52' + ticket_attributes: + _default_title_: attribute_value + _default_description_: + ticket_state: submitted + ticket_type: + type: ticket_type + id: '112' + name: my-ticket-type-21 + description: my ticket type description is awesome. + icon: "\U0001F981" + workspace_id: this_is_an_id660_that_should_be_at_least_ + archived: false + created_at: 1719493060 + updated_at: 1719493060 + is_internal: false + ticket_type_attributes: + type: list + data: + - type: ticket_type_attribute + id: '268' + workspace_id: this_is_an_id660_that_should_be_at_least_ + name: _default_title_ + description: ola + data_type: string + input_options: + order: 0 + required_to_create: true + required_to_create_for_contacts: false + visible_on_create: true + visible_to_contacts: false + default: false + ticket_type_id: 112 + archived: false + created_at: 1719493060 + updated_at: 1719493060 + - type: ticket_type_attribute + id: '269' + workspace_id: this_is_an_id660_that_should_be_at_least_ + name: _default_description_ + description: ola + data_type: string + input_options: + order: 0 + required_to_create: true + required_to_create_for_contacts: false + visible_on_create: true + visible_to_contacts: false + default: false + ticket_type_id: 112 + archived: false + created_at: 1719493060 + updated_at: 1719493060 + category: Back-office + contacts: + type: contact.list + contacts: + - type: contact + id: 667d61c48a68186f43bafe91 + external_id: '038050f6-d917-4b9d-89cb-539b1d371172' + admin_assignee_id: '0' + team_assignee_id: '0' + created_at: 1719493061 + updated_at: 1719493061 + ticket_parts: + type: ticket_part.list + ticket_parts: + - type: ticket_part + id: '134' + part_type: ticket_state_updated_by_admin + ticket_state: submitted + previous_ticket_state: submitted + created_at: 1719493061 + updated_at: 1719493061 + author: + id: '991267912' + type: admin + name: Ciaran445 Lee + email: admin445@email.com + attachments: [] + redacted: false + total_count: 1 + open: true + linked_objects: + type: list + data: [] + total_count: 0 + has_more: false + category: Back-office + is_shared: false + ticket_state_internal_label: Submitted + ticket_state_external_label: Submitted schema: - "$ref": "#/components/schemas/error" + "$ref": "#/components/schemas/ticket" '401': description: Unauthorized content: @@ -10273,38 +10299,12 @@ paths: Unauthorized: value: type: error.list - request_id: 0d3be117-0a9e-4e88-9a05-4fdd7f93d7bc + request_id: e7ba89f2-3bc8-4fc3-97bc-56f62f342680 errors: - code: unauthorized message: Access Token Invalid schema: "$ref": "#/components/schemas/error" - requestBody: - content: - application/json: - schema: - type: object - required: - - admin_id - properties: - admin_id: - type: string - description: The unique identifier for the admin which is given - by Intercom. - example: '123' - examples: - successful: - summary: successful - value: - admin_id: 991267853 - ticket_not_found: - summary: Ticket not found - value: - admin_id: 991267856 - tag_not_found: - summary: Tag not found - value: - admin_id: 991267859 "/tickets/search": post: summary: Search tickets