From 6e23b9f69f40e19cb34be79d0c7a70ae2be12703 Mon Sep 17 00:00:00 2001 From: Karim Frenn Date: Wed, 21 Oct 2026 12:59:37 +0100 Subject: [PATCH] Remove SSE and streaming from Fin Agent API spec Fin Agent API events are documented as delivered via webhooks only. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01D2ZtwrAtSRibMrC8CLHekH --- descriptions/0/api.intercom.io.yaml | 119 ++-------------- descriptions/2.14/api.intercom.io.yaml | 127 ++---------------- descriptions/2.15/api.intercom.io.yaml | 127 ++---------------- descriptions/2.16/api.intercom.io.yaml | 127 ++---------------- descriptions/2.17/api.intercom.io.yaml | 127 ++---------------- .../intercom-api.postman_collection.json | 4 +- 6 files changed, 50 insertions(+), 581 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index c8e4f160..a3ef304c 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -28321,7 +28321,6 @@ paths: 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 @@ -28329,7 +28328,6 @@ paths: 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: @@ -28366,11 +28364,6 @@ paths: 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: @@ -28508,7 +28501,6 @@ paths: 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...' Response with attribute errors: value: conversation_id: ext-123 @@ -28516,7 +28508,6 @@ paths: 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...' errors: user: attributes: @@ -28555,11 +28546,6 @@ paths: 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...' '400': description: Bad Request content: @@ -28661,7 +28647,7 @@ paths: 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 + Fin's progress is delivered asynchronously via 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/preview/rest-api/api.intercom.io/fin-agent/replytofin). @@ -28682,7 +28668,6 @@ paths: 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 @@ -28691,7 +28676,6 @@ paths: 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: @@ -28734,11 +28718,6 @@ paths: 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: @@ -28891,7 +28870,7 @@ paths: 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 + You are notified via webhooks 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. @@ -28909,7 +28888,6 @@ paths: 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' @@ -28925,11 +28903,6 @@ paths: 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: @@ -29024,8 +28997,8 @@ paths: remark. Fin decides *when* to ask for a rating — this reuses the CSAT settings on your Fin - workflow, not this API. When Fin asks, it fires a `csat_requested` event over webhooks or - SSE carrying the rating options to show the user. Present those options, then submit the + workflow, not this API. When Fin asks, it fires a `csat_requested` event over webhooks + carrying the rating options to show the user. Present those options, then submit the user's choice here. Submitting the same rating again, with no new remark, is a no-op and stays successful, @@ -29189,8 +29162,6 @@ paths: During this workflow, the client should allow Fin to continue uninterrupted until a final *complete* status is returned, at which point control of the conversation passes back to the client. - Events can be received via webhooks or Server-Sent Events (SSE) using the `sse_subscription_url` in the response. - {% admonition type="warning" %} To 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**. {% /admonition %} @@ -29207,7 +29178,6 @@ paths: 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 @@ -29215,7 +29185,6 @@ paths: 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: @@ -29257,11 +29226,6 @@ paths: 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: @@ -41621,7 +41585,7 @@ components: - awaiting_user_reply: Fin has finished replying and is waiting for the user to respond - escalated: The conversation has been escalated to a human - resolved: The user's query has been resolved - - complete: Fin has completed its workflow. When CSAT is enabled a csat_requested event may follow, in which case the SSE stream is held open past complete until it is delivered or the token expires + - complete: Fin has completed its workflow. When CSAT is enabled a csat_requested event may follow example: escalated reason: type: string @@ -41739,13 +41703,6 @@ components: - replying: Intermediate reply part; more parts may follow - awaiting_user_reply: Legacy status; instead use the fin_status_updated event with 'awaiting_user_reply', which fires once Fin's reply is done example: replying - stream_id: - type: string - description: | - Optional. Present when the reply was generated via streaming. - Correlates this event with the fin_reply_chunk events that preceded it. - Use this to know when to replace streamed chunk_text with the final message body. - example: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 created_at_ms: type: string format: date-time @@ -41758,73 +41715,14 @@ components: - message - status - created_at_ms - fin_agent_reply_chunk_event: - title: Fin Agent Reply Chunk Event - type: object - description: | - SSE-only event fired during streaming reply generation. - Each chunk contains the full accumulated plain text of Fin's answer so far (cumulative, not a delta). - Only delivered over SSE when streaming is enabled. Not available via webhooks. - When the fin_replied event arrives with the same stream_id, replace streamed text with the final HTML body. - x-tags: - - Fin Agent - properties: - event_name: - type: string - enum: - - fin_reply_chunk - description: The name of the event. - example: fin_reply_chunk - conversation_id: - type: string - description: The ID of the conversation. - example: '123456' - stream_id: - type: string - description: | - A unique identifier for this streaming response. - Correlates chunks with each other and with the eventual fin_replied event. - example: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 - chunk_index: - type: integer - description: | - 0-based counter for this chunk within the stream. Contiguous. - example: 3 - chunk_text: - type: string - description: | - The full accumulated plain text of Fin's answer so far. - Each chunk supersedes the previous — replace rather than append. - example: You can see your account details by clicking - status: - type: string - enum: - - replying - description: Fin's current status (always 'replying' for this event). - example: replying - created_at_ms: - type: string - format: date-time - description: The timestamp the event was created at, with millisecond precision. - example: '2025-01-24T10:00:00.123Z' - required: - - event_name - - conversation_id - - stream_id - - chunk_index - - chunk_text - - created_at_ms fin_agent_csat_requested_event: title: Fin Agent CSAT Requested Event type: object description: | Event fired when Fin asks the user to rate the conversation. - Delivered via webhooks or SSE. Carries the rating options to present to the user; submit + Delivered via webhooks. Carries the rating options to present to the user; submit the user's choice with POST /fin/csat. Unlike the reply events it has no message — a rating survey is a set of options to choose from, not readable text. - Over SSE this event arrives after Fin reaches 'complete'. Because a survey is expected, - 'complete' does not close the stream: the connection is held open so this event can be - delivered, and the token is revoked once it is sent. x-tags: - Fin Agent properties: @@ -47142,7 +47040,7 @@ tags:   - Orchestrate Fin from your own agent: discover what Fin can do with `/fin/capabilities`, ask a one-shot question with `/fin/ask`, run a specific procedure with `/fin/procedures/{procedure_id}/run`, continue a conversation with `/fin/reply`, escalate to a human with `/fin/escalate`, and record a satisfaction rating with `/fin/csat`. Fin notifies your application of its status and responses through a set of events, delivered via webhooks or Server-Sent Events (SSE). + Orchestrate Fin from your own agent: discover what Fin can do with `/fin/capabilities`, ask a one-shot question with `/fin/ask`, run a specific procedure with `/fin/procedures/{procedure_id}/run`, continue a conversation with `/fin/reply`, escalate to a human with `/fin/escalate`, and record a satisfaction rating with `/fin/csat`. Fin notifies your application of its status and responses through a set of events, delivered via webhooks.   @@ -47152,11 +47050,10 @@ tags: **Events** - Configure a webhook endpoint in the Fin Agent API settings to receive events, or use the `sse_subscription_url` from the API response to subscribe via SSE. See the [setup guide](/docs/guides/fin-agent-api/setup) for configuration details. + Configure a webhook endpoint in the Fin Agent API settings to receive events. See the [setup guide](/docs/guides/fin-agent-api/setup) for configuration details. - `fin_status_updated` - Fired when Fin's status changes (awaiting_user_reply, escalated, resolved, complete) - `fin_replied` - Fired when Fin sends a reply to the user - - `fin_reply_chunk` - SSE-only streaming event fired during reply generation (requires streaming enabled) - `csat_requested` - Fired when Fin asks the user to rate the conversation (submit the choice with `POST /fin/csat`) All webhook requests include an `X-Fin-Agent-API-Webhook-Signature` header for request validation. diff --git a/descriptions/2.14/api.intercom.io.yaml b/descriptions/2.14/api.intercom.io.yaml index 8f2f2544..a80a08bf 100644 --- a/descriptions/2.14/api.intercom.io.yaml +++ b/descriptions/2.14/api.intercom.io.yaml @@ -1848,7 +1848,6 @@ paths: 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 @@ -1856,7 +1855,6 @@ paths: 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: @@ -1897,11 +1895,6 @@ paths: 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: @@ -2048,7 +2041,6 @@ paths: 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...' Response with attribute errors: value: conversation_id: ext-123 @@ -2056,7 +2048,6 @@ paths: 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...' errors: user: attributes: @@ -2094,11 +2085,6 @@ paths: 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...' '400': description: Bad Request content: @@ -2194,8 +2180,8 @@ paths: remark. Fin decides *when* to ask for a rating — this reuses the CSAT settings on your Fin - workflow, not this API. When Fin asks, it fires a `csat_requested` event over webhooks or - SSE carrying the rating options to show the user. Present those options, then submit the + workflow, not this API. When Fin asks, it fires a `csat_requested` event over webhooks + carrying the rating options to show the user. Present those options, then submit the user's choice here. Submitting the same rating again, with no new remark, is a no-op and stays successful, @@ -2500,7 +2486,6 @@ paths: 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 @@ -2508,7 +2493,6 @@ paths: 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: @@ -2545,11 +2529,6 @@ paths: 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: @@ -2677,7 +2656,7 @@ paths: 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 + Fin's progress is delivered asynchronously via 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). @@ -2698,7 +2677,6 @@ paths: 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 @@ -2707,7 +2685,6 @@ paths: 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: @@ -2750,11 +2727,6 @@ paths: 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: @@ -2907,7 +2879,7 @@ paths: 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 + You are notified via webhooks 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. @@ -2925,7 +2897,6 @@ paths: 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' @@ -2941,11 +2912,6 @@ paths: 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: @@ -20937,7 +20903,7 @@ components: type: object description: | Event fired when Fin's status changes during a conversation. - Delivered via webhooks or SSE. Fin will report its status to the client via this event. + Delivered via webhooks. Fin will report its status to the client via this event. x-tags: - Fin Agent properties: @@ -20965,7 +20931,7 @@ components: Fin's current status. - escalated: The conversation has been escalated to a human - resolved: The user's query has been resolved - - complete: Fin has completed its workflow. When CSAT is enabled a csat_requested event may follow, in which case the SSE stream is held open past complete until it is delivered or the token expires + - complete: Fin has completed its workflow. When CSAT is enabled a csat_requested event may follow example: escalated reason: type: string @@ -20995,7 +20961,7 @@ components: type: object description: | Event fired when Fin replies to a user. - Delivered via webhooks or SSE. The content of the response will be contained in the message object. + Delivered via webhooks. The content of the response will be contained in the message object. Fin's status will update to 'awaiting_user_reply'. x-tags: - Fin Agent @@ -21078,13 +21044,6 @@ components: - awaiting_user_reply description: Fin's current status (always 'awaiting_user_reply' for this event). example: awaiting_user_reply - stream_id: - type: string - description: | - Optional. Present when the reply was generated via streaming. - Correlates this event with the fin_reply_chunk events that preceded it. - Use this to know when to replace streamed chunk_text with the final message body. - example: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 created_at_ms: type: string format: date-time @@ -21097,73 +21056,14 @@ components: - message - status - created_at_ms - fin_agent_reply_chunk_event: - title: Fin Agent Reply Chunk Event - type: object - description: | - SSE-only event fired during streaming reply generation. - Each chunk contains the full accumulated plain text of Fin's answer so far (cumulative, not a delta). - Only delivered over SSE when streaming is enabled. Not available via webhooks. - When the fin_replied event arrives with the same stream_id, replace streamed text with the final HTML body. - x-tags: - - Fin Agent - properties: - event_name: - type: string - enum: - - fin_reply_chunk - description: The name of the event. - example: fin_reply_chunk - conversation_id: - type: string - description: The ID of the conversation. - example: '123456' - stream_id: - type: string - description: | - A unique identifier for this streaming response. - Correlates chunks with each other and with the eventual fin_replied event. - example: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 - chunk_index: - type: integer - description: | - 0-based counter for this chunk within the stream. Contiguous. - example: 3 - chunk_text: - type: string - description: | - The full accumulated plain text of Fin's answer so far. - Each chunk supersedes the previous — replace rather than append. - example: You can see your account details by clicking - status: - type: string - enum: - - replying - description: Fin's current status (always 'replying' for this event). - example: replying - created_at_ms: - type: string - format: date-time - description: The timestamp the event was created at, with millisecond precision. - example: '2025-01-24T10:00:00.123Z' - required: - - event_name - - conversation_id - - stream_id - - chunk_index - - chunk_text - - created_at_ms fin_agent_csat_requested_event: title: Fin Agent CSAT Requested Event type: object description: | Event fired when Fin asks the user to rate the conversation. - Delivered via webhooks or SSE. Carries the rating options to present to the user; submit + Delivered via webhooks. Carries the rating options to present to the user; submit the user's choice with POST /fin/csat. Unlike the reply events it has no message — a rating survey is a set of options to choose from, not readable text. - Over SSE this event arrives after Fin reaches 'complete'. Because a survey is expected, - 'complete' does not close the stream: the connection is held open so this event can be - delivered, and the token is revoked once it is sent. x-tags: - Fin Agent properties: @@ -24413,13 +24313,7 @@ tags:   - {% admonition type="warning" %} - Server-Sent Events (SSE) is available by application only. Contact your account team or Customer Support to request access. - {% /admonition %} - -   - - 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`. + 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 are delivered via webhooks. You can also record a customer satisfaction rating with `/fin/csat`.   @@ -24431,11 +24325,10 @@ tags: **Events** - Configure a webhook endpoint in the Fin Agent API settings to receive events, or use the `sse_subscription_url` from the API response to subscribe via SSE. See the [setup guide](/docs/guides/fin-agent-api/setup) for configuration details. + Configure a webhook endpoint in the Fin Agent API settings to receive events. See the [setup guide](/docs/guides/fin-agent-api/setup) for configuration details. - `fin_status_updated` - Fired when Fin's status changes (escalated, resolved, complete) - `fin_replied` - Fired when Fin sends a reply to the user - - `fin_reply_chunk` - SSE-only streaming event fired during reply generation (requires streaming enabled) - `csat_requested` - Fired when Fin asks the user to rate the conversation (submit the choice with `POST /fin/csat`) All webhook requests include an `X-Fin-Agent-API-Webhook-Signature` header for request validation. diff --git a/descriptions/2.15/api.intercom.io.yaml b/descriptions/2.15/api.intercom.io.yaml index 4e731623..d5b6112f 100644 --- a/descriptions/2.15/api.intercom.io.yaml +++ b/descriptions/2.15/api.intercom.io.yaml @@ -1854,7 +1854,6 @@ paths: 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 @@ -1862,7 +1861,6 @@ paths: 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: @@ -1903,11 +1901,6 @@ paths: 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: @@ -2054,7 +2047,6 @@ paths: 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...' Response with attribute errors: value: conversation_id: ext-123 @@ -2062,7 +2054,6 @@ paths: 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...' errors: user: attributes: @@ -2100,11 +2091,6 @@ paths: 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...' '400': description: Bad Request content: @@ -14998,8 +14984,8 @@ paths: remark. Fin decides *when* to ask for a rating — this reuses the CSAT settings on your Fin - workflow, not this API. When Fin asks, it fires a `csat_requested` event over webhooks or - SSE carrying the rating options to show the user. Present those options, then submit the + workflow, not this API. When Fin asks, it fires a `csat_requested` event over webhooks + carrying the rating options to show the user. Present those options, then submit the user's choice here. Submitting the same rating again, with no new remark, is a no-op and stays successful, @@ -15304,7 +15290,6 @@ paths: 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 @@ -15312,7 +15297,6 @@ paths: 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: @@ -15349,11 +15333,6 @@ paths: 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: @@ -15481,7 +15460,7 @@ paths: 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 + Fin's progress is delivered asynchronously via 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). @@ -15502,7 +15481,6 @@ paths: 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 @@ -15511,7 +15489,6 @@ paths: 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: @@ -15554,11 +15531,6 @@ paths: 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: @@ -15711,7 +15683,7 @@ paths: 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 + You are notified via webhooks 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. @@ -15729,7 +15701,6 @@ paths: 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' @@ -15745,11 +15716,6 @@ paths: 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: @@ -21865,7 +21831,7 @@ components: type: object description: | Event fired when Fin's status changes during a conversation. - Delivered via webhooks or SSE. Fin will report its status to the client via this event. + Delivered via webhooks. Fin will report its status to the client via this event. x-tags: - Fin Agent properties: @@ -21893,7 +21859,7 @@ components: Fin's current status. - escalated: The conversation has been escalated to a human - resolved: The user's query has been resolved - - complete: Fin has completed its workflow. When CSAT is enabled a csat_requested event may follow, in which case the SSE stream is held open past complete until it is delivered or the token expires + - complete: Fin has completed its workflow. When CSAT is enabled a csat_requested event may follow example: escalated reason: type: string @@ -21923,7 +21889,7 @@ components: type: object description: | Event fired when Fin replies to a user. - Delivered via webhooks or SSE. The content of the response will be contained in the message object. + Delivered via webhooks. The content of the response will be contained in the message object. Fin's status will update to 'awaiting_user_reply'. x-tags: - Fin Agent @@ -22006,13 +21972,6 @@ components: - awaiting_user_reply description: Fin's current status (always 'awaiting_user_reply' for this event). example: awaiting_user_reply - stream_id: - type: string - description: | - Optional. Present when the reply was generated via streaming. - Correlates this event with the fin_reply_chunk events that preceded it. - Use this to know when to replace streamed chunk_text with the final message body. - example: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 created_at_ms: type: string format: date-time @@ -22025,73 +21984,14 @@ components: - message - status - created_at_ms - fin_agent_reply_chunk_event: - title: Fin Agent Reply Chunk Event - type: object - description: | - SSE-only event fired during streaming reply generation. - Each chunk contains the full accumulated plain text of Fin's answer so far (cumulative, not a delta). - Only delivered over SSE when streaming is enabled. Not available via webhooks. - When the fin_replied event arrives with the same stream_id, replace streamed text with the final HTML body. - x-tags: - - Fin Agent - properties: - event_name: - type: string - enum: - - fin_reply_chunk - description: The name of the event. - example: fin_reply_chunk - conversation_id: - type: string - description: The ID of the conversation. - example: '123456' - stream_id: - type: string - description: | - A unique identifier for this streaming response. - Correlates chunks with each other and with the eventual fin_replied event. - example: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 - chunk_index: - type: integer - description: | - 0-based counter for this chunk within the stream. Contiguous. - example: 3 - chunk_text: - type: string - description: | - The full accumulated plain text of Fin's answer so far. - Each chunk supersedes the previous — replace rather than append. - example: You can see your account details by clicking - status: - type: string - enum: - - replying - description: Fin's current status (always 'replying' for this event). - example: replying - created_at_ms: - type: string - format: date-time - description: The timestamp the event was created at, with millisecond precision. - example: '2025-01-24T10:00:00.123Z' - required: - - event_name - - conversation_id - - stream_id - - chunk_index - - chunk_text - - created_at_ms fin_agent_csat_requested_event: title: Fin Agent CSAT Requested Event type: object description: | Event fired when Fin asks the user to rate the conversation. - Delivered via webhooks or SSE. Carries the rating options to present to the user; submit + Delivered via webhooks. Carries the rating options to present to the user; submit the user's choice with POST /fin/csat. Unlike the reply events it has no message — a rating survey is a set of options to choose from, not readable text. - Over SSE this event arrives after Fin reaches 'complete'. Because a survey is expected, - 'complete' does not close the stream: the connection is held open so this event can be - delivered, and the token is revoked once it is sent. x-tags: - Fin Agent properties: @@ -25541,13 +25441,7 @@ tags:   - {% admonition type="warning" %} - Server-Sent Events (SSE) is available by application only. Contact your account team or Customer Support to request access. - {% /admonition %} - -   - - 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`. + 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 are delivered via webhooks. You can also record a customer satisfaction rating with `/fin/csat`.   @@ -25559,11 +25453,10 @@ tags: **Events** - Configure a webhook endpoint in the Fin Agent API settings to receive events, or use the `sse_subscription_url` from the API response to subscribe via SSE. See the [setup guide](/docs/guides/fin-agent-api/setup) for configuration details. + Configure a webhook endpoint in the Fin Agent API settings to receive events. See the [setup guide](/docs/guides/fin-agent-api/setup) for configuration details. - `fin_status_updated` - Fired when Fin's status changes (escalated, resolved, complete) - `fin_replied` - Fired when Fin sends a reply to the user - - `fin_reply_chunk` - SSE-only streaming event fired during reply generation (requires streaming enabled) - `csat_requested` - Fired when Fin asks the user to rate the conversation (submit the choice with `POST /fin/csat`) All webhook requests include an `X-Fin-Agent-API-Webhook-Signature` header for request validation. diff --git a/descriptions/2.16/api.intercom.io.yaml b/descriptions/2.16/api.intercom.io.yaml index b8c337b7..1e86c398 100644 --- a/descriptions/2.16/api.intercom.io.yaml +++ b/descriptions/2.16/api.intercom.io.yaml @@ -4007,7 +4007,6 @@ paths: 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 @@ -4015,7 +4014,6 @@ paths: 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: @@ -4057,11 +4055,6 @@ paths: 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: @@ -4208,7 +4201,6 @@ paths: 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...' Response with attribute errors: value: conversation_id: ext-123 @@ -4216,7 +4208,6 @@ paths: 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...' errors: user: attributes: @@ -4255,11 +4246,6 @@ paths: 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...' '400': description: Bad Request content: @@ -4355,8 +4341,8 @@ paths: remark. Fin decides *when* to ask for a rating — this reuses the CSAT settings on your Fin - workflow, not this API. When Fin asks, it fires a `csat_requested` event over webhooks or - SSE carrying the rating options to show the user. Present those options, then submit the + workflow, not this API. When Fin asks, it fires a `csat_requested` event over webhooks + carrying the rating options to show the user. Present those options, then submit the user's choice here. Submitting the same rating again, with no new remark, is a no-op and stays successful, @@ -4661,7 +4647,6 @@ paths: 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 @@ -4669,7 +4654,6 @@ paths: 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: @@ -4706,11 +4690,6 @@ paths: 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: @@ -4838,7 +4817,7 @@ paths: 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 + Fin's progress is delivered asynchronously via 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). @@ -4859,7 +4838,6 @@ paths: 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 @@ -4868,7 +4846,6 @@ paths: 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: @@ -4911,11 +4888,6 @@ paths: 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: @@ -5068,7 +5040,7 @@ paths: 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 + You are notified via webhooks 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. @@ -5086,7 +5058,6 @@ paths: 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' @@ -5102,11 +5073,6 @@ paths: 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: @@ -32402,7 +32368,7 @@ components: type: object description: | Event fired when Fin's status changes during a conversation. - Delivered via webhooks or SSE. Fin will report its status to the client via this event. + Delivered via webhooks. Fin will report its status to the client via this event. x-tags: - Fin Agent properties: @@ -32432,7 +32398,7 @@ components: - awaiting_user_reply: Fin has finished replying and is waiting for the user to respond - escalated: The conversation has been escalated to a human - resolved: The user's query has been resolved - - complete: Fin has completed its workflow. When CSAT is enabled a csat_requested event may follow, in which case the SSE stream is held open past complete until it is delivered or the token expires + - complete: Fin has completed its workflow. When CSAT is enabled a csat_requested event may follow example: escalated reason: type: string @@ -32462,7 +32428,7 @@ components: type: object description: | Event fired when Fin replies to a user. - Delivered via webhooks or SSE. The content of the response will be contained in the message object. + Delivered via webhooks. The content of the response will be contained in the message object. Intermediate replies have status 'replying'; a separate fin_status_updated event with 'awaiting_user_reply' fires once Fin's reply is done. x-tags: - Fin Agent @@ -32549,13 +32515,6 @@ components: - replying: Intermediate reply part; more parts may follow - awaiting_user_reply: Legacy status; instead use the fin_status_updated event with 'awaiting_user_reply', which fires once Fin's reply is done example: replying - stream_id: - type: string - description: | - Optional. Present when the reply was generated via streaming. - Correlates this event with the fin_reply_chunk events that preceded it. - Use this to know when to replace streamed chunk_text with the final message body. - example: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 created_at_ms: type: string format: date-time @@ -32568,73 +32527,14 @@ components: - message - status - created_at_ms - fin_agent_reply_chunk_event: - title: Fin Agent Reply Chunk Event - type: object - description: | - SSE-only event fired during streaming reply generation. - Each chunk contains the full accumulated plain text of Fin's answer so far (cumulative, not a delta). - Only delivered over SSE when streaming is enabled. Not available via webhooks. - When the fin_replied event arrives with the same stream_id, replace streamed text with the final HTML body. - x-tags: - - Fin Agent - properties: - event_name: - type: string - enum: - - fin_reply_chunk - description: The name of the event. - example: fin_reply_chunk - conversation_id: - type: string - description: The ID of the conversation. - example: '123456' - stream_id: - type: string - description: | - A unique identifier for this streaming response. - Correlates chunks with each other and with the eventual fin_replied event. - example: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 - chunk_index: - type: integer - description: | - 0-based counter for this chunk within the stream. Contiguous. - example: 3 - chunk_text: - type: string - description: | - The full accumulated plain text of Fin's answer so far. - Each chunk supersedes the previous — replace rather than append. - example: You can see your account details by clicking - status: - type: string - enum: - - replying - description: Fin's current status (always 'replying' for this event). - example: replying - created_at_ms: - type: string - format: date-time - description: The timestamp the event was created at, with millisecond precision. - example: '2025-01-24T10:00:00.123Z' - required: - - event_name - - conversation_id - - stream_id - - chunk_index - - chunk_text - - created_at_ms fin_agent_csat_requested_event: title: Fin Agent CSAT Requested Event type: object description: | Event fired when Fin asks the user to rate the conversation. - Delivered via webhooks or SSE. Carries the rating options to present to the user; submit + Delivered via webhooks. Carries the rating options to present to the user; submit the user's choice with POST /fin/csat. Unlike the reply events it has no message — a rating survey is a set of options to choose from, not readable text. - Over SSE this event arrives after Fin reaches 'complete'. Because a survey is expected, - 'complete' does not close the stream: the connection is held open so this event can be - delivered, and the token is revoked once it is sent. x-tags: - Fin Agent properties: @@ -36667,23 +36567,16 @@ tags:   - {% admonition type="warning" %} - Server-Sent Events (SSE) is available by application only. Contact your account team or Customer Support to request access. - {% /admonition %} - -   - - 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`. + 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 are delivered via webhooks. You can also record a customer satisfaction rating with `/fin/csat`.   **Events** - Configure a webhook endpoint in the Fin Agent API settings to receive events, or use the `sse_subscription_url` from the API response to subscribe via SSE. See the [setup guide](/docs/guides/fin-agent-api/setup) for configuration details. + Configure a webhook endpoint in the Fin Agent API settings to receive events. See the [setup guide](/docs/guides/fin-agent-api/setup) for configuration details. - `fin_status_updated` - Fired when Fin's status changes (awaiting_user_reply, escalated, resolved, complete) - `fin_replied` - Fired when Fin sends a reply to the user - - `fin_reply_chunk` - SSE-only streaming event fired during reply generation (requires streaming enabled) - `csat_requested` - Fired when Fin asks the user to rate the conversation (submit the choice with `POST /fin/csat`) All webhook requests include an `X-Fin-Agent-API-Webhook-Signature` header for request validation. diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index 9f570e75..61543628 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -4007,7 +4007,6 @@ paths: 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 @@ -4015,7 +4014,6 @@ paths: 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: @@ -4057,11 +4055,6 @@ paths: 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: @@ -4208,7 +4201,6 @@ paths: 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...' Response with attribute errors: value: conversation_id: ext-123 @@ -4216,7 +4208,6 @@ paths: 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...' errors: user: attributes: @@ -4255,11 +4246,6 @@ paths: 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...' '400': description: Bad Request content: @@ -4355,8 +4341,8 @@ paths: remark. Fin decides *when* to ask for a rating — this reuses the CSAT settings on your Fin - workflow, not this API. When Fin asks, it fires a `csat_requested` event over webhooks or - SSE carrying the rating options to show the user. Present those options, then submit the + workflow, not this API. When Fin asks, it fires a `csat_requested` event over webhooks + carrying the rating options to show the user. Present those options, then submit the user's choice here. Submitting the same rating again, with no new remark, is a no-op and stays successful, @@ -4661,7 +4647,6 @@ paths: 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 @@ -4669,7 +4654,6 @@ paths: 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: @@ -4706,11 +4690,6 @@ paths: 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: @@ -4838,7 +4817,7 @@ paths: 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 + Fin's progress is delivered asynchronously via 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). @@ -4859,7 +4838,6 @@ paths: 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 @@ -4868,7 +4846,6 @@ paths: 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: @@ -4911,11 +4888,6 @@ paths: 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: @@ -5068,7 +5040,7 @@ paths: 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 + You are notified via webhooks 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. @@ -5086,7 +5058,6 @@ paths: 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' @@ -5102,11 +5073,6 @@ paths: 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: @@ -36495,7 +36461,7 @@ components: type: object description: | Event fired when Fin's status changes during a conversation. - Delivered via webhooks or SSE. Fin will report its status to the client via this event. + Delivered via webhooks. Fin will report its status to the client via this event. x-tags: - Fin Agent properties: @@ -36525,7 +36491,7 @@ components: - awaiting_user_reply: Fin has finished replying and is waiting for the user to respond - escalated: The conversation has been escalated to a human - resolved: The user's query has been resolved - - complete: Fin has completed its workflow. When CSAT is enabled a csat_requested event may follow, in which case the SSE stream is held open past complete until it is delivered or the token expires + - complete: Fin has completed its workflow. When CSAT is enabled a csat_requested event may follow example: escalated reason: type: string @@ -36555,7 +36521,7 @@ components: type: object description: | Event fired when Fin replies to a user. - Delivered via webhooks or SSE. The content of the response will be contained in the message object. + Delivered via webhooks. The content of the response will be contained in the message object. Intermediate replies have status 'replying'; a separate fin_status_updated event with 'awaiting_user_reply' fires once Fin's reply is done. x-tags: - Fin Agent @@ -36642,13 +36608,6 @@ components: - replying: Intermediate reply part; more parts may follow - awaiting_user_reply: Legacy status; instead use the fin_status_updated event with 'awaiting_user_reply', which fires once Fin's reply is done example: replying - stream_id: - type: string - description: | - Optional. Present when the reply was generated via streaming. - Correlates this event with the fin_reply_chunk events that preceded it. - Use this to know when to replace streamed chunk_text with the final message body. - example: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 created_at_ms: type: string format: date-time @@ -36661,73 +36620,14 @@ components: - message - status - created_at_ms - fin_agent_reply_chunk_event: - title: Fin Agent Reply Chunk Event - type: object - description: | - SSE-only event fired during streaming reply generation. - Each chunk contains the full accumulated plain text of Fin's answer so far (cumulative, not a delta). - Only delivered over SSE when streaming is enabled. Not available via webhooks. - When the fin_replied event arrives with the same stream_id, replace streamed text with the final HTML body. - x-tags: - - Fin Agent - properties: - event_name: - type: string - enum: - - fin_reply_chunk - description: The name of the event. - example: fin_reply_chunk - conversation_id: - type: string - description: The ID of the conversation. - example: '123456' - stream_id: - type: string - description: | - A unique identifier for this streaming response. - Correlates chunks with each other and with the eventual fin_replied event. - example: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 - chunk_index: - type: integer - description: | - 0-based counter for this chunk within the stream. Contiguous. - example: 3 - chunk_text: - type: string - description: | - The full accumulated plain text of Fin's answer so far. - Each chunk supersedes the previous — replace rather than append. - example: You can see your account details by clicking - status: - type: string - enum: - - replying - description: Fin's current status (always 'replying' for this event). - example: replying - created_at_ms: - type: string - format: date-time - description: The timestamp the event was created at, with millisecond precision. - example: '2025-01-24T10:00:00.123Z' - required: - - event_name - - conversation_id - - stream_id - - chunk_index - - chunk_text - - created_at_ms fin_agent_csat_requested_event: title: Fin Agent CSAT Requested Event type: object description: | Event fired when Fin asks the user to rate the conversation. - Delivered via webhooks or SSE. Carries the rating options to present to the user; submit + Delivered via webhooks. Carries the rating options to present to the user; submit the user's choice with POST /fin/csat. Unlike the reply events it has no message — a rating survey is a set of options to choose from, not readable text. - Over SSE this event arrives after Fin reaches 'complete'. Because a survey is expected, - 'complete' does not close the stream: the connection is held open so this event can be - delivered, and the token is revoked once it is sent. x-tags: - Fin Agent properties: @@ -41218,23 +41118,16 @@ tags:   - {% admonition type="warning" %} - Server-Sent Events (SSE) is available by application only. Contact your account team or Customer Support to request access. - {% /admonition %} - -   - - 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`. + 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 are delivered via webhooks. You can also record a customer satisfaction rating with `/fin/csat`.   **Events** - Configure a webhook endpoint in the Fin Agent API settings to receive events, or use the `sse_subscription_url` from the API response to subscribe via SSE. See the [setup guide](/docs/guides/fin-agent-api/setup) for configuration details. + Configure a webhook endpoint in the Fin Agent API settings to receive events. See the [setup guide](/docs/guides/fin-agent-api/setup) for configuration details. - `fin_status_updated` - Fired when Fin's status changes (awaiting_user_reply, escalated, resolved, complete) - `fin_replied` - Fired when Fin sends a reply to the user - - `fin_reply_chunk` - SSE-only streaming event fired during reply generation (requires streaming enabled) - `csat_requested` - Fired when Fin asks the user to rate the conversation (submit the choice with `POST /fin/csat`) All webhook requests include an `X-Fin-Agent-API-Webhook-Signature` header for request validation. diff --git a/postman/Preview/intercom-api.postman_collection.json b/postman/Preview/intercom-api.postman_collection.json index 259ab516..350e7609 100644 --- a/postman/Preview/intercom-api.postman_collection.json +++ b/postman/Preview/intercom-api.postman_collection.json @@ -10986,7 +10986,7 @@ ] }, "method": "POST", - "description": "Deterministically run a specific procedure on a new conversation. Calling this endpoint\nguarantees that the named procedure runs — there is no non-deterministic routing.\n\nFin's progress is delivered asynchronously via events or Server-Sent Events. If the\nprocedure pauses for user input, the conversation status becomes `awaiting_user_reply` —\nsend the user's response with [`/fin/reply`](/docs/references/preview/rest-api/api.intercom.io/fin-agent/replytofin).\n\n{% admonition type=\"warning\" %}\nTo request access to the Fin Agent API, please [fill out this form](https://forms.gle/osy4uyiqyomRCsL2A).\n{% /admonition %}\n", + "description": "Deterministically run a specific procedure on a new conversation. Calling this endpoint\nguarantees that the named procedure runs — there is no non-deterministic routing.\n\nFin's progress is delivered asynchronously via events. If the\nprocedure pauses for user input, the conversation status becomes `awaiting_user_reply` —\nsend the user's response with [`/fin/reply`](/docs/references/preview/rest-api/api.intercom.io/fin-agent/replytofin).\n\n{% admonition type=\"warning\" %}\nTo request access to the Fin Agent API, please [fill out this form](https://forms.gle/osy4uyiqyomRCsL2A).\n{% /admonition %}\n", "header": [ { "key": "Intercom-Version", @@ -11178,7 +11178,7 @@ ] }, "method": "POST", - "description": "{% admonition type=\"info\" name=\"Legacy — conversational mode\" %}\n`/fin/start` powers the conversational model, where your own UI drives a back-and-forth with Fin. This endpoint is no longer actively developed and is maintained only for existing integrations — new functionality lands on the orchestration endpoints.\n{% /admonition %}\n\nInitialize Fin by passing it the user's message along with conversation history and user details.\n\nThese additional pieces of context will be used by Fin to provide a better and more contextual answer to the user.\n\nOnce Fin is initialized, it progresses through a series of statuses such as *thinking*, *replying*, *awaiting_user_reply*, or *resolved* before ending with a status of *complete*.\n\nDuring this workflow, the client should allow Fin to continue uninterrupted until a final *complete* status is returned, at which point control of the conversation passes back to the client.\n\nEvents can be received via webhooks or Server-Sent Events (SSE) using the `sse_subscription_url` in the response.\n\n{% admonition type=\"warning\" %}\nTo request access to the Fin Agent API, please [fill out this form](https://forms.gle/osy4uyiqyomRCsL2A).\n{% /admonition %}\n", + "description": "{% admonition type=\"info\" name=\"Legacy — conversational mode\" %}\n`/fin/start` powers the conversational model, where your own UI drives a back-and-forth with Fin. This endpoint is no longer actively developed and is maintained only for existing integrations — new functionality lands on the orchestration endpoints.\n{% /admonition %}\n\nInitialize Fin by passing it the user's message along with conversation history and user details.\n\nThese additional pieces of context will be used by Fin to provide a better and more contextual answer to the user.\n\nOnce Fin is initialized, it progresses through a series of statuses such as *thinking*, *replying*, *awaiting_user_reply*, or *resolved* before ending with a status of *complete*.\n\nDuring this workflow, the client should allow Fin to continue uninterrupted until a final *complete* status is returned, at which point control of the conversation passes back to the client.\n\n{% admonition type=\"warning\" %}\nTo request access to the Fin Agent API, please [fill out this form](https://forms.gle/osy4uyiqyomRCsL2A).\n{% /admonition %}\n", "header": [ { "key": "Intercom-Version",