Add audience_ids to AI External Pages API (Preview)#516
Open
alexpetrash-code wants to merge 4 commits into
Open
Add audience_ids to AI External Pages API (Preview)#516alexpetrash-code wants to merge 4 commits into
alexpetrash-code wants to merge 4 commits into
Conversation
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) <noreply@anthropic.com>
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).
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.
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) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why?
Customers integrating with the AI External Pages API now need to read and set Fin AI Agent audience targeting on external pages programmatically. The behavior shipped in the monolith over three PRs but the OpenAPI spec has not been updated — generated SDKs and Postman collections do not surface the field, and developer-docs cannot be synced until this lands.
How?
Document
audience_idsas a nullable array of integers on theexternal_pageresponse schema and on both write request schemas. The field is gated by theAddAudienceIdsToExternalPageschange registered inUnstableVersion, so it is Preview-only.Monolith PRs being documented:
External pages have a unique inheritance dimension because they belong to a parent content import source that can carry default audience segments:
audience_idspreserves any defaults inherited from the parent import source. An explicit array overrides those defaults.[]clears all targeting (even when the source has defaults).[]clears; an explicit array replaces.Unknown audience IDs return
404with no partial commit. A companion developer-docs PR with the matching schema additions will follow (changelog entry intentionally deferred — will be folded into a single follow-up PR covering all knowledge content types).sent by alexbot