From 9c3ef04c9712d7f139db759545eb6b51dc194821 Mon Sep 17 00:00:00 2001 From: yasser-aboelgheit-intercom Date: Wed, 30 Sep 2026 11:52:08 +0100 Subject: [PATCH 1/4] Document translated admin reply topics and translations field in 2.16 Mirrors what Preview PRs #621, #638, #654 and #668 added into the 2.16 spec, matching the promotion in intercom/intercom#585326. Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/2.16/api.intercom.io.yaml | 96 ++++++++++++++++++++++++++ 1 file changed, 96 insertions(+) diff --git a/descriptions/2.16/api.intercom.io.yaml b/descriptions/2.16/api.intercom.io.yaml index be524405..9acc99d4 100644 --- a/descriptions/2.16/api.intercom.io.yaml +++ b/descriptions/2.16/api.intercom.io.yaml @@ -11784,6 +11784,10 @@ paths: name: Test tag event_details: app_package_code: null + translations: + original: en + en:

Okay!

+ fr: "

D'accord!

" - type: conversation_part id: 2 part_type: custom_action_started @@ -20242,6 +20246,26 @@ paths: content: application/json: examples: + Admin reply: + value: + type: ticket_part + id: '155' + part_type: comment + body: "

Thanks for reaching out, we're looking into it!

" + created_at: 1734537880 + updated_at: 1734537880 + author: + id: '991267940' + type: admin + name: Ciaran418 Lee + email: admin418@email.com + attachments: [] + redacted: false + app_package_code: test-integration + translations: + original: en + en: "

Thanks for reaching out, we're looking into it!

" + fr: "

Merci de nous avoir contactés, nous nous en occupons !

" Admin note reply: value: type: ticket_part @@ -28052,6 +28076,30 @@ components: nullable: true example: "test-integration" description: The app package code if this part was created via API. null if the part was not created via API. + translations: + type: object + nullable: true + description: >- + A map of the reply text keyed by locale code. Backs the + `conversation.admin.replied.translated` webhook topic. The special `original` key holds the source locale code + of the reply; every other key is a locale code whose value is the reply + text translated into that locale, as HTML in the same format as `body`. + The `body` field is unchanged and always + stays in the original source language. Available from API version 2.16 + (set `Intercom-Version: 2.16`). This webhook topic is not sent for + every translated reply: it is suppressed when the reply's `body` contains + any text outside an HTML block element, which includes plain-text replies + created through the REST API. + Wrap the body in `

`, `

`, or another supported block element to + avoid this. + required: + - original + additionalProperties: + type: string + example: + original: en + en:

Hello

+ fr:

Bonjour

conversation_part_author: title: Conversation part author type: object @@ -34740,6 +34788,30 @@ components: nullable: false example: text-integration description: The app package code if this part was created via API. Note this field won't show if the part was not created via API. + translations: + type: object + nullable: true + description: >- + A map of the reply text keyed by locale code. Backs the + `ticket.admin.replied.translated` webhook topic. The special `original` key holds the source locale code + of the reply; every other key is a locale code whose value is the reply + text translated into that locale, as HTML in the same format as `body`. + The `body` field is unchanged and always + stays in the original source language. Available from API version 2.16 + (set `Intercom-Version: 2.16`). This webhook topic is not sent for + every translated reply: it is suppressed when the reply's `body` contains + any text outside an HTML block element, which includes plain-text replies + created through the REST API. + Wrap the body in `

`, `

`, or another supported block element to + avoid this. + required: + - original + additionalProperties: + type: string + example: + original: en + en:

Hello

+ fr:

Bonjour

updated_attribute_data: title: Updated Attribute type: object @@ -34909,6 +34981,30 @@ components: type: boolean description: Whether or not the ticket part has been redacted. example: false + translations: + type: object + nullable: true + description: >- + A map of the reply text keyed by locale code. Backs the + `ticket.admin.replied.translated` webhook topic. The special `original` key holds the source locale code + of the reply; every other key is a locale code whose value is the reply + text translated into that locale, as HTML in the same format as `body`. + The `body` field is unchanged and always + stays in the original source language. Available from API version 2.16 + (set `Intercom-Version: 2.16`). This webhook topic is not sent for + every translated reply: it is suppressed when the reply's `body` contains + any text outside an HTML block element, which includes plain-text replies + created through the REST API. + Wrap the body in `

`, `

