Overview

Fin can be accessed programmatically via an API. You can orchestrate Fin from your own agent — discover what Fin can do, ask a one-shot question, run a specific procedure, reply, and escalate to a human — and Fin notifies the client of its status and responses through a set of events. Events can be delivered via webhooks or Server-Sent Events (SSE).

Once Fin is initialized, it works through a series of statuses — thinking as it works on a request and replying as it sends each part of an answer. Fin hands control back to the orchestrating agent when it reaches awaiting_user_reply (it needs the user's next message to continue) or complete (it has finished). Allow Fin to continue uninterrupted until it returns control with one of these statuses.

If you are driving Fin from your own agent, the orchestration endpoints let your agent decide what Fin should do and when:

POST /fin/capabilities returns a per-user list of what Fin can do, so your agent can decide which endpoint to call. The list is audience-matched to the user you pass.

curl -X POST https://api.intercom.io/fin/capabilities \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Intercom-Version: Preview" \
  -H "Content-Type: application/json" \
  -d '{ "user": { "id": "123456" } }'

{
  "version": "Preview",
  "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" }
  ]
}

POST /fin/ask gets a single, self-contained answer to one question. It is non-conversational: Fin will not ask follow-up questions, run procedures, or escalate.

curl -X POST https://api.intercom.io/fin/ask \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Intercom-Version: Preview" \
  -H "Content-Type: application/json" \
  -d '{
    "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" }
  }'

{
  "conversation_id": "ext-123",
  "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"
}

Fin's answer arrives asynchronously via the fin_replied event. The conversation ends with a complete status — there is no awaiting_user_reply cycle.

Endpoint: /fin/reply

Use /fin/reply to send a follow-up message in an existing conversation. When Fin needs more information to complete an action, it sets the conversation to awaiting_user_reply — send the user's response so Fin can continue.

This endpoint requires user.id, the same as the other orchestration endpoints.

Request Payload Example

{
  "message": {
    "author": "user",
    "body": "Here's the information you requested.",
    "timestamp": "2025-01-24T09:01:00.000Z"
  },
  "conversation_id": "ext-123",
  "user": {
    "id": "123456",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "attributes": {
      "plan_type": "Pro",
      "subscription_status": "active"
    }
  },
  "attachments": [
    {
      "type": "url",
      "url": "https://example.com/invoice.pdf"
    }
  ]
}

Response Example

{
  "conversation_id": "ext-123",
  "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": {
        "invalid_attr": "User attribute 'invalid_attr' does not exist"
      }
    }
  }
}

POST /fin/procedures/{procedure_id}/run deterministically runs a specific procedure on a new conversation. Calling it guarantees that procedure runs.

curl -X POST https://api.intercom.io/fin/procedures/12345/run \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Intercom-Version: Preview" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "ext-123",
    "user": { "id": "123456", "name": "John Doe", "email": "john.doe@example.com" }
  }'

{
  "conversation_id": "ext-123",
  "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"
}

If the procedure pauses for input, the conversation status becomes awaiting_user_reply — send the user's response with Reply to Fin.

POST /fin/escalate hands 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. By default, Fin summarises the conversation and opens a new Helpdesk conversation that carries the summary as an internal note — the original agent conversation is not reassigned. You can change this default with an escalation Operator Workflow (see below).
• user — escalate on behalf of a user with no prior agent conversation. A new Helpdesk conversation is created for the teammate. Pass an optional message for its first message.

