From 5a098da6659a68bd70077d706b72c9580d0621d3 Mon Sep 17 00:00:00 2001 From: Mark Dennis Date: Thu, 22 Oct 2026 09:50:42 +0100 Subject: [PATCH 1/5] Align the 2.17 News reference with what the API does Switches the lists to page-number paging and documents page and per_page, gives update its own request schema, documents the 400s and 404s the API returns, and adds the accepted OAuth scopes to each operation. Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/2.17/api.intercom.io.yaml | 456 ++++++++++++++++++++++--- 1 file changed, 417 insertions(+), 39 deletions(-) diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index c87a7a84..dd68b7a8 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -20732,10 +20732,33 @@ paths: in: header schema: "$ref": "#/components/schemas/intercom_version" + - name: page + in: query + required: false + description: The page of results to fetch. + schema: + type: integer + default: 1 + example: 1 + - name: per_page + in: query + required: false + description: The number of news items to return per page. Values above 20 are + reduced to 20. + schema: + type: integer + default: 10 + maximum: 20 + example: 10 tags: - News operationId: listNewsItems - description: You can fetch a list of all news items + description: | + You can fetch a list of all news items + + News items are returned newest first, by creation date. + + Requires the `read_news_scope` or `read_write_news_scope` OAuth scope. responses: '200': description: successful @@ -20760,14 +20783,11 @@ paths: state: draft labels: [] cover_image_url: - reactions: - - - - - - - - + reactions: [] deliver_silently: false created_at: 1734537793 updated_at: 1734537793 + published_at: newsfeed_assignments: [] - id: '30' type: news-item @@ -20778,18 +20798,31 @@ paths: state: draft labels: [] cover_image_url: - reactions: - - - - - - - - + reactions: [] deliver_silently: false created_at: 1734537793 updated_at: 1734537793 + published_at: newsfeed_assignments: [] total_count: 2 schema: "$ref": "#/components/schemas/paginated_response" + '400': + description: Bad Request + content: + application/json: + examples: + Per page too small: + value: + type: error.list + request_id: 1d4b6f2a-5c83-4e71-9a0d-2b6e8c47f310 + errors: + - code: parameter_invalid + message: Per Page is too small + schema: + "$ref": "#/components/schemas/error" + '404': + description: News is not enabled on the workspace. The response has no body. '401': description: Unauthorized content: @@ -20802,6 +20835,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 3f7c91e4-6a25-4d8b-b1c3-7e95a2d6048f + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" post: @@ -20814,7 +20854,10 @@ paths: tags: - News operationId: createNewsItem - description: You can create a news item + description: | + You can create a news item + + Requires the `read_write_news_scope` OAuth scope. responses: '200': description: successful @@ -20841,11 +20884,63 @@ paths: deliver_silently: true created_at: 1734537797 updated_at: 1734537797 + published_at: 1734537797 newsfeed_assignments: - newsfeed_id: 53 published_at: 1664638214 schema: "$ref": "#/components/schemas/news_item" + '400': + description: Bad Request + content: + application/json: + examples: + Title missing: + value: + type: error.list + request_id: 5a2e8d16-9b47-4c30-8f6a-1c84e7b59d22 + errors: + - code: parameter_not_found + message: Title is a required parameter + Sender missing: + value: + type: error.list + request_id: 7c93f4b8-2d16-4a59-93e7-6b0d85f1c4a3 + errors: + - code: parameter_not_found + message: sender_id is a required parameter + Invalid cover image URL: + value: + type: error.list + request_id: 9e51a7c2-4f38-4b6d-a27c-85d3f960e1b4 + errors: + - code: parameter_invalid + message: Invalid cover image URL. Must be a valid url of a PNG + or JPG file + Newsfeed does not exist: + value: + type: error.list + request_id: 2b86d053-7e14-49af-8c35-4a71e2d9f806 + errors: + - code: parameter_invalid + message: Newsfeed with id 123 does not exist + schema: + "$ref": "#/components/schemas/error" + '404': + description: Sender not found. If News is not enabled on the workspace the + response has no body. + content: + application/json: + examples: + Sender Not Found: + value: + type: error.list + request_id: 4d19c6e7-8a52-4f03-b67d-93e5017ac2b8 + errors: + - code: not_found + message: Admin not found + schema: + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -20858,6 +20953,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 6f02b3a9-1c74-4d85-ae29-50b7c38d6e14 + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" requestBody: @@ -20902,7 +21004,10 @@ paths: tags: - News operationId: retrieveNewsItem - description: You can fetch the details of a single news item. + description: | + You can fetch the details of a single news item. + + Requires the `read_news_scope` or `read_write_news_scope` OAuth scope. responses: '200': description: successful @@ -20920,21 +21025,19 @@ paths: state: live labels: [] cover_image_url: - reactions: - - - - - - - - + reactions: [] deliver_silently: false created_at: 1734537800 updated_at: 1734537800 + published_at: 1734537800 newsfeed_assignments: - newsfeed_id: 55 published_at: 1734537800 schema: "$ref": "#/components/schemas/news_item" '404': - description: News Item Not Found + description: News Item Not Found. If News is not enabled on the workspace + the response has no body. content: application/json: examples: @@ -20959,6 +21062,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 0c63f8b1-5d27-4e94-82a6-7f91b35ce0d8 + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" put: @@ -20978,6 +21088,14 @@ paths: tags: - News operationId: updateNewsItem + description: | + You can update a news item. + + You can also send this request with `PATCH`; it behaves the same as `PUT`. + + `title`, `body`, `state`, `deliver_silently` and `cover_image_url` keep their current values when you leave them out. `labels` and `newsfeed_assignments` do not: leaving either out clears it, so send the full list on every update. Leaving `reactions` out disables reactions, although the list in the response does not change. + + Requires the `read_write_news_scope` OAuth scope. responses: '200': description: successful @@ -21001,11 +21119,43 @@ paths: deliver_silently: false created_at: 1734537803 updated_at: 1734537804 + published_at: 1734537804 newsfeed_assignments: [] schema: "$ref": "#/components/schemas/news_item" + '400': + description: Bad Request + content: + application/json: + examples: + Invalid cover image URL: + value: + type: error.list + request_id: 1e58a2c9-7f43-4b06-95d1-3c82e67a4f90 + errors: + - code: parameter_invalid + message: Invalid cover image URL. Must be a valid url of a PNG + or JPG file + Invalid state: + value: + type: error.list + request_id: 3a91d7f5-2e68-4c47-b830-6d15f92b8c07 + errors: + - code: parameter_invalid + message: Invalid state. State can either be draft or live + Newsfeed does not exist: + value: + type: error.list + request_id: 5c74e019-4a3b-4d62-8e15-9f07a2c631d4 + errors: + - code: parameter_invalid + message: Newsfeed with id 123 does not exist + schema: + "$ref": "#/components/schemas/error" '404': - description: News Item Not Found + description: News Item Not Found, or the sender was not found. Omitting `sender_id` + also returns this status. If News is not enabled on the workspace the response + has no body. content: application/json: examples: @@ -21016,6 +21166,13 @@ paths: errors: - code: not_found message: Resource Not Found + Sender Not Found: + value: + type: error.list + request_id: 7b20f6a4-6c81-4e39-a05b-2d48e71c9035 + errors: + - code: not_found + message: Admin not found schema: "$ref": "#/components/schemas/error" '401': @@ -21030,13 +21187,20 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 9d36c851-8e05-4a7b-b492-1a63f58d720e + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" requestBody: content: application/json: schema: - "$ref": "#/components/schemas/news_item_request" + "$ref": "#/components/schemas/update_news_item_request" examples: successful: summary: successful @@ -21073,7 +21237,10 @@ paths: tags: - News operationId: deleteNewsItem - description: You can delete a single news item. + description: | + You can delete a single news item. + + Requires the `read_write_news_scope` OAuth scope. responses: '200': description: successful @@ -21088,7 +21255,8 @@ paths: schema: "$ref": "#/components/schemas/deleted_object" '404': - description: News Item Not Found + description: News Item Not Found. If News is not enabled on the workspace + the response has no body. content: application/json: examples: @@ -21113,6 +21281,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 2f85b4d7-0a19-4c63-8e74-5b92d16fa038 + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" "/news/newsfeeds/{newsfeed_id}/items": @@ -21131,11 +21306,33 @@ paths: example: '123' schema: type: string + - name: page + in: query + required: false + description: The page of results to fetch. + schema: + type: integer + default: 1 + example: 1 + - name: per_page + in: query + required: false + description: The number of news items to return per page. Values above 20 are + reduced to 20. + schema: + type: integer + default: 20 + maximum: 20 + example: 20 tags: - News operationId: listLiveNewsfeedItems - description: You can fetch a list of all news items that are live on a given - newsfeed + description: | + You can fetch a list of all news items that are live on a given newsfeed + + News items are returned most recently published first. + + Requires the `read_news_scope` or `read_write_news_scope` OAuth scope. responses: '200': description: successful @@ -21154,6 +21351,35 @@ paths: total_count: 0 schema: "$ref": "#/components/schemas/paginated_response" + '400': + description: Bad Request + content: + application/json: + examples: + Per page too small: + value: + type: error.list + request_id: 4a07e9b3-2c56-4f81-96d0-8e34b15c7d92 + errors: + - code: parameter_invalid + message: Per Page is too small + schema: + "$ref": "#/components/schemas/error" + '404': + description: Newsfeed not found. If News is not enabled on the workspace + the response has no body. + content: + application/json: + examples: + Newsfeed Not Found: + value: + type: error.list + request_id: 6c58d1f0-4e73-4a25-b8c9-0f26a93e5b14 + errors: + - code: not_found + message: Resource Not Found + schema: + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -21166,6 +21392,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 8e71a3c6-6b90-4d48-85f2-3a07c14e9d26 + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" "/news/newsfeeds": @@ -21176,10 +21409,33 @@ paths: in: header schema: "$ref": "#/components/schemas/intercom_version" + - name: page + in: query + required: false + description: The page of results to fetch. + schema: + type: integer + default: 1 + example: 1 + - name: per_page + in: query + required: false + description: The number of newsfeeds to return per page. Values above 20 are + reduced to 20. + schema: + type: integer + default: 10 + maximum: 20 + example: 10 tags: - News operationId: listNewsfeeds - description: You can fetch a list of all newsfeeds + description: | + You can fetch a list of all newsfeeds + + Newsfeeds are returned newest first, by creation date. + + Requires the `read_news_scope` or `read_write_news_scope` OAuth scope. responses: '200': description: successful @@ -21208,6 +21464,22 @@ paths: total_count: 2 schema: "$ref": "#/components/schemas/paginated_response" + '400': + description: Bad Request + content: + application/json: + examples: + Per page too small: + value: + type: error.list + request_id: 0b94f5e2-8d17-4b60-a3c7-5e29d60b847f + errors: + - code: parameter_invalid + message: Per Page is too small + schema: + "$ref": "#/components/schemas/error" + '404': + description: News is not enabled on the workspace. The response has no body. '401': description: Unauthorized content: @@ -21220,6 +21492,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 2d16c7a8-0f34-4e82-9b51-7c40e83f6a95 + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" "/news/newsfeeds/{newsfeed_id}": @@ -21241,7 +21520,10 @@ paths: tags: - News operationId: retrieveNewsfeed - description: You can fetch the details of a single newsfeed + description: | + You can fetch the details of a single newsfeed + + Requires the `read_news_scope` or `read_write_news_scope` OAuth scope. responses: '200': description: successful @@ -21257,6 +21539,21 @@ paths: updated_at: 1734537815 schema: "$ref": "#/components/schemas/newsfeed" + '404': + description: Newsfeed not found. If News is not enabled on the workspace + the response has no body. + content: + application/json: + examples: + Newsfeed Not Found: + value: + type: error.list + request_id: 4f38e9b0-2a51-4c06-83d7-9e62f05a1b48 + errors: + - code: not_found + message: Resource Not Found + schema: + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -21269,6 +21566,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 1a7d35c0-6e82-4b49-9f13-48c0d2e671ba + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" "/notes/{note_id}": @@ -39029,10 +39333,10 @@ components: "$ref": "#/components/schemas/newsfeed_assignment" labels: type: array - description: Label names displayed to users to categorize the news item. + description: Label names displayed to users to categorize the news item, + sorted alphabetically. items: type: string - nullable: true description: The label name. example: Product Update cover_image_url: @@ -39040,6 +39344,9 @@ components: format: uri nullable: true description: URL of the image used as cover. Must have .jpg or .png extension. + Intercom copies the image you send on write, so the URL returned here is + a signed Intercom URL that expires; fetch the news item again for a fresh + one. example: https://example.com/cover.jpg reactions: type: array @@ -39047,7 +39354,6 @@ components: reactions are disabled. items: type: string - nullable: true description: The emoji reaction to the news item. example: "\U0001F44D" deliver_silently: @@ -39113,13 +39419,18 @@ components: - Product - Update - New + cover_image_url: + type: string + format: uri + description: URL of the image to use as the cover. Must end in `.png` or + `.jpg`. Intercom copies the image and serves it from its own signed URL. + example: https://example.com/cover.jpg reactions: type: array - description: Ordered list of emoji reactions to the news item. When empty, - reactions are disabled. + description: Ordered list of emoji reactions to the news item. Send an empty + list to disable reactions. Each entry must be a single character. items: type: string - nullable: true example: - "\U0001F606" - "\U0001F605" @@ -39131,6 +39442,73 @@ components: required: - title - sender_id + update_news_item_request: + description: The body of a request that updates an existing news item. Leaving + `labels` or `newsfeed_assignments` out clears them, and leaving `reactions` + out disables reactions; every other field keeps its current value when left + out. + type: object + title: Update News Item Request + properties: + title: + type: string + description: The title of the news item. + example: Halloween is here! + body: + type: string + description: The news item body, which may contain HTML. + example: "

