Update Preview escalation context contract

descriptions/0/api.intercom.io.yaml

@@ -25667,14 +25667,16 @@ paths:
         - `conversation_id` — escalate an existing agent conversation, including one started
           with `/fin/ask`. On the Intercom Helpdesk, Fin by default summarises the conversation
           and opens a new Helpdesk conversation that carries the summary as an internal note;
-          the original agent conversation is not reassigned. Configure an escalation Operator
-          Workflow to change this default.
+          the original agent conversation is not reassigned or closed. Configure an escalation
+          Operator Workflow to change this default.
         - `user` — escalate on behalf of a user with no prior agent conversation. On the Intercom
-          Helpdesk, a new Helpdesk conversation is created for the teammate. Include an optional
-          `message` for its first message. Not supported on Fin for Platforms — see below.
+          Helpdesk, a new Helpdesk conversation is created for the teammate. Not supported on Fin
+          for Platforms — see below.
 
-        In both cases the optional `context` is attached as an internal note (supplied by your
-        orchestrating agent, not generated by Fin) alongside any summary.
+        In both cases, pass the optional `context` to give the receiving teammate background your
+        orchestrating agent has and Fin does not. On the Intercom Helpdesk, it appears above the
+        summary in the internal note of the new conversation the teammate picks up. It is never
+        shown to the end user.
 
         Escalating an existing conversation also sets its AI Agent resolution state to
         `escalated`, readable as `ai_agent.resolution_state` on the Conversations API. This is a
@@ -25683,13 +25685,13 @@ paths:
         On Fin for Platforms, `conversation_id` is required — `user` is not supported and is
         rejected, because there is no Intercom Helpdesk in which to create a conversation. There
         is no Intercom inbox either, so an escalation that no workflow handles does not open a
-        Helpdesk conversation for a teammate. You are notified with the `escalated` status and
-        hand the conversation to a human on your own platform.
+        Helpdesk conversation for a teammate. `context` is not surfaced, and the conversation is
+        left open for your platform to hand off and continue driving.
 
         You are notified over the existing webhook or SSE channel with an `escalated` status
         followed by `complete`. The `complete` status signals that Fin is done; it does not close
-        the conversation. On the Intercom Helpdesk it remains open in the human inbox; on Fin for
-        Platforms it remains open for whoever handles it on your own platform.
+        the conversation. On the Intercom Helpdesk, the new human conversation remains open; on
+        Fin for Platforms, the conversation remains open for whoever handles it on your platform.
       responses:
         '200':
           description: Conversation escalated successfully
@@ -25777,15 +25779,10 @@ paths:
                   allOf:
                   - "$ref": "#/components/schemas/fin_agent_user"
                   - description: The user to escalate on behalf of, creating a new conversation. Provide this or `conversation_id`. Not supported on Fin for Platforms.
-                message:
-                  type: string
-                  maxLength: 10000
-                  description: Optional first message for the new conversation, used only when escalating on behalf of a `user`. Shown to the end-user (unlike `context`, which is an internal note), so don't include sensitive orchestration data. Defaults to "Requesting human support".
-                  example: I'd like to speak to a human about my refund.
                 context:
                   type: string
                   maxLength: 10000
-                  description: Optional context for the receiving teammate explaining why the conversation is being escalated. Attached as an internal note, never shown to the user. Avoid including credentials or unnecessary personal data — the note is visible to any teammate with access to the conversation.
+                  description: Optional background for the receiving teammate, valid with either `conversation_id` or `user`. On the Intercom Helpdesk, it appears above the summary in the internal note of the new conversation the teammate picks up, and is never shown to the end user. Not surfaced on Fin for Platforms. Avoid including credentials or unnecessary personal data — it is visible to any teammate with access to the conversation.
                   example: Customer is requesting a refund and is frustrated.
               oneOf:
               - required:
@@ -25803,7 +25800,7 @@ paths:
                     id: '123456'
                     name: John Doe
                     email: john.doe@example.com
-                  message: I need help with my billing issue
+                  context: I need help with my billing issue
   "/fin/csat":
     post:
       summary: Submit a CSAT rating