In both cases, the optional context is attached as an internal note (it's supplied by your orchestrating agent, not generated by Fin) alongside any summary.

The conversation is routed to the human inbox, and you are notified over webhooks or SSE with an escalated status followed by complete. complete signals that Fin is done — it does not close the conversation, which stays open in the human inbox.

curl -X POST https://api.intercom.io/fin/escalate \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Intercom-Version: Preview" \
  -H "Content-Type: application/json" \
  -d '{ "conversation_id": "ext-123", "context": "Customer is requesting a refund." }'

{
  "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"
}

When escalating on behalf of a user, a new conversation is created and the response returns intercom_conversation_id instead of an external conversation_id:

{
  "intercom_conversation_id": "987654321",
  "status": "escalated",
  "sse_subscription_url": "https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:987654321&accessToken=eyJhbG...&rewind=2m"
}

Conversations you drive through the Fin Agent API are billed the same way as any other Fin conversation — on outcomes. You're charged at most once per conversation, and only when Fin reaches a billable outcome.

A conversation that Fin answers through the API is counted as a resolution, which is a billable outcome. Conversations that don't reach a billable outcome aren't charged — for example, handing a conversation to a human with /fin/escalate without a resolution, or discovering what Fin can do with /fin/capabilities, which doesn't create a conversation.

For how outcomes are calculated and billed, see Understanding Fin outcomes.

Endpoint: /fin/start

Initialise Fin by passing it the user's message along with some conversation history and user details. These additional pieces of context will be used by Fin to provide a better and more contextual answer to the user.

Request Payload Example

{
  "conversation_id": "ext-123",
  "message": {
    "author": "user",
    "body": "How can I see my account details?",
    "timestamp": "2025-01-24T10:01:20.000Z"
  },
  "user": {
    "id": "123456",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "attributes": {
      "plan_type": "Pro",
      "subscription_status": "active"
    }
  },
  "attachments": [
    {
      "type": "url",
      "url": "https://example.com/document.pdf"
    },
    {
      "type": "file",
      "name": "screenshot.png",
      "content_type": "image/png",
      "data": "<base64 encoded file data>"
    }
  ],
  "conversation_metadata": {
    "history": [
      {
        "author": "user",
        "body": "I need help",
        "timestamp": "2025-01-24T10:00:01Z"
      },
      {
        "author": "agent",
        "body": "What do you need help with?",
        "timestamp": "2025-01-24T10:01:00Z"
      }
    ],
    "attributes": {
      "priority_level": "high",
      "department": "sales"
    }
  }
}

Response Example

{
  "conversation_id": "ext-123",
  "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"
      }
    },
    "conversation": {
      "attributes": {
        "bad_attr": "Conversation attribute 'bad_attr' does not exist",
        "priority_level": "'1234' is not a valid value for attribute 'priority_level' of type 'string'"
      }
    }
  }
}

Fin fires events during its workflow to convey its status and deliver replies to the user. These events can be received via Webhooks, SSE, or both — for example, using SSE for low-latency UI rendering with webhooks as a reliable fallback.

Both delivery mechanisms provide the same event types with identical schemas.

A webhook endpoint can be configured in the Fin Agent API settings. The client can then listen for Fin events sent to this webhook and handle them accordingly.

All webhook requests will include an X-Fin-Agent-API-Webhook-Signature header containing an HMAC-SHA256 signature of the request body. Validation can be done by generating a signature using the request body and the signing secret from the settings, and comparing it with the aforementioned header value.

You can receive events via Server-Sent Events (SSE) using the sse_subscription_url returned by any endpoint that starts or continues a Fin response cycle — Ask Fin, Reply to Fin, Run a procedure, and Escalate to a human (as well as the legacy /fin/start).

1. Call any of these endpoints as normal.
2. The response includes an sse_subscription_url field.
3. Open an SSE connection to this URL using EventSource or any HTTP client that supports SSE.
4. Receive fin_replied and fin_status_updated events in real time over the SSE stream.

The sse_subscription_url follows this format:

https://primary-realtime.intercom-messenger.com/event-stream?channels={channel}&accessToken={token}&rewind={duration}

Endpoints that begin a new Fin response cycle — Ask Fin, Run a procedure, Escalate, and the legacy /fin/start — return an sse_subscription_url with a rewind=2m query parameter. This instructs the SSE provider to replay any events from the last 2 minutes when the client connects, preventing missed events between receiving the HTTP response and establishing the SSE connection.

The /fin/reply endpoint does not include the rewind parameter, since the client is expected to already have an active SSE connection at that point.

• SSE access tokens expire after 3 minutes.
• The token is revoked immediately when Fin sets the conversation to awaiting_user_reply or complete. The awaiting_user_reply revocation occurs when Fin finishes replying; the complete revocation covers flows where the conversation ends without a reply cycle (e.g., immediate escalation).
• After receiving awaiting_user_reply, the SSE connection will close. If the user replies, call /fin/reply to obtain a new sse_subscription_url with a fresh token.

