Add translations field to conversation_part and ticket_part (Preview) (#621)

* 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) <noreply@anthropic.com>

* 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.

* 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.

* 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.

* 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.

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: cathalging

descriptions/0/api.intercom.io.yaml

@@ -12188,6 +12188,10 @@ paths:
                             name: Test tag
                         event_details:
                         app_package_code: null
+                        translations:
+                          original: en
+                          en: <p>Okay!</p>
+                          fr: "<p>D'accord!</p>"
                       - type: conversation_part
                         id: 2
                         part_type: custom_action_started
@@ -12393,6 +12397,10 @@ paths:
                             name: Test tag
                         event_details:
                         app_package_code: null
+                        translations:
+                          original: en
+                          en: <p>Okay!</p>
+                          fr: "<p>D'accord!</p>"
                       - type: conversation_part
                         id: 2
                         part_type: custom_action_started
@@ -14157,6 +14165,10 @@ paths:
                     attachments: []
                     external_id:
                     external_reply_send_state: sent
+                    translations:
+                      original: en
+                      en: "<p>Hello there!</p>"
+                      fr: "<p>Bonjour!</p>"
                 Mark part as seen:
                   value:
                     type: conversation_part
@@ -14176,6 +14188,10 @@ paths:
                     external_id:
                     seen_state:
                       admin_seen: true
+                    translations:
+                      original: en
+                      en: "<p>Hello there!</p>"
+                      fr: "<p>Bonjour!</p>"
               schema:
                 "$ref": "#/components/schemas/conversation_part"
         '401':
@@ -22415,6 +22431,26 @@ paths:
           content:
             application/json:
               examples:
+                Admin reply:
+                  value:
+                    type: ticket_part
+                    id: '155'
+                    part_type: comment
+                    body: "<p>Thanks for reaching out, we're looking into it!</p>"
+                    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: "<p>Thanks for reaching out, we're looking into it!</p>"
+                      fr: "<p>Merci de nous avoir contactés, nous nous en occupons !</p>"
                 Admin note reply:
                   value:
                     type: ticket_part
@@ -32093,6 +32129,26 @@ 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, 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: <p>Hello</p>
+            fr: <p>Bonjour</p>
     conversation_part_author:
       title: Conversation part author
       type: object
@@ -39718,6 +39774,26 @@ 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, 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: <p>Hello</p>
+            fr: <p>Bonjour</p>
         updated_attribute_data:
           title: Updated Attribute
           type: object
@@ -39887,6 +39963,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: <p>Hello</p>
+            fr: <p>Bonjour</p>
     ticket_request_custom_attributes:
       title: Ticket Attributes
       type: object