From 6a80a5e0c2b234c260132269ea5b205d3ca32301 Mon Sep 17 00:00:00 2001 From: robertlangner-fin Date: Wed, 2 Sep 2026 11:13:00 +0100 Subject: [PATCH 1/6] Add conversation part type filtering parameters (Preview) Adds include_part_types and exclude_part_types query parameters to GET /conversations/{id} in the Preview spec, mirroring intercom/intercom#568321. Co-Authored-By: Claude Opus 5 (1M context) --- descriptions/0/api.intercom.io.yaml | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index cd079d8..8b70baa 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -12340,6 +12340,20 @@ paths: schema: type: boolean default: false + - name: include_part_types + in: query + required: false + description: A comma-separated list of conversation part types to include; only parts of these types are returned. Up to 50 values are accepted, and this parameter cannot be combined with `exclude_part_types` (a 422 is returned if both are supplied). The filter is applied before the conversation parts limit, so the newest matching parts are returned. Only supported from API version 2.6 onward; on earlier versions, or if an unknown part type is supplied, a 422 is returned. + example: comment,note + schema: + type: string + - name: exclude_part_types + in: query + required: false + description: A comma-separated list of conversation part types to exclude; parts of these types are omitted from the response. Up to 50 values are accepted, and this parameter cannot be combined with `include_part_types` (a 422 is returned if both are supplied). The filter is applied before the conversation parts limit, so the newest matching parts are returned. Only supported from API version 2.6 onward; on earlier versions, or if an unknown part type is supplied, a 422 is returned. + example: assignment + schema: + type: string tags: - Conversations operationId: retrieveConversation From 54a61bf6f5bed141cc6b93b7609cd588f40f651e Mon Sep 17 00:00:00 2001 From: robertlangner-fin Date: Wed, 2 Sep 2026 15:35:18 +0100 Subject: [PATCH 2/6] Describe part type filtering as Preview-only until 2.17 The filter is gated on a Preview-only version change, not the 2.6 part type change, so it is not available on released versions. Co-Authored-By: Claude Opus 5 (1M context) --- descriptions/0/api.intercom.io.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 8b70baa..5c2993d 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -12343,14 +12343,14 @@ paths: - name: include_part_types in: query required: false - description: A comma-separated list of conversation part types to include; only parts of these types are returned. Up to 50 values are accepted, and this parameter cannot be combined with `exclude_part_types` (a 422 is returned if both are supplied). The filter is applied before the conversation parts limit, so the newest matching parts are returned. Only supported from API version 2.6 onward; on earlier versions, or if an unknown part type is supplied, a 422 is returned. + description: A comma-separated list of conversation part types to include; only parts of these types are returned. Up to 50 values are accepted, and this parameter cannot be combined with `exclude_part_types` (a 422 is returned if both are supplied). The filter is applied before the conversation parts limit, so the newest matching parts are returned. Available on the Preview version until the 2.17 release; on any other version, or if an unknown part type is supplied, a 422 is returned. example: comment,note schema: type: string - name: exclude_part_types in: query required: false - description: A comma-separated list of conversation part types to exclude; parts of these types are omitted from the response. Up to 50 values are accepted, and this parameter cannot be combined with `include_part_types` (a 422 is returned if both are supplied). The filter is applied before the conversation parts limit, so the newest matching parts are returned. Only supported from API version 2.6 onward; on earlier versions, or if an unknown part type is supplied, a 422 is returned. + description: A comma-separated list of conversation part types to exclude; parts of these types are omitted from the response. Up to 50 values are accepted, and this parameter cannot be combined with `include_part_types` (a 422 is returned if both are supplied). The filter is applied before the conversation parts limit, so the newest matching parts are returned. Available on the Preview version until the 2.17 release; on any other version, or if an unknown part type is supplied, a 422 is returned. example: assignment schema: type: string From 968334a9290f2f13dbc3ebeaa928746f9c2ef308 Mon Sep 17 00:00:00 2001 From: robertlangner-fin Date: Wed, 2 Sep 2026 16:32:52 +0100 Subject: [PATCH 3/6] Type the part type filters as arrays Matches the comma-separated query params on /content/search, so generated clients get a list rather than one opaque string. maxItems encodes the 50-value cap the endpoint already enforces. Co-Authored-By: Claude Opus 5 (1M context) --- descriptions/0/api.intercom.io.yaml | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 5c2993d..78d77a8 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -12346,14 +12346,24 @@ paths: description: A comma-separated list of conversation part types to include; only parts of these types are returned. Up to 50 values are accepted, and this parameter cannot be combined with `exclude_part_types` (a 422 is returned if both are supplied). The filter is applied before the conversation parts limit, so the newest matching parts are returned. Available on the Preview version until the 2.17 release; on any other version, or if an unknown part type is supplied, a 422 is returned. example: comment,note schema: - type: string + type: array + maxItems: 50 + items: + type: string + style: form + explode: false - name: exclude_part_types in: query required: false description: A comma-separated list of conversation part types to exclude; parts of these types are omitted from the response. Up to 50 values are accepted, and this parameter cannot be combined with `include_part_types` (a 422 is returned if both are supplied). The filter is applied before the conversation parts limit, so the newest matching parts are returned. Available on the Preview version until the 2.17 release; on any other version, or if an unknown part type is supplied, a 422 is returned. example: assignment schema: - type: string + type: array + maxItems: 50 + items: + type: string + style: form + explode: false tags: - Conversations operationId: retrieveConversation From dbc0259b8071de048448677733a84b10e7cef855 Mon Sep 17 00:00:00 2001 From: robertlangner-fin Date: Wed, 2 Sep 2026 17:36:34 +0100 Subject: [PATCH 4/6] Document the part type filter vocabulary and its two traps The parameters accepted any string with no indication of what the 115 valid names are, and a wrong value is a hard 422. State the rule instead of an enum: the values are the names this version returns in part_type, which stays true as part types are added, since name_to_type_ids derives them from subclass_types rather than a maintained list. Call out the two names that surprise callers. "comment" is the fallback the read path uses for any id it does not recognise, so filtering on it matches a broader set than its name suggests. Type 13 serializes as note_and_unsnooze here but note_and_reopen below 2.6, so a pinned integration moving to Preview hits a 422 on the name it has been receiving. Also point conversation_part.part_type at the filters, since that field is where a caller discovers the vocabulary. Co-Authored-By: Claude Opus 5 (1M context) --- descriptions/0/api.intercom.io.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 78d77a8..0d4cb74 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -12343,7 +12343,7 @@ paths: - name: include_part_types in: query required: false - description: A comma-separated list of conversation part types to include; only parts of these types are returned. Up to 50 values are accepted, and this parameter cannot be combined with `exclude_part_types` (a 422 is returned if both are supplied). The filter is applied before the conversation parts limit, so the newest matching parts are returned. Available on the Preview version until the 2.17 release; on any other version, or if an unknown part type is supplied, a 422 is returned. + description: A comma-separated list of conversation part types to keep; only parts of these types are returned. Values are the names this version returns in a part's `part_type` field, such as `assignment`, `note` or `snoozed`; an unrecognised name returns a 422 rather than being silently ignored, so a typo fails loudly instead of filtering nothing. Two names need care — `comment` matches every part that serializes as `comment`, which includes part types this version does not name individually, and the part type that versions below 2.6 return as `note_and_reopen` is named `note_and_unsnooze` here. Up to 50 values are accepted, and `include_part_types` cannot be combined with `exclude_part_types`; both cases return a 422. The filter is applied before the conversation parts limit, so the newest matching parts are returned. Available on the Preview version until the 2.17 release; a 422 is returned on any other version. example: comment,note schema: type: array @@ -12355,7 +12355,7 @@ paths: - name: exclude_part_types in: query required: false - description: A comma-separated list of conversation part types to exclude; parts of these types are omitted from the response. Up to 50 values are accepted, and this parameter cannot be combined with `include_part_types` (a 422 is returned if both are supplied). The filter is applied before the conversation parts limit, so the newest matching parts are returned. Available on the Preview version until the 2.17 release; on any other version, or if an unknown part type is supplied, a 422 is returned. + description: A comma-separated list of conversation part types to drop; parts of these types are omitted and all others are returned. Values are the names this version returns in a part's `part_type` field, such as `assignment`, `note` or `snoozed`; an unrecognised name returns a 422 rather than being silently ignored, so a typo fails loudly instead of filtering nothing. Two names need care — `comment` matches every part that serializes as `comment`, which includes part types this version does not name individually, and the part type that versions below 2.6 return as `note_and_reopen` is named `note_and_unsnooze` here. Up to 50 values are accepted, and `include_part_types` cannot be combined with `exclude_part_types`; both cases return a 422. The filter is applied before the conversation parts limit, so the newest matching parts are returned. Available on the Preview version until the 2.17 release; a 422 is returned on any other version. example: assignment schema: type: array @@ -32562,7 +32562,7 @@ components: example: '3' part_type: type: string - description: The type of conversation part. + description: The type of conversation part. On the Preview version these are also the values accepted by the `include_part_types` and `exclude_part_types` query parameters when retrieving a conversation. example: comment body: type: string From 1e6c4943a47cfe8663e259ec89c1d2ca2a06fe02 Mon Sep 17 00:00:00 2001 From: robertlangner-fin Date: Wed, 2 Sep 2026 17:47:53 +0100 Subject: [PATCH 5/6] Document the 422 the part type filters can return The parameter descriptions said an invalid filter returns a 422, but the operation only declared 200, 404, 401 and 403, so the generated contract had no shape for the error a caller is most likely to hit. Adds a 422 with the four messages part_type_filter actually raises, all carrying the parameter_invalid code that raise_invalid_param emits, and the shared error schema. Also carries over the conversation parts limit note that only landed in developer-docs, so the source of truth is not missing a sentence its downstream copy has. Co-Authored-By: Claude Opus 5 (1M context) --- descriptions/0/api.intercom.io.yaml | 37 ++++++++++++++++++++++++++++- 1 file changed, 36 insertions(+), 1 deletion(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 0d4cb74..a46fa10 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -12374,7 +12374,7 @@ paths: This will return a single Conversation model with all its conversation parts. {% admonition type="warning" name="Hard limit of 500 parts" %} - The maximum number of conversation parts that can be returned via the API is 500. If you have more than that we will return the 500 most recent conversation parts. + The maximum number of conversation parts that can be returned via the API is 500. If you have more than that we will return the 500 most recent conversation parts. `include_part_types` and `exclude_part_types` are applied before this limit, so filtering returns the 500 most recent matching parts. {% /admonition %} For AI agent conversation metadata, please note that you need to have the agent enabled in your workspace, which is a [paid feature](https://www.intercom.com/help/en/articles/8205718-fin-resolutions#h_97f8c2e671). @@ -12843,6 +12843,41 @@ paths: message: Active subscription needed. schema: "$ref": "#/components/schemas/error" + '422': + description: Invalid part type filter + content: + application/json: + examples: + Unknown part type name: + value: + type: error.list + request_id: 1f2e3d4c-5b6a-4798-8c9d-0e1f2a3b4c5d + errors: + - code: parameter_invalid + message: 'Unknown conversation part types: coment' + Both filters supplied: + value: + type: error.list + request_id: 2a3b4c5d-6e7f-4890-9a1b-2c3d4e5f6a7b + errors: + - code: parameter_invalid + message: include_part_types and exclude_part_types cannot be used together + Too many values: + value: + type: error.list + request_id: 3b4c5d6e-7f80-4901-8b2c-3d4e5f6a7b8c + errors: + - code: parameter_invalid + message: At most 50 conversation part types may be supplied + Unsupported API version: + value: + type: error.list + request_id: 4c5d6e7f-8091-4012-9c3d-4e5f6a7b8c9d + errors: + - code: parameter_invalid + message: include_part_types and exclude_part_types are not supported on this API version + schema: + "$ref": "#/components/schemas/error" put: summary: Update a conversation parameters: From e4e5a29a3cf50507da2036ed61099db9440663eb Mon Sep 17 00:00:00 2001 From: robertlangner-fin Date: Thu, 3 Sep 2026 14:09:32 +0100 Subject: [PATCH 6/6] Say Preview-only without naming a version AddConversationPartTypeFiltering ships with define_is_ready_for_release false, so the 2.17 cut will not pick it up and naming that version would go stale on release day. A version can be named once the change is marked ready. Co-Authored-By: Claude Opus 5 (1M context) --- descriptions/0/api.intercom.io.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index a46fa10..976f4e0 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -12343,7 +12343,7 @@ paths: - name: include_part_types in: query required: false - description: A comma-separated list of conversation part types to keep; only parts of these types are returned. Values are the names this version returns in a part's `part_type` field, such as `assignment`, `note` or `snoozed`; an unrecognised name returns a 422 rather than being silently ignored, so a typo fails loudly instead of filtering nothing. Two names need care — `comment` matches every part that serializes as `comment`, which includes part types this version does not name individually, and the part type that versions below 2.6 return as `note_and_reopen` is named `note_and_unsnooze` here. Up to 50 values are accepted, and `include_part_types` cannot be combined with `exclude_part_types`; both cases return a 422. The filter is applied before the conversation parts limit, so the newest matching parts are returned. Available on the Preview version until the 2.17 release; a 422 is returned on any other version. + description: A comma-separated list of conversation part types to keep; only parts of these types are returned. Values are the names this version returns in a part's `part_type` field, such as `assignment`, `note` or `snoozed`; an unrecognised name returns a 422 rather than being silently ignored, so a typo fails loudly instead of filtering nothing. Two names need care — `comment` matches every part that serializes as `comment`, which includes part types this version does not name individually, and the part type that versions below 2.6 return as `note_and_reopen` is named `note_and_unsnooze` here. Up to 50 values are accepted, and `include_part_types` cannot be combined with `exclude_part_types`; both cases return a 422. The filter is applied before the conversation parts limit, so the newest matching parts are returned. Available on the Preview version; a 422 is returned on any other version. example: comment,note schema: type: array @@ -12355,7 +12355,7 @@ paths: - name: exclude_part_types in: query required: false - description: A comma-separated list of conversation part types to drop; parts of these types are omitted and all others are returned. Values are the names this version returns in a part's `part_type` field, such as `assignment`, `note` or `snoozed`; an unrecognised name returns a 422 rather than being silently ignored, so a typo fails loudly instead of filtering nothing. Two names need care — `comment` matches every part that serializes as `comment`, which includes part types this version does not name individually, and the part type that versions below 2.6 return as `note_and_reopen` is named `note_and_unsnooze` here. Up to 50 values are accepted, and `include_part_types` cannot be combined with `exclude_part_types`; both cases return a 422. The filter is applied before the conversation parts limit, so the newest matching parts are returned. Available on the Preview version until the 2.17 release; a 422 is returned on any other version. + description: A comma-separated list of conversation part types to drop; parts of these types are omitted and all others are returned. Values are the names this version returns in a part's `part_type` field, such as `assignment`, `note` or `snoozed`; an unrecognised name returns a 422 rather than being silently ignored, so a typo fails loudly instead of filtering nothing. Two names need care — `comment` matches every part that serializes as `comment`, which includes part types this version does not name individually, and the part type that versions below 2.6 return as `note_and_reopen` is named `note_and_unsnooze` here. Up to 50 values are accepted, and `include_part_types` cannot be combined with `exclude_part_types`; both cases return a 422. The filter is applied before the conversation parts limit, so the newest matching parts are returned. Available on the Preview version; a 422 is returned on any other version. example: assignment schema: type: array