`, or another supported block element to + avoid this. + required: + - original + additionalProperties: + type: string + example: + original: en + en:

Hello

+ fr:

Bonjour

ticket_request_custom_attributes: title: Ticket Attributes type: object From 3b9d71a9f814b24c985fbea8b41c1b5751cb631a Mon Sep 17 00:00:00 2001 From: yasser-aboelgheit-intercom Date: Wed, 30 Sep 2026 12:08:42 +0100 Subject: [PATCH 2/4] Match the 2.16 translations examples to developer-docs Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/2.16/api.intercom.io.yaml | 102 ++++++++++++++----------- 1 file changed, 59 insertions(+), 43 deletions(-) diff --git a/descriptions/2.16/api.intercom.io.yaml b/descriptions/2.16/api.intercom.io.yaml index 9acc99d4..43ee5286 100644 --- a/descriptions/2.16/api.intercom.io.yaml +++ b/descriptions/2.16/api.intercom.io.yaml @@ -11786,8 +11786,8 @@ paths: app_package_code: null translations: original: en - en:

Okay!

- fr: "

D'accord!

" + en: '

Okay!

' + es: '

¡Vale!

' - type: conversation_part id: 2 part_type: custom_action_started @@ -13050,6 +13050,10 @@ paths: metadata: {} email_message_metadata: app_package_code: null + translations: + original: en + en: '

Goodbye :)

' + es: '

¡Adiós! :)

' total_count: 1 Snooze a conversation: value: @@ -20264,8 +20268,8 @@ paths: app_package_code: test-integration translations: original: en - en: "

Thanks for reaching out, we're looking into it!

" - fr: "

Merci de nous avoir contactés, nous nous en occupons !

" + en: '

Thanks for reaching out, we''re looking into it!

' + fr: '

Merci de nous avoir contactés, nous nous en occupons !

' Admin note reply: value: type: ticket_part @@ -28080,26 +28084,30 @@ components: type: object nullable: true description: >- - A map of the reply text keyed by locale code. Backs the - `conversation.admin.replied.translated` webhook topic. The special `original` key holds the source locale code + A map of the reply text keyed by locale code, with values in the + same HTML format as `body`. Backs the `conversation.admin.replied.translated` + webhook topic. The special `original` key holds the source locale code of the reply; every other key is a locale code whose value is the reply - text translated into that locale, as HTML in the same format as `body`. - The `body` field is unchanged and always - stays in the original source language. Available from API version 2.16 - (set `Intercom-Version: 2.16`). This webhook topic is not sent for - every translated reply: it is suppressed when the reply's `body` contains - any text outside an HTML block element, which includes plain-text replies - created through the REST API. + text translated into that locale. The `translations` field does not modify + `body`; `body` carries the reply as authored. + This webhook topic is not sent for every translated reply: it is + suppressed when the reply's `body` contains any text outside an HTML block + element, which includes plain-text replies created through the REST API. Wrap the body in `

`, `

`, or another supported block element to avoid this. - required: - - original + properties: + original: + type: string + description: The locale code identifying the language the reply was originally written in. + example: en additionalProperties: type: string + required: + - original example: original: en - en:

Hello

- fr:

Bonjour

+ en: '

Hello

' + fr: '

Bonjour

' conversation_part_author: title: Conversation part author type: object @@ -34792,26 +34800,30 @@ components: type: object nullable: true description: >- - A map of the reply text keyed by locale code. Backs the - `ticket.admin.replied.translated` webhook topic. The special `original` key holds the source locale code + A map of the reply text keyed by locale code, with values in the + same HTML format as `body`. Backs the `ticket.admin.replied.translated` + webhook topic. The special `original` key holds the source locale code of the reply; every other key is a locale code whose value is the reply - text translated into that locale, as HTML in the same format as `body`. - The `body` field is unchanged and always - stays in the original source language. Available from API version 2.16 - (set `Intercom-Version: 2.16`). This webhook topic is not sent for - every translated reply: it is suppressed when the reply's `body` contains - any text outside an HTML block element, which includes plain-text replies - created through the REST API. + text translated into that locale. The `translations` field does not modify + `body`; `body` carries the reply as authored. + This webhook topic is not sent for every translated reply: it is + suppressed when the reply's `body` contains any text outside an HTML block + element, which includes plain-text replies created through the REST API. Wrap the body in `

`, `

`, or another supported block element to avoid this. - required: - - original + properties: + original: + type: string + description: The locale code identifying the language the reply was originally written in. + example: en additionalProperties: type: string + required: + - original example: original: en - en:

Hello

- fr:

Bonjour

+ en: '

Hello

' + fr: '

Bonjour

' updated_attribute_data: title: Updated Attribute type: object @@ -34985,26 +34997,30 @@ components: type: object nullable: true description: >- - A map of the reply text keyed by locale code. Backs the - `ticket.admin.replied.translated` webhook topic. The special `original` key holds the source locale code + A map of the reply text keyed by locale code, with values in the + same HTML format as `body`. Backs the `ticket.admin.replied.translated` + webhook topic. The special `original` key holds the source locale code of the reply; every other key is a locale code whose value is the reply - text translated into that locale, as HTML in the same format as `body`. - The `body` field is unchanged and always - stays in the original source language. Available from API version 2.16 - (set `Intercom-Version: 2.16`). This webhook topic is not sent for - every translated reply: it is suppressed when the reply's `body` contains - any text outside an HTML block element, which includes plain-text replies - created through the REST API. + text translated into that locale. The `translations` field does not modify + `body`; `body` carries the reply as authored. + This webhook topic is not sent for every translated reply: it is + suppressed when the reply's `body` contains any text outside an HTML block + element, which includes plain-text replies created through the REST API. Wrap the body in `

