From a220599f45e16239ed8359a3a5be2e250ec2c7bc Mon Sep 17 00:00:00 2001 From: Rahul D'Souza Date: Mon, 28 Sep 2026 15:38:40 +0100 Subject: [PATCH] Add Fin Agent API orchestration endpoints to v2.14, v2.15, and v2.16 Document the `/fin/capabilities`, `/fin/ask`, `/fin/procedures/{procedure_id}/run`, and `/fin/escalate` endpoints on API versions 2.14, 2.15, and 2.16. Update the Fin Agent tag description to list these endpoints, and add `intercom_conversation_id` to the `/fin/ask` and `/fin/procedures/{procedure_id}/run` responses. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_01EExbnyABqRELbKq47qWL3q --- descriptions/2.14/api.intercom.io.yaml | 669 ++++++++++++++++++++++++- descriptions/2.15/api.intercom.io.yaml | 669 ++++++++++++++++++++++++- descriptions/2.16/api.intercom.io.yaml | 669 ++++++++++++++++++++++++- 3 files changed, 2004 insertions(+), 3 deletions(-) diff --git a/descriptions/2.14/api.intercom.io.yaml b/descriptions/2.14/api.intercom.io.yaml index f9de1521..42070a3b 100644 --- a/descriptions/2.14/api.intercom.io.yaml +++ b/descriptions/2.14/api.intercom.io.yaml @@ -2324,6 +2324,673 @@ paths: conversation_id: ext-123 rating: amazing remark: Fin solved my problem in seconds. + "/fin/capabilities": + post: + summary: Discover Fin's capabilities + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + tags: + - Fin Agent + operationId: listFinCapabilities + description: | + Return a machine-readable, per-user list of what Fin can do for a given end user, so an + orchestrating agent can decide which endpoint to call. + + The response is audience-matched to the supplied user: each live, API-triggerable + procedure is checked against that user before being included, alongside the static + `reply` and `ask` actions. + responses: + '200': + description: Capabilities returned successfully + content: + application/json: + examples: + Successful response: + value: + version: "2.14" + capabilities: + - type: procedure + id: '12345' + name: Reset password + description: Walk the user through resetting their password. + endpoint: /fin/procedures/12345/run + method: POST + - type: reply + description: Reply to an in-progress Fin conversation. + endpoint: /fin/reply + method: POST + - type: ask + description: Ask Fin a single, self-contained question. + endpoint: /fin/ask + method: POST + schema: + type: object + properties: + version: + type: string + description: The API version the capabilities document was generated for. + example: "2.14" + capabilities: + type: array + description: The list of capabilities available to this user. + items: + type: object + properties: + type: + type: string + description: The kind of capability — `procedure` for a runnable procedure, or a static action such as `reply`, `ask`, or `escalate`. + example: procedure + id: + type: string + description: The procedure ID. Present only when `type` is `procedure`. + example: '12345' + name: + type: string + description: The procedure name. Present only when `type` is `procedure`. + example: Reset password + description: + type: string + description: A human-readable description of the capability. + example: Walk the user through resetting their password. + endpoint: + type: string + description: The endpoint path to call to use this capability. + example: /fin/procedures/12345/run + method: + type: string + description: The HTTP method to use. + example: POST + '400': + description: Bad Request + content: + application/json: + examples: + Too many attributes: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: parameter_invalid + message: Cannot update more than 10 attributes at once. + schema: + "$ref": "#/components/schemas/error" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + user: + allOf: + - "$ref": "#/components/schemas/fin_agent_user" + - description: The user to list capabilities for. If no user exists for the id, one is created from the supplied details; if the user already exists, the supplied email and attributes update it. + required: + - user + examples: + Capabilities for a user: + value: + user: + id: '123456' + "/fin/ask": + post: + summary: Ask Fin + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + tags: + - Fin Agent + operationId: askFin + description: | + Ask Fin a single, self-contained question and receive one informational answer. + + Unlike a conversation, `/fin/ask` is non-conversational: Fin will not ask follow-up + questions, will not run procedures, and will not escalate to a human on its own. You can + still escalate one yourself with `POST /fin/escalate`; the ask conversation is already + closed after its one-shot answer, and escalation leaves it closed while routing the + handoff separately. + + Fin's answer is delivered asynchronously via the `fin_replied` event. The conversation + ends with a `complete` status — there is no `awaiting_user_reply` cycle. + responses: + '200': + description: Question accepted successfully + content: + application/json: + examples: + Successful response: + value: + conversation_id: ext-123 + intercom_conversation_id: '192837465' + user_id: user-456 + status: thinking + created_at_ms: '2025-01-24T10:00:00.123Z' + sse_subscription_url: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m' + Response with attribute errors: + value: + conversation_id: ext-123 + intercom_conversation_id: '192837465' + user_id: user-456 + status: thinking + created_at_ms: '2025-01-24T10:00:00.123Z' + sse_subscription_url: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m' + errors: + user: + attributes: + invalid_attr: User attribute 'invalid_attr' does not exist + schema: + type: object + properties: + conversation_id: + type: string + description: The external ID of the conversation. + example: ext-123 + intercom_conversation_id: + type: string + description: The internal Intercom conversation ID, useful for matching this Agent API session to the conversation in Intercom. + example: '192837465' + user_id: + type: string + description: The ID of the user. + example: user-456 + status: + type: string + enum: + - thinking + - replying + - resolved + - complete + description: | + Fin's current status in the conversation workflow. + example: thinking + created_at_ms: + type: string + format: date-time + description: The timestamp the response was created at, with millisecond precision. + example: '2025-01-24T10:00:00.123Z' + errors: + "$ref": "#/components/schemas/fin_agent_attribute_errors" + sse_subscription_url: + type: string + description: | + Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to complete status. When CSAT is enabled and a survey will follow the resolution, `complete` revocation is deferred until the `csat_requested` event is delivered or the token expires. + example: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m' + '400': + description: Bad Request + content: + application/json: + examples: + Conversation ID missing: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: parameter_invalid + message: External Conversation ID is required + User ID missing: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: parameter_invalid + message: User ID is required + Too many history items: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: parameter_invalid + message: Conversation history cannot contain more than 10 items + schema: + "$ref": "#/components/schemas/error" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + conversation_id: + type: string + description: Your external conversation ID. Fin creates a conversation for this ID. If a conversation already exists for it, use `/fin/reply` instead. + example: ext-123 + message: + "$ref": "#/components/schemas/fin_agent_message" + user: + "$ref": "#/components/schemas/fin_agent_user" + conversation_metadata: + "$ref": "#/components/schemas/fin_agent_conversation_metadata" + attachments: + type: array + description: An array of attachments to include with the message. Maximum of 10 attachments. + maxItems: 10 + items: + "$ref": "#/components/schemas/fin_agent_attachment" + required: + - conversation_id + - message + - user + examples: + Basic question: + value: + conversation_id: ext-123 + message: + author: user + body: How do I reset my password? + timestamp: '2025-01-24T10:01:20.000Z' + user: + id: '123456' + name: John Doe + email: john.doe@example.com + Question with history and attributes: + value: + conversation_id: ext-123 + message: + author: user + body: And how long does that take to apply? + timestamp: '2025-01-24T10:02:00.000Z' + user: + id: '123456' + name: John Doe + email: john.doe@example.com + attributes: + plan_type: Pro + conversation_metadata: + history: + - author: user + body: How do I reset my password? + timestamp: '2025-01-24T10:01:20.000Z' + attributes: + order_id: '98765' + "/fin/procedures/{procedure_id}/run": + post: + summary: Run a Fin procedure + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + - name: procedure_id + in: path + required: true + description: The ID of the procedure to run. + schema: + type: string + example: '12345' + tags: + - Fin Agent + operationId: runFinProcedure + description: | + Deterministically run a specific procedure on a new conversation. Calling this endpoint + guarantees that the named procedure runs — there is no non-deterministic routing. + + Fin's progress is delivered asynchronously via events or Server-Sent Events. If the + procedure pauses for user input, the conversation status becomes `awaiting_user_reply` — + send the user's response with [`/fin/reply`](/docs/references/2.14/rest-api/api.intercom.io/fin-agent/replytofin). + responses: + '200': + description: Procedure run started successfully + content: + application/json: + examples: + Successful response: + value: + conversation_id: ext-123 + intercom_conversation_id: '192837465' + user_id: user-456 + procedure_id: '12345' + status: thinking + created_at_ms: '2025-01-24T10:00:00.123Z' + sse_subscription_url: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m' + Response with attribute errors: + value: + conversation_id: ext-123 + intercom_conversation_id: '192837465' + user_id: user-456 + procedure_id: '12345' + status: thinking + created_at_ms: '2025-01-24T10:00:00.123Z' + sse_subscription_url: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m' + errors: + user: + attributes: + invalid_attr: User attribute 'invalid_attr' does not exist + schema: + type: object + properties: + conversation_id: + type: string + description: The ID of the conversation. + example: ext-123 + intercom_conversation_id: + type: string + description: The internal Intercom conversation ID, useful for matching this Agent API session to the conversation in Intercom. + example: '192837465' + user_id: + type: string + description: The ID of the user. + example: user-456 + procedure_id: + type: string + description: The ID of the procedure that was run. + example: '12345' + status: + type: string + enum: + - thinking + - replying + - awaiting_user_reply + - escalated + - resolved + - complete + description: | + Fin's current status in the conversation workflow. + example: thinking + created_at_ms: + type: string + format: date-time + description: The timestamp the response was created at, with millisecond precision. + example: '2025-01-24T10:00:00.123Z' + errors: + "$ref": "#/components/schemas/fin_agent_attribute_errors" + sse_subscription_url: + type: string + description: | + Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. When CSAT is enabled and a survey will follow the resolution, `complete` revocation is deferred until the `csat_requested` event is delivered or the token expires. + example: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m' + '400': + description: Bad Request + content: + application/json: + examples: + Procedure not found: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: parameter_invalid + message: Procedure not found + Procedure not live: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: parameter_invalid + message: Procedure is not live + Procedure has no API trigger: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: parameter_invalid + message: Procedure does not have an API trigger + No Fin profile: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: parameter_invalid + message: No Fin profile is configured to handle this conversation. Configure a Fin profile and retry. + Conversation already exists: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: parameter_invalid + message: Fin session already exists for this conversation. Please use /reply to continue the conversation. + schema: + "$ref": "#/components/schemas/error" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + conversation_id: + type: string + description: Your external conversation ID. Fin creates a conversation for this ID. If a conversation already exists for it, use `/fin/reply` instead. + example: ext-123 + user: + "$ref": "#/components/schemas/fin_agent_user" + message: + "$ref": "#/components/schemas/fin_agent_message" + conversation_metadata: + type: object + description: Metadata about the conversation. Only attributes are accepted (no history). + properties: + attributes: + type: object + description: | + A hash of conversation attributes. Limit to 10 attributes. + additionalProperties: true + example: + order_id: '98765' + required: + - conversation_id + - user + examples: + Basic procedure run: + value: + conversation_id: ext-123 + user: + id: '123456' + name: John Doe + email: john.doe@example.com + Procedure run with trigger message and attributes: + value: + conversation_id: ext-123 + user: + id: '123456' + name: John Doe + email: john.doe@example.com + message: + author: agent + body: Starting your refund request. + conversation_metadata: + attributes: + order_id: '98765' + "/fin/escalate": + post: + summary: Escalate to a human + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + tags: + - Fin Agent + operationId: escalateFinConversation + description: | + Hand a conversation off to a human teammate. If you use the Intercom Helpdesk, the + handoff lands in your team inbox. + + Provide either `conversation_id` or `user`: + + - `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. + Escalation does not change the original agent conversation's assignment or open/closed + state. 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. Not supported on Fin + for Platforms — see below. + + 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 + resolution state, not a billable resolution. + + 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. `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, 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 + content: + application/json: + examples: + Existing conversation: + value: + conversation_id: ext-123 + status: escalated + sse_subscription_url: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m' + New conversation: + value: + intercom_conversation_id: '987654321' + status: escalated + schema: + type: object + properties: + conversation_id: + type: string + description: The external ID of the conversation. Returned when you escalate an existing conversation by `conversation_id` (echoed back). When you escalate a `user`, a new conversation is created and only `intercom_conversation_id` is returned. + example: ext-123 + intercom_conversation_id: + type: string + description: The internal Intercom conversation ID. Returned when a new conversation was created for the escalation. + example: '987654321' + sse_subscription_url: + type: string + description: | + Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to complete status. When CSAT is enabled and a survey will follow the resolution, `complete` revocation is deferred until the `csat_requested` event is delivered or the token expires. Includes a `rewind` window so a subscriber that connects after the escalation is processed can still receive the `escalated` and `complete` events. + example: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m' + status: + type: string + enum: + - escalated + description: The resulting status of the conversation. + example: escalated + '400': + description: Bad Request + content: + application/json: + examples: + Neither identifier provided: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: parameter_invalid + message: Either conversation_id or user must be provided + Conversation not found: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: parameter_invalid + message: Conversation not found + schema: + "$ref": "#/components/schemas/error" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + requestBody: + required: true + content: + application/json: + schema: + 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. + example: ext-123 + user: + 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. + 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. + example: Customer is requesting a refund and is frustrated. + oneOf: + - required: + - conversation_id + - required: + - user + examples: + Escalate an existing conversation: + value: + conversation_id: ext-123 + context: Customer is requesting a refund and is frustrated. + Escalate on behalf of a user: + value: + user: + id: '123456' + name: John Doe + email: john.doe@example.com + context: I need help with my billing issue "/help_center/collections": get: summary: List all collections @@ -23665,7 +24332,7 @@ tags:   - Integration is centered around two endpoints (`/fin/start` and `/fin/reply`) and a set of events that notify your application of Fin's status and responses. Events can be delivered via webhooks or Server-Sent Events (SSE). You can also record a customer satisfaction rating with `/fin/csat`. + Integration centres on the Fin Agent API endpoints — start a conversation with `/fin/start` and continue it with `/fin/reply`, or drive Fin from your own agent with `/fin/capabilities`, `/fin/ask`, `/fin/procedures/{procedure_id}/run`, and `/fin/escalate` — plus a set of events that notify your application of Fin's status and responses. Events can be delivered via webhooks or Server-Sent Events (SSE). You can also record a customer satisfaction rating with `/fin/csat`.   diff --git a/descriptions/2.15/api.intercom.io.yaml b/descriptions/2.15/api.intercom.io.yaml index af1e2b40..c323b521 100644 --- a/descriptions/2.15/api.intercom.io.yaml +++ b/descriptions/2.15/api.intercom.io.yaml @@ -15120,6 +15120,673 @@ paths: conversation_id: ext-123 rating: amazing remark: Fin solved my problem in seconds. + "/fin/capabilities": + post: + summary: Discover Fin's capabilities + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + tags: + - Fin Agent + operationId: listFinCapabilities + description: | + Return a machine-readable, per-user list of what Fin can do for a given end user, so an + orchestrating agent can decide which endpoint to call. + + The response is audience-matched to the supplied user: each live, API-triggerable + procedure is checked against that user before being included, alongside the static + `reply` and `ask` actions. + responses: + '200': + description: Capabilities returned successfully + content: + application/json: + examples: + Successful response: + value: + version: "2.15" + capabilities: + - type: procedure + id: '12345' + name: Reset password + description: Walk the user through resetting their password. + endpoint: /fin/procedures/12345/run + method: POST + - type: reply + description: Reply to an in-progress Fin conversation. + endpoint: /fin/reply + method: POST + - type: ask + description: Ask Fin a single, self-contained question. + endpoint: /fin/ask + method: POST + schema: + type: object + properties: + version: + type: string + description: The API version the capabilities document was generated for. + example: "2.15" + capabilities: + type: array + description: The list of capabilities available to this user. + items: + type: object + properties: + type: + type: string + description: The kind of capability — `procedure` for a runnable procedure, or a static action such as `reply`, `ask`, or `escalate`. + example: procedure + id: + type: string + description: The procedure ID. Present only when `type` is `procedure`. + example: '12345' + name: + type: string + description: The procedure name. Present only when `type` is `procedure`. + example: Reset password + description: + type: string + description: A human-readable description of the capability. + example: Walk the user through resetting their password. + endpoint: + type: string + description: The endpoint path to call to use this capability. + example: /fin/procedures/12345/run + method: + type: string + description: The HTTP method to use. + example: POST + '400': + description: Bad Request + content: + application/json: + examples: + Too many attributes: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: parameter_invalid + message: Cannot update more than 10 attributes at once. + schema: + "$ref": "#/components/schemas/error" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + user: + allOf: + - "$ref": "#/components/schemas/fin_agent_user" + - description: The user to list capabilities for. If no user exists for the id, one is created from the supplied details; if the user already exists, the supplied email and attributes update it. + required: + - user + examples: + Capabilities for a user: + value: + user: + id: '123456' + "/fin/ask": + post: + summary: Ask Fin + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + tags: + - Fin Agent + operationId: askFin + description: | + Ask Fin a single, self-contained question and receive one informational answer. + + Unlike a conversation, `/fin/ask` is non-conversational: Fin will not ask follow-up + questions, will not run procedures, and will not escalate to a human on its own. You can + still escalate one yourself with `POST /fin/escalate`; the ask conversation is already + closed after its one-shot answer, and escalation leaves it closed while routing the + handoff separately. + + Fin's answer is delivered asynchronously via the `fin_replied` event. The conversation + ends with a `complete` status — there is no `awaiting_user_reply` cycle. + responses: + '200': + description: Question accepted successfully + content: + application/json: + examples: + Successful response: + value: + conversation_id: ext-123 + intercom_conversation_id: '192837465' + user_id: user-456 + status: thinking + created_at_ms: '2025-01-24T10:00:00.123Z' + sse_subscription_url: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m' + Response with attribute errors: + value: + conversation_id: ext-123 + intercom_conversation_id: '192837465' + user_id: user-456 + status: thinking + created_at_ms: '2025-01-24T10:00:00.123Z' + sse_subscription_url: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m' + errors: + user: + attributes: + invalid_attr: User attribute 'invalid_attr' does not exist + schema: + type: object + properties: + conversation_id: + type: string + description: The external ID of the conversation. + example: ext-123 + intercom_conversation_id: + type: string + description: The internal Intercom conversation ID, useful for matching this Agent API session to the conversation in Intercom. + example: '192837465' + user_id: + type: string + description: The ID of the user. + example: user-456 + status: + type: string + enum: + - thinking + - replying + - resolved + - complete + description: | + Fin's current status in the conversation workflow. + example: thinking + created_at_ms: + type: string + format: date-time + description: The timestamp the response was created at, with millisecond precision. + example: '2025-01-24T10:00:00.123Z' + errors: + "$ref": "#/components/schemas/fin_agent_attribute_errors" + sse_subscription_url: + type: string + description: | + Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to complete status. When CSAT is enabled and a survey will follow the resolution, `complete` revocation is deferred until the `csat_requested` event is delivered or the token expires. + example: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m' + '400': + description: Bad Request + content: + application/json: + examples: + Conversation ID missing: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: parameter_invalid + message: External Conversation ID is required + User ID missing: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: parameter_invalid + message: User ID is required + Too many history items: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: parameter_invalid + message: Conversation history cannot contain more than 10 items + schema: + "$ref": "#/components/schemas/error" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + conversation_id: + type: string + description: Your external conversation ID. Fin creates a conversation for this ID. If a conversation already exists for it, use `/fin/reply` instead. + example: ext-123 + message: + "$ref": "#/components/schemas/fin_agent_message" + user: + "$ref": "#/components/schemas/fin_agent_user" + conversation_metadata: + "$ref": "#/components/schemas/fin_agent_conversation_metadata" + attachments: + type: array + description: An array of attachments to include with the message. Maximum of 10 attachments. + maxItems: 10 + items: + "$ref": "#/components/schemas/fin_agent_attachment" + required: + - conversation_id + - message + - user + examples: + Basic question: + value: + conversation_id: ext-123 + message: + author: user + body: How do I reset my password? + timestamp: '2025-01-24T10:01:20.000Z' + user: + id: '123456' + name: John Doe + email: john.doe@example.com + Question with history and attributes: + value: + conversation_id: ext-123 + message: + author: user + body: And how long does that take to apply? + timestamp: '2025-01-24T10:02:00.000Z' + user: + id: '123456' + name: John Doe + email: john.doe@example.com + attributes: + plan_type: Pro + conversation_metadata: + history: + - author: user + body: How do I reset my password? + timestamp: '2025-01-24T10:01:20.000Z' + attributes: + order_id: '98765' + "/fin/procedures/{procedure_id}/run": + post: + summary: Run a Fin procedure + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + - name: procedure_id + in: path + required: true + description: The ID of the procedure to run. + schema: + type: string + example: '12345' + tags: + - Fin Agent + operationId: runFinProcedure + description: | + Deterministically run a specific procedure on a new conversation. Calling this endpoint + guarantees that the named procedure runs — there is no non-deterministic routing. + + Fin's progress is delivered asynchronously via events or Server-Sent Events. If the + procedure pauses for user input, the conversation status becomes `awaiting_user_reply` — + send the user's response with [`/fin/reply`](/docs/references/2.15/rest-api/api.intercom.io/fin-agent/replytofin). + responses: + '200': + description: Procedure run started successfully + content: + application/json: + examples: + Successful response: + value: + conversation_id: ext-123 + intercom_conversation_id: '192837465' + user_id: user-456 + procedure_id: '12345' + status: thinking + created_at_ms: '2025-01-24T10:00:00.123Z' + sse_subscription_url: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m' + Response with attribute errors: + value: + conversation_id: ext-123 + intercom_conversation_id: '192837465' + user_id: user-456 + procedure_id: '12345' + status: thinking + created_at_ms: '2025-01-24T10:00:00.123Z' + sse_subscription_url: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m' + errors: + user: + attributes: + invalid_attr: User attribute 'invalid_attr' does not exist + schema: + type: object + properties: + conversation_id: + type: string + description: The ID of the conversation. + example: ext-123 + intercom_conversation_id: + type: string + description: The internal Intercom conversation ID, useful for matching this Agent API session to the conversation in Intercom. + example: '192837465' + user_id: + type: string + description: The ID of the user. + example: user-456 + procedure_id: + type: string + description: The ID of the procedure that was run. + example: '12345' + status: + type: string + enum: + - thinking + - replying + - awaiting_user_reply + - escalated + - resolved + - complete + description: | + Fin's current status in the conversation workflow. + example: thinking + created_at_ms: + type: string + format: date-time + description: The timestamp the response was created at, with millisecond precision. + example: '2025-01-24T10:00:00.123Z' + errors: + "$ref": "#/components/schemas/fin_agent_attribute_errors" + sse_subscription_url: + type: string + description: | + Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. When CSAT is enabled and a survey will follow the resolution, `complete` revocation is deferred until the `csat_requested` event is delivered or the token expires. + example: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m' + '400': + description: Bad Request + content: + application/json: + examples: + Procedure not found: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: parameter_invalid + message: Procedure not found + Procedure not live: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: parameter_invalid + message: Procedure is not live + Procedure has no API trigger: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: parameter_invalid + message: Procedure does not have an API trigger + No Fin profile: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: parameter_invalid + message: No Fin profile is configured to handle this conversation. Configure a Fin profile and retry. + Conversation already exists: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: parameter_invalid + message: Fin session already exists for this conversation. Please use /reply to continue the conversation. + schema: + "$ref": "#/components/schemas/error" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + conversation_id: + type: string + description: Your external conversation ID. Fin creates a conversation for this ID. If a conversation already exists for it, use `/fin/reply` instead. + example: ext-123 + user: + "$ref": "#/components/schemas/fin_agent_user" + message: + "$ref": "#/components/schemas/fin_agent_message" + conversation_metadata: + type: object + description: Metadata about the conversation. Only attributes are accepted (no history). + properties: + attributes: + type: object + description: | + A hash of conversation attributes. Limit to 10 attributes. + additionalProperties: true + example: + order_id: '98765' + required: + - conversation_id + - user + examples: + Basic procedure run: + value: + conversation_id: ext-123 + user: + id: '123456' + name: John Doe + email: john.doe@example.com + Procedure run with trigger message and attributes: + value: + conversation_id: ext-123 + user: + id: '123456' + name: John Doe + email: john.doe@example.com + message: + author: agent + body: Starting your refund request. + conversation_metadata: + attributes: + order_id: '98765' + "/fin/escalate": + post: + summary: Escalate to a human + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + tags: + - Fin Agent + operationId: escalateFinConversation + description: | + Hand a conversation off to a human teammate. If you use the Intercom Helpdesk, the + handoff lands in your team inbox. + + Provide either `conversation_id` or `user`: + + - `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. + Escalation does not change the original agent conversation's assignment or open/closed + state. 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. Not supported on Fin + for Platforms — see below. + + 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 + resolution state, not a billable resolution. + + 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. `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, 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 + content: + application/json: + examples: + Existing conversation: + value: + conversation_id: ext-123 + status: escalated + sse_subscription_url: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m' + New conversation: + value: + intercom_conversation_id: '987654321' + status: escalated + schema: + type: object + properties: + conversation_id: + type: string + description: The external ID of the conversation. Returned when you escalate an existing conversation by `conversation_id` (echoed back). When you escalate a `user`, a new conversation is created and only `intercom_conversation_id` is returned. + example: ext-123 + intercom_conversation_id: + type: string + description: The internal Intercom conversation ID. Returned when a new conversation was created for the escalation. + example: '987654321' + sse_subscription_url: + type: string + description: | + Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to complete status. When CSAT is enabled and a survey will follow the resolution, `complete` revocation is deferred until the `csat_requested` event is delivered or the token expires. Includes a `rewind` window so a subscriber that connects after the escalation is processed can still receive the `escalated` and `complete` events. + example: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m' + status: + type: string + enum: + - escalated + description: The resulting status of the conversation. + example: escalated + '400': + description: Bad Request + content: + application/json: + examples: + Neither identifier provided: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: parameter_invalid + message: Either conversation_id or user must be provided + Conversation not found: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: parameter_invalid + message: Conversation not found + schema: + "$ref": "#/components/schemas/error" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + requestBody: + required: true + content: + application/json: + schema: + 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. + example: ext-123 + user: + 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. + 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. + example: Customer is requesting a refund and is frustrated. + oneOf: + - required: + - conversation_id + - required: + - user + examples: + Escalate an existing conversation: + value: + conversation_id: ext-123 + context: Customer is requesting a refund and is frustrated. + Escalate on behalf of a user: + value: + user: + id: '123456' + name: John Doe + email: john.doe@example.com + context: I need help with my billing issue "/export/workflows/{id}": get: summary: Export a workflow @@ -24780,7 +25447,7 @@ tags:   - Integration is centered around two endpoints (`/fin/start` and `/fin/reply`) and a set of events that notify your application of Fin's status and responses. Events can be delivered via webhooks or Server-Sent Events (SSE). You can also record a customer satisfaction rating with `/fin/csat`. + Integration centres on the Fin Agent API endpoints — start a conversation with `/fin/start` and continue it with `/fin/reply`, or drive Fin from your own agent with `/fin/capabilities`, `/fin/ask`, `/fin/procedures/{procedure_id}/run`, and `/fin/escalate` — plus a set of events that notify your application of Fin's status and responses. Events can be delivered via webhooks or Server-Sent Events (SSE). You can also record a customer satisfaction rating with `/fin/csat`.   diff --git a/descriptions/2.16/api.intercom.io.yaml b/descriptions/2.16/api.intercom.io.yaml index 339239b7..d6a70646 100644 --- a/descriptions/2.16/api.intercom.io.yaml +++ b/descriptions/2.16/api.intercom.io.yaml @@ -4471,6 +4471,673 @@ paths: conversation_id: ext-123 rating: amazing remark: Fin solved my problem in seconds. + "/fin/capabilities": + post: + summary: Discover Fin's capabilities + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + tags: + - Fin Agent + operationId: listFinCapabilities + description: | + Return a machine-readable, per-user list of what Fin can do for a given end user, so an + orchestrating agent can decide which endpoint to call. + + The response is audience-matched to the supplied user: each live, API-triggerable + procedure is checked against that user before being included, alongside the static + `reply` and `ask` actions. + responses: + '200': + description: Capabilities returned successfully + content: + application/json: + examples: + Successful response: + value: + version: "2.16" + capabilities: + - type: procedure + id: '12345' + name: Reset password + description: Walk the user through resetting their password. + endpoint: /fin/procedures/12345/run + method: POST + - type: reply + description: Reply to an in-progress Fin conversation. + endpoint: /fin/reply + method: POST + - type: ask + description: Ask Fin a single, self-contained question. + endpoint: /fin/ask + method: POST + schema: + type: object + properties: + version: + type: string + description: The API version the capabilities document was generated for. + example: "2.16" + capabilities: + type: array + description: The list of capabilities available to this user. + items: + type: object + properties: + type: + type: string + description: The kind of capability — `procedure` for a runnable procedure, or a static action such as `reply`, `ask`, or `escalate`. + example: procedure + id: + type: string + description: The procedure ID. Present only when `type` is `procedure`. + example: '12345' + name: + type: string + description: The procedure name. Present only when `type` is `procedure`. + example: Reset password + description: + type: string + description: A human-readable description of the capability. + example: Walk the user through resetting their password. + endpoint: + type: string + description: The endpoint path to call to use this capability. + example: /fin/procedures/12345/run + method: + type: string + description: The HTTP method to use. + example: POST + '400': + description: Bad Request + content: + application/json: + examples: + Too many attributes: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: parameter_invalid + message: Cannot update more than 10 attributes at once. + schema: + "$ref": "#/components/schemas/error" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + user: + allOf: + - "$ref": "#/components/schemas/fin_agent_user" + - description: The user to list capabilities for. If no user exists for the id, one is created from the supplied details; if the user already exists, the supplied email and attributes update it. + required: + - user + examples: + Capabilities for a user: + value: + user: + id: '123456' + "/fin/ask": + post: + summary: Ask Fin + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + tags: + - Fin Agent + operationId: askFin + description: | + Ask Fin a single, self-contained question and receive one informational answer. + + Unlike a conversation, `/fin/ask` is non-conversational: Fin will not ask follow-up + questions, will not run procedures, and will not escalate to a human on its own. You can + still escalate one yourself with `POST /fin/escalate`; the ask conversation is already + closed after its one-shot answer, and escalation leaves it closed while routing the + handoff separately. + + Fin's answer is delivered asynchronously via the `fin_replied` event. The conversation + ends with a `complete` status — there is no `awaiting_user_reply` cycle. + responses: + '200': + description: Question accepted successfully + content: + application/json: + examples: + Successful response: + value: + conversation_id: ext-123 + intercom_conversation_id: '192837465' + user_id: user-456 + status: thinking + created_at_ms: '2025-01-24T10:00:00.123Z' + sse_subscription_url: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m' + Response with attribute errors: + value: + conversation_id: ext-123 + intercom_conversation_id: '192837465' + user_id: user-456 + status: thinking + created_at_ms: '2025-01-24T10:00:00.123Z' + sse_subscription_url: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m' + errors: + user: + attributes: + invalid_attr: User attribute 'invalid_attr' does not exist + schema: + type: object + properties: + conversation_id: + type: string + description: The external ID of the conversation. + example: ext-123 + intercom_conversation_id: + type: string + description: The internal Intercom conversation ID, useful for matching this Agent API session to the conversation in Intercom. + example: '192837465' + user_id: + type: string + description: The ID of the user. + example: user-456 + status: + type: string + enum: + - thinking + - replying + - resolved + - complete + description: | + Fin's current status in the conversation workflow. + example: thinking + created_at_ms: + type: string + format: date-time + description: The timestamp the response was created at, with millisecond precision. + example: '2025-01-24T10:00:00.123Z' + errors: + "$ref": "#/components/schemas/fin_agent_attribute_errors" + sse_subscription_url: + type: string + description: | + Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to complete status. When CSAT is enabled and a survey will follow the resolution, `complete` revocation is deferred until the `csat_requested` event is delivered or the token expires. + example: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m' + '400': + description: Bad Request + content: + application/json: + examples: + Conversation ID missing: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: parameter_invalid + message: External Conversation ID is required + User ID missing: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: parameter_invalid + message: User ID is required + Too many history items: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: parameter_invalid + message: Conversation history cannot contain more than 10 items + schema: + "$ref": "#/components/schemas/error" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + conversation_id: + type: string + description: Your external conversation ID. Fin creates a conversation for this ID. If a conversation already exists for it, use `/fin/reply` instead. + example: ext-123 + message: + "$ref": "#/components/schemas/fin_agent_message" + user: + "$ref": "#/components/schemas/fin_agent_user" + conversation_metadata: + "$ref": "#/components/schemas/fin_agent_conversation_metadata" + attachments: + type: array + description: An array of attachments to include with the message. Maximum of 10 attachments. + maxItems: 10 + items: + "$ref": "#/components/schemas/fin_agent_attachment" + required: + - conversation_id + - message + - user + examples: + Basic question: + value: + conversation_id: ext-123 + message: + author: user + body: How do I reset my password? + timestamp: '2025-01-24T10:01:20.000Z' + user: + id: '123456' + name: John Doe + email: john.doe@example.com + Question with history and attributes: + value: + conversation_id: ext-123 + message: + author: user + body: And how long does that take to apply? + timestamp: '2025-01-24T10:02:00.000Z' + user: + id: '123456' + name: John Doe + email: john.doe@example.com + attributes: + plan_type: Pro + conversation_metadata: + history: + - author: user + body: How do I reset my password? + timestamp: '2025-01-24T10:01:20.000Z' + attributes: + order_id: '98765' + "/fin/procedures/{procedure_id}/run": + post: + summary: Run a Fin procedure + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + - name: procedure_id + in: path + required: true + description: The ID of the procedure to run. + schema: + type: string + example: '12345' + tags: + - Fin Agent + operationId: runFinProcedure + description: | + Deterministically run a specific procedure on a new conversation. Calling this endpoint + guarantees that the named procedure runs — there is no non-deterministic routing. + + Fin's progress is delivered asynchronously via events or Server-Sent Events. If the + procedure pauses for user input, the conversation status becomes `awaiting_user_reply` — + send the user's response with [`/fin/reply`](/docs/references/rest-api/api.intercom.io/fin-agent/replytofin). + responses: + '200': + description: Procedure run started successfully + content: + application/json: + examples: + Successful response: + value: + conversation_id: ext-123 + intercom_conversation_id: '192837465' + user_id: user-456 + procedure_id: '12345' + status: thinking + created_at_ms: '2025-01-24T10:00:00.123Z' + sse_subscription_url: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m' + Response with attribute errors: + value: + conversation_id: ext-123 + intercom_conversation_id: '192837465' + user_id: user-456 + procedure_id: '12345' + status: thinking + created_at_ms: '2025-01-24T10:00:00.123Z' + sse_subscription_url: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m' + errors: + user: + attributes: + invalid_attr: User attribute 'invalid_attr' does not exist + schema: + type: object + properties: + conversation_id: + type: string + description: The ID of the conversation. + example: ext-123 + intercom_conversation_id: + type: string + description: The internal Intercom conversation ID, useful for matching this Agent API session to the conversation in Intercom. + example: '192837465' + user_id: + type: string + description: The ID of the user. + example: user-456 + procedure_id: + type: string + description: The ID of the procedure that was run. + example: '12345' + status: + type: string + enum: + - thinking + - replying + - awaiting_user_reply + - escalated + - resolved + - complete + description: | + Fin's current status in the conversation workflow. + example: thinking + created_at_ms: + type: string + format: date-time + description: The timestamp the response was created at, with millisecond precision. + example: '2025-01-24T10:00:00.123Z' + errors: + "$ref": "#/components/schemas/fin_agent_attribute_errors" + sse_subscription_url: + type: string + description: | + Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. When CSAT is enabled and a survey will follow the resolution, `complete` revocation is deferred until the `csat_requested` event is delivered or the token expires. + example: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m' + '400': + description: Bad Request + content: + application/json: + examples: + Procedure not found: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: parameter_invalid + message: Procedure not found + Procedure not live: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: parameter_invalid + message: Procedure is not live + Procedure has no API trigger: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: parameter_invalid + message: Procedure does not have an API trigger + No Fin profile: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: parameter_invalid + message: No Fin profile is configured to handle this conversation. Configure a Fin profile and retry. + Conversation already exists: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: parameter_invalid + message: Fin session already exists for this conversation. Please use /reply to continue the conversation. + schema: + "$ref": "#/components/schemas/error" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + conversation_id: + type: string + description: Your external conversation ID. Fin creates a conversation for this ID. If a conversation already exists for it, use `/fin/reply` instead. + example: ext-123 + user: + "$ref": "#/components/schemas/fin_agent_user" + message: + "$ref": "#/components/schemas/fin_agent_message" + conversation_metadata: + type: object + description: Metadata about the conversation. Only attributes are accepted (no history). + properties: + attributes: + type: object + description: | + A hash of conversation attributes. Limit to 10 attributes. + additionalProperties: true + example: + order_id: '98765' + required: + - conversation_id + - user + examples: + Basic procedure run: + value: + conversation_id: ext-123 + user: + id: '123456' + name: John Doe + email: john.doe@example.com + Procedure run with trigger message and attributes: + value: + conversation_id: ext-123 + user: + id: '123456' + name: John Doe + email: john.doe@example.com + message: + author: agent + body: Starting your refund request. + conversation_metadata: + attributes: + order_id: '98765' + "/fin/escalate": + post: + summary: Escalate to a human + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + tags: + - Fin Agent + operationId: escalateFinConversation + description: | + Hand a conversation off to a human teammate. If you use the Intercom Helpdesk, the + handoff lands in your team inbox. + + Provide either `conversation_id` or `user`: + + - `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. + Escalation does not change the original agent conversation's assignment or open/closed + state. 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. Not supported on Fin + for Platforms — see below. + + 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 + resolution state, not a billable resolution. + + 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. `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, 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 + content: + application/json: + examples: + Existing conversation: + value: + conversation_id: ext-123 + status: escalated + sse_subscription_url: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m' + New conversation: + value: + intercom_conversation_id: '987654321' + status: escalated + schema: + type: object + properties: + conversation_id: + type: string + description: The external ID of the conversation. Returned when you escalate an existing conversation by `conversation_id` (echoed back). When you escalate a `user`, a new conversation is created and only `intercom_conversation_id` is returned. + example: ext-123 + intercom_conversation_id: + type: string + description: The internal Intercom conversation ID. Returned when a new conversation was created for the escalation. + example: '987654321' + sse_subscription_url: + type: string + description: | + Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to complete status. When CSAT is enabled and a survey will follow the resolution, `complete` revocation is deferred until the `csat_requested` event is delivered or the token expires. Includes a `rewind` window so a subscriber that connects after the escalation is processed can still receive the `escalated` and `complete` events. + example: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m' + status: + type: string + enum: + - escalated + description: The resulting status of the conversation. + example: escalated + '400': + description: Bad Request + content: + application/json: + examples: + Neither identifier provided: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: parameter_invalid + message: Either conversation_id or user must be provided + Conversation not found: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: parameter_invalid + message: Conversation not found + schema: + "$ref": "#/components/schemas/error" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + requestBody: + required: true + content: + application/json: + schema: + 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. + example: ext-123 + user: + 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. + 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. + example: Customer is requesting a refund and is frustrated. + oneOf: + - required: + - conversation_id + - required: + - user + examples: + Escalate an existing conversation: + value: + conversation_id: ext-123 + context: Customer is requesting a refund and is frustrated. + Escalate on behalf of a user: + value: + user: + id: '123456' + name: John Doe + email: john.doe@example.com + context: I need help with my billing issue "/help_center/help_centers/{help_center_id}/redirects": get: summary: List all redirects for a help center @@ -35741,7 +36408,7 @@ tags:   - Integration is centered around two endpoints (`/fin/start` and `/fin/reply`) and a set of events that notify your application of Fin's status and responses. Events can be delivered via webhooks or Server-Sent Events (SSE). You can also record a customer satisfaction rating with `/fin/csat`. + Integration centres on the Fin Agent API endpoints — start a conversation with `/fin/start` and continue it with `/fin/reply`, or drive Fin from your own agent with `/fin/capabilities`, `/fin/ask`, `/fin/procedures/{procedure_id}/run`, and `/fin/escalate` — plus a set of events that notify your application of Fin's status and responses. Events can be delivered via webhooks or Server-Sent Events (SSE). You can also record a customer satisfaction rating with `/fin/csat`.