New costumes in store for this spooky season

" + sender_id: + type: integer + description: The id of the sender of the news item. Must be a teammate on + the workspace. + example: 123 + state: + type: string + description: News items will not be visible to your users in the assigned + newsfeeds until they are set live. + enum: + - draft + - live + example: live + deliver_silently: + type: boolean + description: When set to `true`, the news item will appear in the messenger + newsfeed without showing a notification badge. + example: true + labels: + type: array + description: Label names displayed to users to categorize the news item. + Send the full list; the labels you leave out are removed. + items: + type: string + example: + - Product + - Update + - New + cover_image_url: + type: string + format: uri + description: URL of the image to use as the cover. Must end in `.png` or + `.jpg`. Intercom copies the image and serves it from its own signed URL. + example: https://example.com/cover.jpg + reactions: + type: array + description: Ordered list of emoji reactions to the news item. Send an empty + list to disable reactions. Each entry must be a single character. + items: + type: string + example: + - "\U0001F606" + - "\U0001F605" + newsfeed_assignments: + type: array + description: A list of newsfeed_assignments to assign to the specified newsfeed. + Send the full list; the assignments you leave out are removed. + items: + "$ref": "#/components/schemas/newsfeed_assignment" + required: + - sender_id newsfeed: title: Newsfeed type: object @@ -39154,7 +39532,8 @@ components: name: type: string description: The name of the newsfeed. This name will never be visible to - your users. + your users. Returned HTML-escaped, for example `&` as `&`. The News + Center newsfeed always returns the name `News center newsfeed`. example: My Newsfeed created_at: type: integer @@ -39176,16 +39555,16 @@ components: newsfeed_id: type: integer description: The unique identifier for the newsfeed which is given by Intercom. - Publish dates cannot be in the future, to schedule news items use the - dedicated feature in app (see this article). example: 198313 published_at: type: integer format: timestamp + nullable: true description: Publish date of the news item on the newsfeed, use this field if you want to set a publish date in the past (e.g. when importing existing news items). On write, this field will be ignored if the news item state - is "draft". + is "draft", and a date in the future is rejected with a `400`. Null while + the news item has not gone live on the newsfeed. example: 1674917488 note: title: Note @@ -39325,10 +39704,9 @@ components: description: The type of object enum: - list - - conversation.list example: list pages: - "$ref": "#/components/schemas/cursor_pages" + "$ref": "#/components/schemas/pages_link" total_count: type: integer description: A count of the total number of objects. From a8547c948c598012501865a169f3e86997220f27 Mon Sep 17 00:00:00 2001 From: Mark Dennis Date: Thu, 22 Oct 2026 11:20:42 +0100 Subject: [PATCH 2/5] Say that only optional fields keep their value on a news item update sender_id is required on update, so the request description now limits "keeps its current value when left out" to the optional fields. Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/2.17/api.intercom.io.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index dd68b7a8..5df91a85 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -39445,8 +39445,8 @@ components: update_news_item_request: description: The body of a request that updates an existing news item. Leaving `labels` or `newsfeed_assignments` out clears them, and leaving `reactions` - out disables reactions; every other field keeps its current value when left - out. + out disables reactions; every other optional field keeps its current value + when left out. type: object title: Update News Item Request properties: From 239656253de768f0c8f0c87868656b79f4082f90 Mon Sep 17 00:00:00 2001 From: Mark Dennis Date: Fri, 23 Oct 2026 14:29:47 +0100 Subject: [PATCH 3/5] Port the News changes to Preview Applies the same 2.17 changes to the Preview spec, merged operation by operation so Preview-only content stays, such as the `{id}` path parameter name. The next version is cut from Preview, and the Preview SDKs are generated from it. Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/0/api.intercom.io.yaml | 456 +++++++++++++++++++++++++--- 1 file changed, 417 insertions(+), 39 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 605b1b06..22af87f0 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -22982,10 +22982,33 @@ paths: in: header schema: "$ref": "#/components/schemas/intercom_version" + - name: page + in: query + required: false + description: The page of results to fetch. + schema: + type: integer + default: 1 + example: 1 + - name: per_page + in: query + required: false + description: The number of news items to return per page. Values above 20 are + reduced to 20. + schema: + type: integer + default: 10 + maximum: 20 + example: 10 tags: - News operationId: listNewsItems - description: You can fetch a list of all news items + description: | + You can fetch a list of all news items + + News items are returned newest first, by creation date. + + Requires the `read_news_scope` or `read_write_news_scope` OAuth scope. responses: '200': description: successful @@ -23010,14 +23033,11 @@ paths: state: draft labels: [] cover_image_url: - reactions: - - - - - - - - + reactions: [] deliver_silently: false created_at: 1734537793 updated_at: 1734537793 + published_at: newsfeed_assignments: [] - id: '30' type: news-item @@ -23028,18 +23048,31 @@ paths: state: draft labels: [] cover_image_url: - reactions: - - - - - - - - + reactions: [] deliver_silently: false created_at: 1734537793 updated_at: 1734537793 + published_at: newsfeed_assignments: [] total_count: 2 schema: "$ref": "#/components/schemas/paginated_response" + '400': + description: Bad Request + content: + application/json: + examples: + Per page too small: + value: + type: error.list + request_id: 1d4b6f2a-5c83-4e71-9a0d-2b6e8c47f310 + errors: + - code: parameter_invalid + message: Per Page is too small + schema: + "$ref": "#/components/schemas/error" + '404': + description: News is not enabled on the workspace. The response has no body. '401': description: Unauthorized content: @@ -23052,6 +23085,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 3f7c91e4-6a25-4d8b-b1c3-7e95a2d6048f + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" post: @@ -23064,7 +23104,10 @@ paths: tags: - News operationId: createNewsItem - description: You can create a news item + description: | + You can create a news item + + Requires the `read_write_news_scope` OAuth scope. responses: '200': description: successful @@ -23091,11 +23134,63 @@ paths: deliver_silently: true created_at: 1734537797 updated_at: 1734537797 + published_at: 1734537797 newsfeed_assignments: - newsfeed_id: 53 published_at: 1664638214 schema: "$ref": "#/components/schemas/news_item" + '400': + description: Bad Request + content: + application/json: + examples: + Title missing: + value: + type: error.list + request_id: 5a2e8d16-9b47-4c30-8f6a-1c84e7b59d22 + errors: + - code: parameter_not_found + message: Title is a required parameter + Sender missing: + value: + type: error.list + request_id: 7c93f4b8-2d16-4a59-93e7-6b0d85f1c4a3 + errors: + - code: parameter_not_found + message: sender_id is a required parameter + Invalid cover image URL: + value: + type: error.list + request_id: 9e51a7c2-4f38-4b6d-a27c-85d3f960e1b4 + errors: + - code: parameter_invalid + message: Invalid cover image URL. Must be a valid url of a PNG + or JPG file + Newsfeed does not exist: + value: + type: error.list + request_id: 2b86d053-7e14-49af-8c35-4a71e2d9f806 + errors: + - code: parameter_invalid + message: Newsfeed with id 123 does not exist + schema: + "$ref": "#/components/schemas/error" + '404': + description: Sender not found. If News is not enabled on the workspace the + response has no body. + content: + application/json: + examples: + Sender Not Found: + value: + type: error.list + request_id: 4d19c6e7-8a52-4f03-b67d-93e5017ac2b8 + errors: + - code: not_found + message: Admin not found + schema: + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -23108,6 +23203,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 6f02b3a9-1c74-4d85-ae29-50b7c38d6e14 + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" requestBody: @@ -23152,7 +23254,10 @@ paths: tags: - News operationId: retrieveNewsItem - description: You can fetch the details of a single news item. + description: | + You can fetch the details of a single news item. + + Requires the `read_news_scope` or `read_write_news_scope` OAuth scope. responses: '200': description: successful @@ -23170,21 +23275,19 @@ paths: state: live labels: [] cover_image_url: - reactions: - - - - - - - - + reactions: [] deliver_silently: false created_at: 1734537800 updated_at: 1734537800 + published_at: 1734537800 newsfeed_assignments: - newsfeed_id: 55 published_at: 1734537800 schema: "$ref": "#/components/schemas/news_item" '404': - description: News Item Not Found + description: News Item Not Found. If News is not enabled on the workspace + the response has no body. content: application/json: examples: @@ -23209,6 +23312,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 0c63f8b1-5d27-4e94-82a6-7f91b35ce0d8 + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" put: @@ -23228,6 +23338,14 @@ paths: tags: - News operationId: updateNewsItem + description: | + You can update a news item. + + You can also send this request with `PATCH`; it behaves the same as `PUT`. + + `title`, `body`, `state`, `deliver_silently` and `cover_image_url` keep their current values when you leave them out. `labels` and `newsfeed_assignments` do not: leaving either out clears it, so send the full list on every update. Leaving `reactions` out disables reactions, although the list in the response does not change. + + Requires the `read_write_news_scope` OAuth scope. responses: '200': description: successful @@ -23251,11 +23369,43 @@ paths: deliver_silently: false created_at: 1734537803 updated_at: 1734537804 + published_at: 1734537804 newsfeed_assignments: [] schema: "$ref": "#/components/schemas/news_item" + '400': + description: Bad Request + content: + application/json: + examples: + Invalid cover image URL: + value: + type: error.list + request_id: 1e58a2c9-7f43-4b06-95d1-3c82e67a4f90 + errors: + - code: parameter_invalid + message: Invalid cover image URL. Must be a valid url of a PNG + or JPG file + Invalid state: + value: + type: error.list + request_id: 3a91d7f5-2e68-4c47-b830-6d15f92b8c07 + errors: + - code: parameter_invalid + message: Invalid state. State can either be draft or live + Newsfeed does not exist: + value: + type: error.list + request_id: 5c74e019-4a3b-4d62-8e15-9f07a2c631d4 + errors: + - code: parameter_invalid + message: Newsfeed with id 123 does not exist + schema: + "$ref": "#/components/schemas/error" '404': - description: News Item Not Found + description: News Item Not Found, or the sender was not found. Omitting `sender_id` + also returns this status. If News is not enabled on the workspace the response + has no body. content: application/json: examples: @@ -23266,6 +23416,13 @@ paths: errors: - code: not_found message: Resource Not Found + Sender Not Found: + value: + type: error.list + request_id: 7b20f6a4-6c81-4e39-a05b-2d48e71c9035 + errors: + - code: not_found + message: Admin not found schema: "$ref": "#/components/schemas/error" '401': @@ -23280,13 +23437,20 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 9d36c851-8e05-4a7b-b492-1a63f58d720e + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" requestBody: content: application/json: schema: - "$ref": "#/components/schemas/news_item_request" + "$ref": "#/components/schemas/update_news_item_request" examples: successful: summary: successful @@ -23323,7 +23487,10 @@ paths: tags: - News operationId: deleteNewsItem - description: You can delete a single news item. + description: | + You can delete a single news item. + + Requires the `read_write_news_scope` OAuth scope. responses: '200': description: successful @@ -23338,7 +23505,8 @@ paths: schema: "$ref": "#/components/schemas/deleted_object" '404': - description: News Item Not Found + description: News Item Not Found. If News is not enabled on the workspace + the response has no body. content: application/json: examples: @@ -23363,6 +23531,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 2f85b4d7-0a19-4c63-8e74-5b92d16fa038 + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" "/news/newsfeeds/{id}/items": @@ -23381,11 +23556,33 @@ paths: example: '123' schema: type: string + - name: page + in: query + required: false + description: The page of results to fetch. + schema: + type: integer + default: 1 + example: 1 + - name: per_page + in: query + required: false + description: The number of news items to return per page. Values above 20 are + reduced to 20. + schema: + type: integer + default: 20 + maximum: 20 + example: 20 tags: - News operationId: listLiveNewsfeedItems - description: You can fetch a list of all news items that are live on a given - newsfeed + description: | + You can fetch a list of all news items that are live on a given newsfeed + + News items are returned most recently published first. + + Requires the `read_news_scope` or `read_write_news_scope` OAuth scope. responses: '200': description: successful @@ -23404,6 +23601,35 @@ paths: total_count: 0 schema: "$ref": "#/components/schemas/paginated_response" + '400': + description: Bad Request + content: + application/json: + examples: + Per page too small: + value: + type: error.list + request_id: 4a07e9b3-2c56-4f81-96d0-8e34b15c7d92 + errors: + - code: parameter_invalid + message: Per Page is too small + schema: + "$ref": "#/components/schemas/error" + '404': + description: Newsfeed not found. If News is not enabled on the workspace + the response has no body. + content: + application/json: + examples: + Newsfeed Not Found: + value: + type: error.list + request_id: 6c58d1f0-4e73-4a25-b8c9-0f26a93e5b14 + errors: + - code: not_found + message: Resource Not Found + schema: + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -23416,6 +23642,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 8e71a3c6-6b90-4d48-85f2-3a07c14e9d26 + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" "/news/newsfeeds": @@ -23426,10 +23659,33 @@ paths: in: header schema: "$ref": "#/components/schemas/intercom_version" + - name: page + in: query + required: false + description: The page of results to fetch. + schema: + type: integer + default: 1 + example: 1 + - name: per_page + in: query + required: false + description: The number of newsfeeds to return per page. Values above 20 are + reduced to 20. + schema: + type: integer + default: 10 + maximum: 20 + example: 10 tags: - News operationId: listNewsfeeds - description: You can fetch a list of all newsfeeds + description: | + You can fetch a list of all newsfeeds + + Newsfeeds are returned newest first, by creation date. + + Requires the `read_news_scope` or `read_write_news_scope` OAuth scope. responses: '200': description: successful @@ -23458,6 +23714,22 @@ paths: total_count: 2 schema: "$ref": "#/components/schemas/paginated_response" + '400': + description: Bad Request + content: + application/json: + examples: + Per page too small: + value: + type: error.list + request_id: 0b94f5e2-8d17-4b60-a3c7-5e29d60b847f + errors: + - code: parameter_invalid + message: Per Page is too small + schema: + "$ref": "#/components/schemas/error" + '404': + description: News is not enabled on the workspace. The response has no body. '401': description: Unauthorized content: @@ -23470,6 +23742,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 2d16c7a8-0f34-4e82-9b51-7c40e83f6a95 + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" "/news/newsfeeds/{id}": @@ -23491,7 +23770,10 @@ paths: tags: - News operationId: retrieveNewsfeed - description: You can fetch the details of a single newsfeed + description: | + You can fetch the details of a single newsfeed + + Requires the `read_news_scope` or `read_write_news_scope` OAuth scope. responses: '200': description: successful @@ -23507,6 +23789,21 @@ paths: updated_at: 1734537815 schema: "$ref": "#/components/schemas/newsfeed" + '404': + description: Newsfeed not found. If News is not enabled on the workspace + the response has no body. + content: + application/json: + examples: + Newsfeed Not Found: + value: + type: error.list + request_id: 4f38e9b0-2a51-4c06-83d7-9e62f05a1b48 + errors: + - code: not_found + message: Resource Not Found + schema: + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -23519,6 +23816,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 1a7d35c0-6e82-4b49-9f13-48c0d2e671ba + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" "/notes/{id}": @@ -44270,10 +44574,10 @@ components: "$ref": "#/components/schemas/newsfeed_assignment" labels: type: array - description: Label names displayed to users to categorize the news item. + description: Label names displayed to users to categorize the news item, + sorted alphabetically. items: type: string - nullable: true description: The label name. example: Product Update cover_image_url: @@ -44281,6 +44585,9 @@ components: format: uri nullable: true description: URL of the image used as cover. Must have .jpg or .png extension. + Intercom copies the image you send on write, so the URL returned here is + a signed Intercom URL that expires; fetch the news item again for a fresh + one. example: https://example.com/cover.jpg reactions: type: array @@ -44288,7 +44595,6 @@ components: reactions are disabled. items: type: string - nullable: true description: The emoji reaction to the news item. example: "\U0001F44D" deliver_silently: @@ -44354,13 +44660,18 @@ components: - Product - Update - New + cover_image_url: + type: string + format: uri + description: URL of the image to use as the cover. Must end in `.png` or + `.jpg`. Intercom copies the image and serves it from its own signed URL. + example: https://example.com/cover.jpg reactions: type: array - description: Ordered list of emoji reactions to the news item. When empty, - reactions are disabled. + description: Ordered list of emoji reactions to the news item. Send an empty + list to disable reactions. Each entry must be a single character. items: type: string - nullable: true example: - "\U0001F606" - "\U0001F605" @@ -44372,6 +44683,73 @@ components: required: - title - sender_id + update_news_item_request: + description: The body of a request that updates an existing news item. Leaving + `labels` or `newsfeed_assignments` out clears them, and leaving `reactions` + out disables reactions; every other optional field keeps its current value + when left out. + type: object + title: Update News Item Request + properties: + title: + type: string + description: The title of the news item. + example: Halloween is here! + body: + type: string + description: The news item body, which may contain HTML. + example: "

