{"command":{"effect":"write","timeoutSeconds":30,"inputSchema":{"type":"object","description":"Hand a conversation off to a human teammate. If you use the Intercom Helpdesk, the\nhandoff lands in your team inbox.\n\nProvide either `conversation_id` or `user`:\n\n- `conversation_id` — escalate an existing agent conversation, including one started\n  with `/fin/ask`. On the Intercom Helpdesk, Fin by default summarises the conversation\n  and opens a new Helpdesk conversation that carries the summary as an internal note.\n  Configure an escalation Operator Workflow to change this default. Escalation closes the\n  original agent conversation if it is open.\n- `user` — escalate on behalf of a user with no prior agent conversation. Fin creates an\n  agent conversation for the escalation and closes it once the handoff completes. On the\n  Intercom Helpdesk, the teammate works in a separate new Helpdesk conversation. Not\n  supported on Fin for Platforms — see below.\n\nIn both cases, pass the optional `context` to give the receiving teammate background your\norchestrating agent has and Fin does not. On the Intercom Helpdesk, it appears above the\nsummary in the internal note of the new conversation the teammate picks up. It is never\nshown to the end user.\n\nEscalating an existing conversation also sets its AI Agent resolution state to\n`escalated`, readable as `ai_agent.resolution_state` on the Conversations API. This is a\nresolution state, not a billable resolution.\n\nOn Fin for Platforms, `conversation_id` is required — `user` is not supported and is\nrejected, because there is no Intercom Helpdesk in which to create a conversation. There\nis no Intercom inbox either, so an escalation that no workflow handles does not open a\nHelpdesk conversation for a teammate. `context` is not surfaced. The conversation is closed,\nas on the Intercom Helpdesk, and your platform hands the user off to a human.\n\nYou are notified via webhooks with an `escalated` status\nfollowed by `complete`. The `complete` status signals that Fin is done. By then the\noriginal agent conversation has been closed. An escalation Operator Workflow may act\non it afterwards, but it is closed again once the workflow's first steps have run, so\nonly steps that run later (for example after a wait) can reopen it. On the Intercom\nHelpdesk, the new human conversation remains open.\n\n{% admonition type=\"warning\" %}\nTo request access to the Fin Agent API, go to **Settings > Integrations > Fin Agent API** in your workspace and tell us about your use case. Once access is granted, **Fin Agent API** appears under **Fin AI Agent > Deploy**.\n{% /admonition %}\n","properties":{"headers":{"type":"object","properties":{"Intercom-Version":{"$ref":"#/definitions/intercom_version","enum":["2.17"]}},"required":[],"additionalProperties":false},"body":{"type":"object","properties":{"conversation_id":{"type":"string","description":"The external ID of the conversation to escalate. Provide this or `user`. Required on Fin for Platforms, where `user` is not supported.","examples":["ext-123"]},"user":{"allOf":[{"$ref":"#/definitions/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."}]},"context":{"type":"string","maxLength":10000,"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.","examples":["Customer is requesting a refund and is frustrated."]}},"oneOf":[{"required":["conversation_id"]},{"required":["user"]}],"examples":[{"conversation_id":"ext-123","context":"Customer is requesting a refund and is frustrated."}]}},"required":["body"],"additionalProperties":false,"definitions":{"intercom_version":{"description":"Intercom API version.</br>If you omit the header, the API uses the version set in your app package, and 1.0 if none is set.","type":"string","enum":["1.0","1.1","1.2","1.3","1.4","2.0","2.1","2.2","2.3","2.4","2.5","2.6","2.7","2.8","2.9","2.10","2.11","2.12","2.13","2.14","2.15","2.16","2.17"],"examples":["2.17"]},"fin_agent_user":{"title":"Fin Agent User","type":"object","description":"A user object representing the user in a Fin Agent conversation.","properties":{"id":{"type":"string","description":"The ID of the user. This value will be used to uniquely identify the user\nduring a conversation with Fin. Maps to the user_id field on the Intercom User object.\n","examples":["123456"]},"name":{"type":"string","description":"The name of the user.","examples":["John Doe"]},"email":{"type":"string","format":"email","description":"The email of the user.","examples":["john.doe@example.com"]},"attributes":{"type":"object","description":"A hash of attributes associated with the user.\nAttributes can be used by Fin to target content and responses.\nLimit to 10 attributes.\n","additionalProperties":true,"examples":[{"plan_type":"Pro","subscription_status":"active"}]}},"required":["id"]}}},"name":"Escalate to a human","id":"intercom.escalatefinconversation","example":{"body":{"conversation_id":"ext-123","context":"Customer is requesting a refund and is frustrated."}},"maxRequests":1,"summary":false}}