From c1133899ba45d61900c99a6c43764eb8f92438e1 Mon Sep 17 00:00:00 2001 From: alexpetrash-code Date: Fri, 22 May 2026 15:40:06 +0100 Subject: [PATCH 1/4] Add audience_ids to AI External Pages API (Preview) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Documents the audience_ids field added to the AI External Pages API in: - intercom/intercom#512971 (GET — read support) - intercom/intercom#513583 (POST — write support on create/upsert) - intercom/intercom#513451 (PUT — write support on update) Adds the field to: - external_page schema (response) - create_external_page_request - update_external_page_request POST has special inheritance semantics: omitting audience_ids preserves defaults inherited from the parent content_import_source; an explicit array overrides them; [] clears all targeting. PUT uses PATCH semantics matching the other knowledge-API write endpoints. Gated by the AddAudienceIdsToExternalPages version change in UnstableVersion (Preview-only). Co-Authored-By: Claude Sonnet 4.6 (1M context) --- descriptions/0/api.intercom.io.yaml | 38 +++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index bd352a1..eaeb79b 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -23839,6 +23839,20 @@ components: description: The identifier for the external page which was given by the source. Must be unique for the source. example: '5678' + audience_ids: + type: array + nullable: true + description: >- + The list of audience IDs to target this external page to for Fin AI Agent. + Omitting the field preserves any default audience segments inherited from the parent content import source. + Pass an explicit array to override inherited defaults with the given set. + Pass `[]` to clear all audience memberships (even if the source has defaults). + Unknown audience IDs return a `404` error with no partial commit. + items: + type: integer + example: + - 1 + - 2 required: - title - html @@ -26483,6 +26497,17 @@ components: format: date-time description: The time when the external page was last ingested. example: 1672928610 + audience_ids: + type: array + nullable: true + description: >- + The list of audience IDs this external page is targeted to for Fin AI Agent. + Empty array means no audience targeting is set. + items: + type: integer + example: + - 1 + - 2 required: - id - type @@ -30038,6 +30063,19 @@ components: description: The identifier for the external page which was given by the source. Must be unique for the source. example: '5678' + audience_ids: + type: array + nullable: true + description: >- + The list of audience IDs to target this external page to for Fin AI Agent. + Omitting the field leaves existing audience memberships unchanged (PATCH semantics). + Pass `[]` to clear all audience memberships. + Unknown audience IDs return a `404` error with no partial commit. + items: + type: integer + example: + - 1 + - 2 required: - title - html From a41ebe74e98b425bd338ef57ad509558078de171 Mon Sep 17 00:00:00 2001 From: alexpetrash-code Date: Fri, 22 May 2026 16:43:16 +0100 Subject: [PATCH 2/4] Address review: add 404 response + audience_ids inline examples Mirrors the fixes applied to the developer-docs companion PR intercom/developer-docs#930. Per Redocly bot + Ivan's review pattern on the sibling PRs: 1. Add `audience_ids: [1, 2]` to inline examples on listExternalPages, createExternalPage (request + response), getExternalPage, updateExternalPage (request + response). 2. Add a 404 response to POST /ai/external_pages for the new "unknown audience IDs" error case (returns invalid_parameter code). 3. Add a 404 response to PUT /ai/external_pages/{id} for the same case (this endpoint had no 404 documented previously). --- descriptions/0/api.intercom.io.yaml | 44 +++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index eaeb79b..0559427 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -916,6 +916,9 @@ paths: created_at: 1734537269 updated_at: 1734537269 last_ingested_at: 1734537269 + audience_ids: + - 1 + - 2 - id: '18' type: external_page title: My External Content @@ -1002,6 +1005,9 @@ paths: created_at: 1734537273 updated_at: 1734537274 last_ingested_at: 1734537274 + audience_ids: + - 1 + - 2 schema: "$ref": "#/components/schemas/external_page" '401': @@ -1018,6 +1024,19 @@ paths: message: Access Token Invalid schema: "$ref": "#/components/schemas/error" + '404': + description: Unknown audience IDs + content: + application/json: + examples: + Unknown audience IDs: + value: + type: error.list + errors: + - code: invalid_parameter + message: 'audience_ids contains unknown audience IDs: 999' + schema: + "$ref": "#/components/schemas/error" requestBody: content: application/json: @@ -1033,6 +1052,9 @@ paths: source_id: 44 title: Test url: https://www.example.com + audience_ids: + - 1 + - 2 "/ai/external_pages/{id}": parameters: - name: id @@ -1124,6 +1146,9 @@ paths: created_at: 1734537278 updated_at: 1734537278 last_ingested_at: 1734537278 + audience_ids: + - 1 + - 2 schema: "$ref": "#/components/schemas/external_page" '401': @@ -1174,6 +1199,9 @@ paths: created_at: 1734537280 updated_at: 1734537281 last_ingested_at: 1734537281 + audience_ids: + - 1 + - 2 schema: "$ref": "#/components/schemas/external_page" '401': @@ -1190,6 +1218,19 @@ paths: message: Access Token Invalid schema: "$ref": "#/components/schemas/error" + '404': + description: Unknown audience IDs + content: + application/json: + examples: + Unknown audience IDs: + value: + type: error.list + errors: + - code: invalid_parameter + message: 'audience_ids contains unknown audience IDs: 999' + schema: + "$ref": "#/components/schemas/error" requestBody: content: application/json: @@ -1205,6 +1246,9 @@ paths: source_id: 47 title: Test url: https://www.example.com + audience_ids: + - 1 + - 2 "/articles": get: summary: List all articles From 62284e6bfaebf197d5c7aee86e1a82d78c4674db Mon Sep 17 00:00:00 2001 From: alexpetrash-code Date: Fri, 22 May 2026 17:06:39 +0100 Subject: [PATCH 3/4] Fix error code in audience_ids 404 examples The Ruby constant `Api::V3::Errors::Code::INVALID_PARAMETER` maps to the string `'parameter_invalid'`, not `'invalid_parameter'`. The serializer in error_handler.rb#error_to_hash renders the constant's value as the JSON `code` field, so the actual API response is: code: parameter_invalid not `invalid_parameter` as previously documented. HTTP 404 status was correct; only the code string was wrong. --- 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 0559427..056e914 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -1033,7 +1033,7 @@ paths: value: type: error.list errors: - - code: invalid_parameter + - code: parameter_invalid message: 'audience_ids contains unknown audience IDs: 999' schema: "$ref": "#/components/schemas/error" @@ -1227,7 +1227,7 @@ paths: value: type: error.list errors: - - code: invalid_parameter + - code: parameter_invalid message: 'audience_ids contains unknown audience IDs: 999' schema: "$ref": "#/components/schemas/error" From 3a1048b99c8758cf01613fa4a20a5d11ae2b9bd0 Mon Sep 17 00:00:00 2001 From: alexpetrash-code Date: Fri, 22 May 2026 17:18:43 +0100 Subject: [PATCH 4/4] Add audience_ids to deleteExternalPage response example DELETE returns the full external_page schema, so the inline response example should mirror the new audience_ids field. Co-Authored-By: Claude Sonnet 4.6 (1M context) --- descriptions/0/api.intercom.io.yaml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 056e914..298a029 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -1097,6 +1097,9 @@ paths: created_at: 1734537276 updated_at: 1734537276 last_ingested_at: 1734537276 + audience_ids: + - 1 + - 2 schema: "$ref": "#/components/schemas/external_page" '401':