From 14ea18d9d5829c6763622c883afd49a9010507d1 Mon Sep 17 00:00:00 2001 From: Cathal Ging Date: Thu, 13 Aug 2026 14:06:42 +0100 Subject: [PATCH 1/5] feat(preview): add translations field to conversation_part and ticket_part Model the new `translations` object on the Preview conversation_part and ticket_part schemas. It is a map keyed by locale code: the special `original` key holds the source locale code of the reply, and every other key is a locale code whose value is the reply text translated into that locale, e.g. { "original": "en", "en": "Hello", "fr": "Bonjour" }. This backs the new `conversation.admin.replied.translated` and `ticket.admin.replied.translated` webhook topics. The existing `body` field is unchanged and stays in the original source language. The field is Preview-only (descriptions/0), so it is gated by the Preview API version. Co-Authored-By: Claude Opus 4.8 (1M context) --- descriptions/0/api.intercom.io.yaml | 34 +++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 13975bd..1914d10 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -31865,6 +31865,23 @@ 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. Only present on the + Preview API version and 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 `body` field is unchanged and always + stays in the original source language. Available in the Preview API version + only (set `Intercom-Version: Preview`). + additionalProperties: + type: string + example: + original: en + en: 'Hello' + fr: 'Bonjour' conversation_part_author: title: Conversation part author type: object @@ -39471,6 +39488,23 @@ 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. Only present on the + Preview API version and 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 `body` field is unchanged and always + stays in the original source language. Available in the Preview API version + only (set `Intercom-Version: Preview`). + additionalProperties: + type: string + example: + original: en + en: 'Hello' + fr: 'Bonjour' updated_attribute_data: title: Updated Attribute type: object From ffbda0fe69ccd9bb92b818bde1bb54a8c91d9e03 Mon Sep 17 00:00:00 2001 From: Cathal Ging Date: Fri, 21 Aug 2026 12:53:12 +0100 Subject: [PATCH 2/5] fix(preview): require original key and add translations to reply examples Declares `original` as required on the conversation_part and ticket_part translations schemas, since it is always present in the payload. Also adds translations to the existing admin-authored comment/reply examples (retrieveConversation, updateConversationPart) so the new field is demonstrated in inline responses. --- descriptions/0/api.intercom.io.yaml | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 1914d10..087418a 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -12180,6 +12180,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 @@ -12385,6 +12389,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 @@ -14148,6 +14156,10 @@ paths: attachments: [] external_id: external_reply_send_state: sent + translations: + original: en + en: 'Hello there!' + fr: 'Bonjour!' Mark part as seen: value: type: conversation_part @@ -14167,6 +14179,10 @@ paths: external_id: seen_state: admin_seen: true + translations: + original: en + en: 'Hello there!' + fr: 'Bonjour!' schema: "$ref": "#/components/schemas/conversation_part" '401': @@ -31876,6 +31892,8 @@ components: text translated into that locale. The `body` field is unchanged and always stays in the original source language. Available in the Preview API version only (set `Intercom-Version: Preview`). + required: + - original additionalProperties: type: string example: @@ -39499,6 +39517,8 @@ components: text translated into that locale. The `body` field is unchanged and always stays in the original source language. Available in the Preview API version only (set `Intercom-Version: Preview`). + required: + - original additionalProperties: type: string example: From 109c47e55499d0ec335b6a33997277cf5a56aea7 Mon Sep 17 00:00:00 2001 From: Cathal Ging Date: Fri, 21 Aug 2026 12:55:59 +0100 Subject: [PATCH 3/5] fix(preview): add admin comment reply example with translations to replyTicket replyTicket only had note and quick_reply examples, neither a legitimate carrier of translations (note is internal-only, quick_reply here has no reply body text). Adds a customer-facing admin comment reply example, matching the ticket_reply schema's documented comment support. --- descriptions/0/api.intercom.io.yaml | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 087418a..5d43795 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -22227,6 +22227,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 From 346fc6380c2cd0c20fc3d370dd42d8c3ade88e1d Mon Sep 17 00:00:00 2001 From: Cathal Ging Date: Fri, 21 Aug 2026 13:00:21 +0100 Subject: [PATCH 4/5] fix(preview): translations values are HTML like body, not plain text Corrects every translations example (retrieveConversation, updateConversationPart, the new replyTicket comment example) and both schema-level example blocks to wrap translated text in the same HTML as body, per production payload shape. Also clarifies the schema description to state values are HTML matching body's format. --- descriptions/0/api.intercom.io.yaml | 34 +++++++++++++++-------------- 1 file changed, 18 insertions(+), 16 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 5d43795..43cbdbd 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -12182,8 +12182,8 @@ paths: app_package_code: null translations: original: en - en: 'Okay!' - fr: "D'accord!" + en:

Okay!

+ fr: "

D'accord!

" - type: conversation_part id: 2 part_type: custom_action_started @@ -12391,8 +12391,8 @@ paths: app_package_code: null translations: original: en - en: 'Okay!' - fr: "D'accord!" + en:

Okay!

+ fr: "

D'accord!

" - type: conversation_part id: 2 part_type: custom_action_started @@ -14158,8 +14158,8 @@ paths: external_reply_send_state: sent translations: original: en - en: 'Hello there!' - fr: 'Bonjour!' + en: "

Hello there!

" + fr: "

Bonjour!

" Mark part as seen: value: type: conversation_part @@ -14181,8 +14181,8 @@ paths: admin_seen: true translations: original: en - en: 'Hello there!' - fr: 'Bonjour!' + en: "

Hello there!

" + fr: "

Bonjour!

" schema: "$ref": "#/components/schemas/conversation_part" '401': @@ -22245,8 +22245,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 @@ -31909,7 +31909,8 @@ components: Preview API version and 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 `body` field is unchanged and always + 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 in the Preview API version only (set `Intercom-Version: Preview`). required: @@ -31918,8 +31919,8 @@ components: type: string example: original: en - en: 'Hello' - fr: 'Bonjour' + en:

Hello

+ fr:

Bonjour

conversation_part_author: title: Conversation part author type: object @@ -39534,7 +39535,8 @@ components: Preview API version and 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 `body` field is unchanged and always + 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 in the Preview API version only (set `Intercom-Version: Preview`). required: @@ -39543,8 +39545,8 @@ components: type: string example: original: en - en: 'Hello' - fr: 'Bonjour' + en:

Hello

+ fr:

Bonjour

updated_attribute_data: title: Updated Attribute type: object From 015c57da1022bb5b88ff68d58b7a24d8b12e2d49 Mon Sep 17 00:00:00 2001 From: Cathal Ging Date: Fri, 21 Aug 2026 13:05:12 +0100 Subject: [PATCH 5/5] fix(preview): add translations to the ticket_reply response schema replyTicket's 200 response uses ticket_reply, not ticket_part, so the Admin reply example's translations field had no schema definition backing it. Adds the same translations property (required original, HTML values, ticket.admin.replied.translated topic) already present on conversation_part and ticket_part. --- descriptions/0/api.intercom.io.yaml | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 43cbdbd..b53c729 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -39716,6 +39716,26 @@ 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. Only present on the + Preview API version and 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 in the Preview API version + only (set `Intercom-Version: Preview`). + required: + - original + additionalProperties: + type: string + example: + original: en + en:

Hello

+ fr:

Bonjour

ticket_request_custom_attributes: title: Ticket Attributes type: object