// After calling an endpoint that returns an sse_subscription_url (e.g. /fin/ask)
const response = await fetch('https://api.intercom.io/fin/ask', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <YOUR_ACCESS_TOKEN>',
    'Content-Type': 'application/json',
    'Intercom-Version': 'Preview'
  },
  body: JSON.stringify({ /* request payload */ })
});

const data = await response.json();

// Connect to SSE using the subscription URL
const eventSource = new EventSource(data.sse_subscription_url);

eventSource.onmessage = (event) => {
  const eventData = JSON.parse(event.data);

  if (eventData.event_name === 'fin_replied') {
    // Handle Fin's reply
    console.log('Fin replied:', eventData.message.body);
  }

  if (eventData.event_name === 'fin_status_updated') {
    console.log('Status updated:', eventData.status);

    if (eventData.status === 'awaiting_user_reply' || eventData.status === 'complete') {
      // Fin is done with this cycle — close the SSE connection
      eventSource.close();
    }
  }
};

eventSource.onerror = (error) => {
  console.error('SSE connection error:', error);
  eventSource.close();
};

Fin will report its status to the client via this event.

Status Update Example (Escalated)

{
  "event_name": "fin_status_updated",
  "conversation_id": "ext-123",
  "user_id": "7891",
  "status": "escalated",
  "reason": "Escalation requested by user",
  "created_at_ms": "2025-01-24T10:00:00.123Z"
}

Status Update Example (Resolved)

{
  "event_name": "fin_status_updated",
  "conversation_id": "ext-123",
  "user_id": "7891",
  "status": "resolved",
  "created_at_ms": "2025-01-24T10:00:00.123Z"
}

Status Update Example (Awaiting User Reply)

{
  "event_name": "fin_status_updated",
  "conversation_id": "ext-123",
  "user_id": "7891",
  "status": "awaiting_user_reply",
  "created_at_ms": "2025-01-24T10:00:00.123Z"
}

Fin will reply to a user via this event. The content of the response will be contained in the Message object. Intermediate reply events have a status of replying, indicating that more reply parts may follow. When Fin has finished replying, a separate fin_status_updated event with status awaiting_user_reply is fired as a done signal.

Fin Reply Example (Intermediate)

{
  "event_name": "fin_replied",
  "conversation_id": "ext-123",
  "user_id": "7891",
  "message": {
    "id": "98765",
    "author": "fin",
    "body": "<p>You can see your account details by clicking on the <em>Account</em> tab in the top right corner of the screen.</p>",
    "timestamp_ms": "2025-01-24T09:01:00.456Z"
  },
  "status": "replying",
  "created_at_ms": "2025-01-24T10:00:00.123Z"
}

When SSE is enabled with streaming, Fin will emit fin_reply_chunk events during reply generation. Each chunk contains the full accumulated answer text so far — not a delta. This allows progressive rendering as Fin types.

Fin Reply Chunk Example

{
  "event_name": "fin_reply_chunk",
  "conversation_id": "ext-123",
  "stream_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "chunk_index": 3,
  "chunk_text": "You can see your account details by clicking",
  "status": "replying",
  "created_at_ms": "2025-01-24T10:00:00.123Z"
}

As Fin works through a request it reports a series of statuses. Listen for these via Webhooks or SSE and react accordingly.

Which statuses you see depends on the endpoint. Every request reports thinking while Fin works and ends with complete when control returns to you. replying accompanies each reply part. awaiting_user_reply only appears when Fin needs more information to continue (for example, a procedure that pauses for input) — a one-shot Ask Fin call never enters it. escalated is covered below.

When a conversation is escalated, the escalated fin_status_updated event carries a reason field.

When you escalate deterministically with /fin/escalate, the reason is always:

The following reasons may be provided:

Note: The reason field is optional and may not be present in all escalated status update events. Legacy implementations or certain edge cases may not include this field.

All requests to this API require an API key in the HTTP header. You can obtain an API key after completing the Fin Agent API setup.