New costumes in store for this spooky season

" + sender_id: + type: integer + description: The id of the sender of the news item. Must be a teammate on + the workspace. + example: 123 + state: + type: string + description: News items will not be visible to your users in the assigned + newsfeeds until they are set live. + enum: + - draft + - live + example: live + deliver_silently: + type: boolean + description: When set to `true`, the news item will appear in the messenger + newsfeed without showing a notification badge. + example: true + labels: + type: array + description: Label names displayed to users to categorize the news item. + Send the full list; the labels you leave out are removed. + items: + type: string + example: + - Product + - Update + - New + cover_image_url: + type: string + format: uri + description: URL of the image to use as the cover. Must end in `.png` or + `.jpg`. Intercom copies the image and serves it from its own signed URL. + example: https://example.com/cover.jpg + reactions: + type: array + description: Ordered list of emoji reactions to the news item. Send an empty + list to disable reactions. Each entry must be a single character. + items: + type: string + example: + - "\U0001F606" + - "\U0001F605" + newsfeed_assignments: + type: array + description: A list of newsfeed_assignments to assign to the specified newsfeed. + Send the full list; the assignments you leave out are removed. + items: + "$ref": "#/components/schemas/newsfeed_assignment" + required: + - sender_id newsfeed: title: Newsfeed type: object @@ -44395,7 +44773,8 @@ components: name: type: string description: The name of the newsfeed. This name will never be visible to - your users. + your users. Returned HTML-escaped, for example `&` as `&`. The News + Center newsfeed always returns the name `News center newsfeed`. example: My Newsfeed created_at: type: integer @@ -44417,16 +44796,16 @@ components: newsfeed_id: type: integer description: The unique identifier for the newsfeed which is given by Intercom. - Publish dates cannot be in the future, to schedule news items use the - dedicated feature in app (see this article). example: 198313 published_at: type: integer format: timestamp + nullable: true description: Publish date of the news item on the newsfeed, use this field if you want to set a publish date in the past (e.g. when importing existing news items). On write, this field will be ignored if the news item state - is "draft". + is "draft", and a date in the future is rejected with a `400`. Null while + the news item has not gone live on the newsfeed. example: 1674917488 note: title: Note @@ -44749,10 +45128,9 @@ components: description: The type of object enum: - list - - conversation.list example: list pages: - "$ref": "#/components/schemas/cursor_pages" + "$ref": "#/components/schemas/pages_link" total_count: type: integer description: A count of the total number of objects. From 2c57c9a3e0f04bf3f827e1f0bfeb4d845690e60e Mon Sep 17 00:00:00 2001 From: Mark Dennis Date: Fri, 23 Oct 2026 14:57:33 +0100 Subject: [PATCH 4/5] Document the reaction limits, label order and two more news item 400s Reactions accept at most five entries, each a single Unicode code point. Labels sort with uppercase letters first, and newsfeed_assignment.published_at goes back to null when an item returns to draft. Create now shows the invalid-state 400, and create and update show the future published_at 400. Applied to 2.17 and Preview. Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/0/api.intercom.io.yaml | 33 ++++++++++++++++++++++---- descriptions/2.17/api.intercom.io.yaml | 33 ++++++++++++++++++++++---- 2 files changed, 58 insertions(+), 8 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 22af87f0..38d91bff 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -23174,6 +23174,20 @@ paths: errors: - code: parameter_invalid message: Newsfeed with id 123 does not exist + Invalid state: + value: + type: error.list + request_id: 8d40b2f7-3c95-4e18-a6d1-5f27c09e4b83 + errors: + - code: parameter_invalid + message: Invalid state. State can either be draft or live + Published date in the future: + value: + type: error.list + request_id: a3e61c58-7b04-4f92-8d3e-1c69f5b20a47 + errors: + - code: parameter_invalid + message: Invalid published_at 4102444800. Date cannot be in the future. Scheduling is not supported through API schema: "$ref": "#/components/schemas/error" '404': @@ -23400,6 +23414,13 @@ paths: errors: - code: parameter_invalid message: Newsfeed with id 123 does not exist + Published date in the future: + value: + type: error.list + request_id: f27c9d14-5a68-4b3e-90c2-7e81a4d6b359 + errors: + - code: parameter_invalid + message: Invalid published_at 4102444800. Date cannot be in the future. Scheduling is not supported through API schema: "$ref": "#/components/schemas/error" '404': @@ -44575,7 +44596,7 @@ components: labels: type: array description: Label names displayed to users to categorize the news item, - sorted alphabetically. + sorted with uppercase letters before lowercase. items: type: string description: The label name. @@ -44669,7 +44690,9 @@ components: reactions: type: array description: Ordered list of emoji reactions to the news item. Send an empty - list to disable reactions. Each entry must be a single character. + list to disable reactions. Send at most five, each a single Unicode code + point, so an emoji with a skin tone, a joiner sequence or a variation selector + (such as ❤️) is rejected. items: type: string example: @@ -44736,7 +44759,9 @@ components: reactions: type: array description: Ordered list of emoji reactions to the news item. Send an empty - list to disable reactions. Each entry must be a single character. + list to disable reactions. Send at most five, each a single Unicode code + point, so an emoji with a skin tone, a joiner sequence or a variation selector + (such as ❤️) is rejected. items: type: string example: @@ -44805,7 +44830,7 @@ components: if you want to set a publish date in the past (e.g. when importing existing news items). On write, this field will be ignored if the news item state is "draft", and a date in the future is rejected with a `400`. Null while - the news item has not gone live on the newsfeed. + the news item isn't live. example: 1674917488 note: title: Note diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index 5df91a85..3a4126b4 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -20924,6 +20924,20 @@ paths: errors: - code: parameter_invalid message: Newsfeed with id 123 does not exist + Invalid state: + value: + type: error.list + request_id: 8d40b2f7-3c95-4e18-a6d1-5f27c09e4b83 + errors: + - code: parameter_invalid + message: Invalid state. State can either be draft or live + Published date in the future: + value: + type: error.list + request_id: a3e61c58-7b04-4f92-8d3e-1c69f5b20a47 + errors: + - code: parameter_invalid + message: Invalid published_at 4102444800. Date cannot be in the future. Scheduling is not supported through API schema: "$ref": "#/components/schemas/error" '404': @@ -21150,6 +21164,13 @@ paths: errors: - code: parameter_invalid message: Newsfeed with id 123 does not exist + Published date in the future: + value: + type: error.list + request_id: f27c9d14-5a68-4b3e-90c2-7e81a4d6b359 + errors: + - code: parameter_invalid + message: Invalid published_at 4102444800. Date cannot be in the future. Scheduling is not supported through API schema: "$ref": "#/components/schemas/error" '404': @@ -39334,7 +39355,7 @@ components: labels: type: array description: Label names displayed to users to categorize the news item, - sorted alphabetically. + sorted with uppercase letters before lowercase. items: type: string description: The label name. @@ -39428,7 +39449,9 @@ components: reactions: type: array description: Ordered list of emoji reactions to the news item. Send an empty - list to disable reactions. Each entry must be a single character. + list to disable reactions. Send at most five, each a single Unicode code + point, so an emoji with a skin tone, a joiner sequence or a variation selector + (such as ❤️) is rejected. items: type: string example: @@ -39495,7 +39518,9 @@ components: reactions: type: array description: Ordered list of emoji reactions to the news item. Send an empty - list to disable reactions. Each entry must be a single character. + list to disable reactions. Send at most five, each a single Unicode code + point, so an emoji with a skin tone, a joiner sequence or a variation selector + (such as ❤️) is rejected. items: type: string example: @@ -39564,7 +39589,7 @@ components: if you want to set a publish date in the past (e.g. when importing existing news items). On write, this field will be ignored if the news item state is "draft", and a date in the future is rejected with a `400`. Null while - the news item has not gone live on the newsfeed. + the news item isn't live. example: 1674917488 note: title: Note From c4cdb5f6cde43458adf646c566a001eba5401e04 Mon Sep 17 00:00:00 2001 From: Mark Dennis Date: Fri, 23 Oct 2026 16:32:57 +0100 Subject: [PATCH 5/5] Say that a create with too many reactions still saves a draft A create request with more than five reactions returns a 400 after the news item is already saved as a draft, with no reactions or cover image. The cover image check matches `.png` or `.jpg` anywhere in the URL and is case-sensitive, so the description now says "contain" and names the rejected `.jpeg` and `.PNG`. The response's reactions list also says that an update leaving out `reactions` disables them without clearing the list. Applied to 2.17 and Preview. Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/0/api.intercom.io.yaml | 16 ++++++++++------ descriptions/2.17/api.intercom.io.yaml | 16 ++++++++++------ 2 files changed, 20 insertions(+), 12 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 38d91bff..17c7396d 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -44613,7 +44613,8 @@ components: reactions: type: array description: Ordered list of emoji reactions to the news item. When empty, - reactions are disabled. + reactions are disabled. An update that leaves out `reactions` also disables + them but leaves this list as it was. items: type: string description: The emoji reaction to the news item. @@ -44684,15 +44685,17 @@ components: cover_image_url: type: string format: uri - description: URL of the image to use as the cover. Must end in `.png` or - `.jpg`. Intercom copies the image and serves it from its own signed URL. + description: URL of the image to use as the cover. Must contain `.png` or + `.jpg` in lower case, so `.jpeg` and `.PNG` are rejected. Intercom copies + the image and serves it from its own signed URL. example: https://example.com/cover.jpg reactions: type: array description: Ordered list of emoji reactions to the news item. Send an empty list to disable reactions. Send at most five, each a single Unicode code point, so an emoji with a skin tone, a joiner sequence or a variation selector - (such as ❤️) is rejected. + (such as ❤️) is rejected. More than five returns a 400, but the news item + is still saved as a draft, with no reactions or cover image. items: type: string example: @@ -44753,8 +44756,9 @@ components: cover_image_url: type: string format: uri - description: URL of the image to use as the cover. Must end in `.png` or - `.jpg`. Intercom copies the image and serves it from its own signed URL. + description: URL of the image to use as the cover. Must contain `.png` or + `.jpg` in lower case, so `.jpeg` and `.PNG` are rejected. Intercom copies + the image and serves it from its own signed URL. example: https://example.com/cover.jpg reactions: type: array diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index 3a4126b4..fef3dd57 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -39372,7 +39372,8 @@ components: reactions: type: array description: Ordered list of emoji reactions to the news item. When empty, - reactions are disabled. + reactions are disabled. An update that leaves out `reactions` also disables + them but leaves this list as it was. items: type: string description: The emoji reaction to the news item. @@ -39443,15 +39444,17 @@ components: cover_image_url: type: string format: uri - description: URL of the image to use as the cover. Must end in `.png` or - `.jpg`. Intercom copies the image and serves it from its own signed URL. + description: URL of the image to use as the cover. Must contain `.png` or + `.jpg` in lower case, so `.jpeg` and `.PNG` are rejected. Intercom copies + the image and serves it from its own signed URL. example: https://example.com/cover.jpg reactions: type: array description: Ordered list of emoji reactions to the news item. Send an empty list to disable reactions. Send at most five, each a single Unicode code point, so an emoji with a skin tone, a joiner sequence or a variation selector - (such as ❤️) is rejected. + (such as ❤️) is rejected. More than five returns a 400, but the news item + is still saved as a draft, with no reactions or cover image. items: type: string example: @@ -39512,8 +39515,9 @@ components: cover_image_url: type: string format: uri - description: URL of the image to use as the cover. Must end in `.png` or - `.jpg`. Intercom copies the image and serves it from its own signed URL. + description: URL of the image to use as the cover. Must contain `.png` or + `.jpg` in lower case, so `.jpeg` and `.PNG` are rejected. Intercom copies + the image and serves it from its own signed URL. example: https://example.com/cover.jpg reactions: type: array