Skip to content

Preview: conversation part type filtering parameters #653

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
robertlangner-fin wants to merge 7 commits into
base: main
Choose a base branch
from
Open

Preview: conversation part type filtering parameters #653

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
6a80a5e
Add conversation part type filtering parameters (Preview)
robertlangner-fin Sep 2, 2026
54a61bf
Describe part type filtering as Preview-only until 2.17
robertlangner-fin Sep 2, 2026
968334a
Type the part type filters as arrays
robertlangner-fin Sep 2, 2026
dbc0259
Document the part type filter vocabulary and its two traps
robertlangner-fin Sep 2, 2026
1e6c494
Document the 422 the part type filters can return
robertlangner-fin Sep 2, 2026
e4e5a29
Say Preview-only without naming a version
robertlangner-fin Sep 3, 2026
d3f05ba
Document the unknown part type and drop the comment bucket wording
robertlangner-fin Sep 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 68 additions & 2 deletions descriptions/0/api.intercom.io.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12340,6 +12340,30 @@ paths:
schema:
type: boolean
default: false
- 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 — a part type this version does not recognise is returned as `unknown`, and `unknown` is not itself an accepted filter value, so those parts are removed by naming the types you do want rather than by filtering them out directly; 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.

@anubhav-intercom anubhav-intercom Sep 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

State that repeated include_part_types parameters are not supported; only one comma-separated value is read.
?include_part_types=comment&include_part_types=note parses to "note" (Rack keeps the last value), so the request succeeds and silently drops comment. Neighbouring /content/search array params say they accept "repeated params"; these do not. Same for exclude_part_types at line 12358.

example: comment,note
schema:
type: array
maxItems: 50

@anubhav-intercom anubhav-intercom Sep 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add minItems: 1 to both parameter schemas.
?include_part_types= returns 422 include_part_types must name at least one conversation part type (intercom#568321 controller diff line 70); the schema currently says an empty array is valid. Same at line 12362.

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 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 — a part type this version does not recognise is returned as `unknown`, and `unknown` is not itself an accepted filter value, so those parts are removed by naming the types you do want rather than by filtering them out directly; 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
maxItems: 50
items:
type: string
style: form
explode: false
tags:
- Conversations
operationId: retrieveConversation
Expand All @@ -12350,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.

@anubhav-intercom anubhav-intercom Sep 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Say that conversation_parts.total_count counts parts after filtering.
total_count is model_parts.count on the filtered relation (versioned_conversation_part_list_response.rb:58; intercom#568321 spec line 470 asserts 1 under a filter). A caller using total_count > 500 to detect truncation, as this admonition invites, gets a post-filter number.

{% /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).
Expand Down Expand Up @@ -12819,6 +12843,48 @@ paths:
message: Active subscription needed.
schema:
"$ref": "#/components/schemas/error"
'422':
description: Invalid part type filter
content:
application/json:
examples:
Unknown part type name:

@anubhav-intercom anubhav-intercom Sep 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add 422 examples for the empty-value and non-string cases.
The controller raises six parameter_invalid messages; this block lists four. Missing: must name at least one conversation part type and must be a comma-separated list of conversation part types (intercom#568321 diff lines 67, 70), both asserted by its specs.

value:
type: error.list
request_id: 1f2e3d4c-5b6a-4798-8c9d-0e1f2a3b4c5d
errors:
- code: parameter_invalid
message: 'Unknown conversation part types: coment'
Filtering on the unknown part type:
value:
type: error.list
request_id: 5d6e7f80-9102-4123-8d4e-5f6a7b8c9d0e
errors:
- code: parameter_invalid
message: 'Unknown conversation part types: unknown'
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:
Expand Down Expand Up @@ -32538,7 +32604,7 @@ components:
example: '3'
part_type:
type: string
description: The type of conversation part.
description: The type of conversation part. On the Preview version a part type the API does not recognise is returned as `unknown`; on earlier versions those parts are returned as `comment`. Every value other than `unknown` is also accepted by the `include_part_types` and `exclude_part_types` query parameters when retrieving a conversation.
example: comment
body:
type: string
Expand Down