For general authentication guidelines, see Intercom authentication.

The Fin Agent API access token is created with the write_conversations OAuth scope, which provides the minimum permissions needed for Fin Agent API operations. This follows security best practices by limiting what an access token can do if compromised.

For more information about OAuth scopes and token security, see the OAuth Scopes & Permissions section in the setup guide.

When you provide a User object to the Fin Agent API, the following behavior applies:

• User role only: The Fin Agent API only supports the User role. Leads and Visitors are not supported.

• User lookup: The id field is used to look up existing users in Intercom. This value maps to the user_id field on the Intercom User object.

• User creation: If no user is found with the provided id, a new user will be created with the given parameters.

• Email updates: If an email is provided and differs from the existing user's email, the user's email will be updated.

• Attribute updates: If attributes are provided, they will be merged with the user's existing attributes. New attributes are added and existing attributes with the same key are overwritten.

  User data update considerations

  If your users interact with Intercom across multiple channels (e.g., Messenger and the Fin Agent API), updating the email or attributes via this API will affect the user record across all channels. Ensure that the data you provide is authoritative and consistent with your other integrations to avoid unintended changes to user data.

SSE and webhooks serve different purposes and can be used independently or together. Choose based on your integration's needs:

• Chunks are cumulative plain text — Each fin_reply_chunk contains the full accumulated answer text so far, not a delta. You can render the latest chunk directly — no need to concatenate fragments. If you miss a chunk, the next one contains everything. Note that fin_reply_chunk events contain plain text only — rich content such as images is not included in chunks and will only appear in the final fin_replied event.
• Swap to rich text on completion — When Fin completes its reply, the fin_replied event delivers the final answer as rich text (HTML with formatting, sources, etc.). The recommended strategy: stream fin_reply_chunk events for real-time display, then replace the streamed text with the fin_replied rich text for the final rendered view.
• Use stream_id to correlate chunks and replies — Each reply stream has a unique stream_id. Use it to match fin_reply_chunk events to the corresponding fin_replied event, especially when handling multiple reply parts.

• Tokens are short-lived — SSE access tokens expire after 3 minutes and are revoked when Fin finishes replying (awaiting_user_reply or complete status).
• Use /fin/reply for fresh tokens — After a token is revoked, call the /fin/reply endpoint when the user responds. Each response includes a new sse_subscription_url with a fresh token — do not cache or reuse old URLs.

• Persist conversations for page refreshes — SSE is ephemeral. Clients must persist conversation state locally or via their backend and rely on webhooks for updates that arrive while no SSE connection is active (e.g., after a page refresh or reconnection).
• Inactivity messages arrive via webhook only — If Fin times out waiting for a user reply, the inactivity message will not arrive over SSE (the connection will likely have closed by then). Rely on webhooks to capture it.

• Use message.id to deduplicate across SSE and webhooks — When using both SSE and webhooks, the same fin_replied event is delivered on both channels. Each fin_replied event includes a message.id that uniquely identifies the message. Use it to detect and discard duplicates.
• stream_id links chunks to the final reply — For streamed replies, use stream_id to correlate fin_reply_chunk events with the final fin_replied event. Non-streamed replies (e.g., follow-ups) will not have a stream_id but will always have a message.id.

• fin_reply_chunk — Use for progressive rendering. Each chunk contains the cumulative plain-text answer so far with a replying status.
• fin_replied — Replace the streamed text with the fin_replied event's rich-text body for the final rendered view. Use stream_id to match it to the preceding chunks.
• fin_status_updated — A follow-up fin_status_updated event is fired after Fin's replies to indicate the conversation has moved to awaiting_user_reply, resolved, or complete status. Use this as the "done" signal.

Use a stable API version (e.g., 2.14, 2.15) for production integrations. The Preview version may include experimental changes that are modified or removed before reaching a stable release. See Update your API version for guidance on choosing and upgrading versions.

The message.body field in fin_replied events contains server-rendered HTML. The specific elements that appear depend on the knowledge ingested into Fin — for example, if your help center articles contain tables or code blocks, Fin may include those elements in its responses.

The following HTML elements may appear in message.body: