diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index cd079d84..51832079 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -12340,6 +12340,32 @@ 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. Supply one comma-separated value; repeating the parameter is not read as a combined list, and only the last occurrence is used. 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 + minItems: 1 + 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 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. Supply one comma-separated value; repeating the parameter is not read as a combined list, and only the last occurrence is used. 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 + minItems: 1 + maxItems: 50 + items: + type: string + style: form + explode: false tags: - Conversations operationId: retrieveConversation @@ -12350,7 +12376,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. `conversation_parts.total_count` counts the parts in this response, after filtering — it is not the conversation's total part count. {% /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). @@ -12819,6 +12845,62 @@ 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' + 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 + Empty filter value: + value: + type: error.list + request_id: 6e7f8091-0213-4234-9e5f-6a7b8c9d0e1f + errors: + - code: parameter_invalid + message: include_part_types must name at least one conversation part type + Non-string filter value: + value: + type: error.list + request_id: 7f809102-1324-4345-8f6a-7b8c9d0e1f2a + errors: + - code: parameter_invalid + message: include_part_types must be a comma-separated list of conversation part types + 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: @@ -32538,7 +32620,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 @@ -32711,7 +32793,9 @@ components: "$ref": "#/components/schemas/conversation_part" total_count: type: integer - description: '' + description: A count of the conversation parts in this response, after any + `include_part_types` or `exclude_part_types` filter has been applied. This + is not the conversation's total part count. example: 1 conversation_part_metadata: title: Conversation Part Metadata