`, `

`, or another supported block element to avoid this. - required: - - original + properties: + original: + type: string + description: The locale code identifying the language the reply was originally written in. + example: en additionalProperties: type: string + required: + - original example: original: en - en:

Hello

- fr:

Bonjour

+ en: '

Hello

' + fr: '

Bonjour

' ticket_request_custom_attributes: title: Ticket Attributes type: object From 15e866fbf029f05738735430d837da19c068930f Mon Sep 17 00:00:00 2001 From: yasser aboelgheit Date: Wed, 30 Sep 2026 16:46:03 +0100 Subject: [PATCH 3/4] Shorten the 2.16 translations descriptions Limits them to what the field contains and drops the body sentence, which is wrong when a conversation is retrieved with include_translations=true. Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/2.16/api.intercom.io.yaml | 45 +++++++------------------- 1 file changed, 12 insertions(+), 33 deletions(-) diff --git a/descriptions/2.16/api.intercom.io.yaml b/descriptions/2.16/api.intercom.io.yaml index 43ee5286..f4ba9929 100644 --- a/descriptions/2.16/api.intercom.io.yaml +++ b/descriptions/2.16/api.intercom.io.yaml @@ -28084,17 +28084,10 @@ components: type: object nullable: true description: >- - A map of the reply text keyed by locale code, with values in the - same HTML format as `body`. Backs the `conversation.admin.replied.translated` - webhook topic. The special `original` key holds the source locale code - of the reply; every other key is a locale code whose value is the reply - text translated into that locale. The `translations` field does not modify - `body`; `body` carries the reply as authored. - This webhook topic is not sent for every translated reply: it is - suppressed when the reply's `body` contains any text outside an HTML block - element, which includes plain-text replies created through the REST API. - Wrap the body in `

`, `

`, or another supported block element to - avoid this. + A map of the reply text keyed by locale code. Backs the + `conversation.admin.replied.translated` webhook topic. `original` holds + the locale code the reply was written in; every other key holds the + reply translated into that locale. properties: original: type: string @@ -34800,17 +34793,10 @@ components: type: object nullable: true description: >- - A map of the reply text keyed by locale code, with values in the - same HTML format as `body`. Backs the `ticket.admin.replied.translated` - webhook topic. The special `original` key holds the source locale code - of the reply; every other key is a locale code whose value is the reply - text translated into that locale. The `translations` field does not modify - `body`; `body` carries the reply as authored. - This webhook topic is not sent for every translated reply: it is - suppressed when the reply's `body` contains any text outside an HTML block - element, which includes plain-text replies created through the REST API. - Wrap the body in `

`, `

`, or another supported block element to - avoid this. + A map of the reply text keyed by locale code. Backs the + `ticket.admin.replied.translated` webhook topic. `original` holds + the locale code the reply was written in; every other key holds the + reply translated into that locale. properties: original: type: string @@ -34997,17 +34983,10 @@ components: type: object nullable: true description: >- - A map of the reply text keyed by locale code, with values in the - same HTML format as `body`. Backs the `ticket.admin.replied.translated` - webhook topic. The special `original` key holds the source locale code - of the reply; every other key is a locale code whose value is the reply - text translated into that locale. The `translations` field does not modify - `body`; `body` carries the reply as authored. - This webhook topic is not sent for every translated reply: it is - suppressed when the reply's `body` contains any text outside an HTML block - element, which includes plain-text replies created through the REST API. - Wrap the body in `

`, `

`, or another supported block element to - avoid this. + A map of the reply text keyed by locale code. Backs the + `ticket.admin.replied.translated` webhook topic. `original` holds + the locale code the reply was written in; every other key holds the + reply translated into that locale. properties: original: type: string From f0dd7d5820d2095c16fc3193d013e2f109df166d Mon Sep 17 00:00:00 2001 From: yasser aboelgheit Date: Wed, 30 Sep 2026 16:47:59 +0100 Subject: [PATCH 4/4] Add an admin_reply request example to replyTicket Pairs with the new Admin reply response example, so the request shown next to it is an admin comment instead of the user reply. Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/2.16/api.intercom.io.yaml | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/descriptions/2.16/api.intercom.io.yaml b/descriptions/2.16/api.intercom.io.yaml index f4ba9929..654541dd 100644 --- a/descriptions/2.16/api.intercom.io.yaml +++ b/descriptions/2.16/api.intercom.io.yaml @@ -20356,6 +20356,13 @@ paths: Ticket. example: true examples: + admin_reply: + summary: Admin reply + value: + message_type: comment + type: admin + admin_id: 991267940 + body: "

Thanks for reaching out, we're looking into it!

" user_reply: summary: User reply value: