Overview

Fin can be accessed programmatically via an API. You call Fin from your own agent, and Fin notifies your application of its status and responses through a set of events, delivered via webhooks.

Once Fin is initialized, it works through a series of statuses — thinking when it starts running a procedure and replying as it sends each part of an answer. Fin hands control back to your 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.

You can use Fin in one of two ways, depending on how much control you want to keep over the conversation.

Use Fin as a tool — Your agent stays in control of the turn. It disambiguates the question and decides whether to route to Fin. If it does, it can call Fin capabilities — ask, escalate, or run a procedure — and use the result. Best when you have your own orchestration logic and want Fin to deliver contained answers.

Start a conversation with Fin — Your agent hands the whole turn to Fin. Fin handles the request using its own features: content, guidance, escalations, and procedures. It produces an answer and passes control back. Best when you want Fin to own the resolution end-to-end.

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: 2.16" \
  -H "Content-Type: application/json" \
  -d '{ "user": { "id": "123456" } }'

{
  "version": "2.16",
  "capabilities": [
    {
      "name": "run_procedure_reset_password_12345",
      "description": "<untrusted-content>\nWalk the user through resetting their password.\n</untrusted-content>",
      "inputSchema": {
        "type": "object",
        "properties": { "conversation_id": { "type": "string" }, "user": { "type": "object" }, "message": { "type": "object" }, "conversation_metadata": { "type": "object" } },
        "required": ["conversation_id", "user"]
      },
      "endpoint": "/fin/procedures/12345/run",
      "method": "POST"
    },
    {
      "name": "reply",
      "description": "Send a user reply into an existing Fin conversation and get Fin's next turn. ...",
      "inputSchema": { "type": "object", "properties": { "conversation_id": { "type": "string" }, "message": { "type": "object" }, "user": { "type": "object" } }, "required": ["conversation_id", "message", "user"] },
      "endpoint": "/fin/reply",
      "method": "POST"
    }
  ]
}

Each capability is a tool definition: name, description, inputSchema (a JSON Schema for the request body to send), plus the endpoint and method to call. Procedures are named run_procedure_<title_slug>_<id>, with the slug cut to 80 characters, or run_procedure_<id> when the title gives no usable slug (for example a blank or non-Latin title), and a procedure's description is wrapped in <untrusted-content> tags. The static actions are named reply, ask and escalate. The example above is abbreviated: inputSchema is shortened, and ask and escalate are omitted.

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 decide to hand over to a human itself. Escalation rules can still match, and the conversation can still be routed to a team or finish without resolution. You can also escalate one yourself with /fin/escalate — the ask conversation is already closed after its one-shot answer, and escalation leaves it closed while routing the handoff separately.

curl -X POST https://api.intercom.io/fin/ask \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Intercom-Version: 2.16" \
  -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"
}

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",
  "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, or fails with a 422, for example when the procedure doesn't exist, isn't live, isn't available on the Fin Agent API channel or doesn't match the user's audience, when no Fin profile is configured to handle the conversation, or when conversation_id is already in use.

curl -X POST https://api.intercom.io/fin/procedures/12345/run \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Intercom-Version: 2.16" \
  -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"
}

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, including one started with /fin/ask. On the Intercom Helpdesk, Fin by default summarises the conversation and opens a new Helpdesk conversation that carries the summary as an internal note. You can change this default with an escalation Operator Workflow (see below). Escalation closes the original agent conversation if it is open, including on Fin for Platforms.
• user — escalate on behalf of a user with no prior agent conversation. Fin creates an agent conversation for the escalation and closes it once the handoff completes. On the Intercom Helpdesk, the teammate works in a separate new Helpdesk conversation. Not supported on Fin for Platforms — see below.

In both cases, pass the optional context to give the receiving teammate background your orchestrating agent has and Fin does not. On the Intercom Helpdesk, it appears above the summary in the internal note of the new conversation the teammate picks up. It is never shown to the end user.

On Fin for Platforms, context is not surfaced: escalation hands off to your own agent desk rather than creating an Intercom Helpdesk conversation, and the escalation events your platform receives do not carry it.

Escalating an existing conversation also sets its AI Agent resolution state to escalated, readable as ai_agent.resolution_state on the Conversations API. This is a resolution state, not a billable resolution.

You are notified over webhooks with an escalated status followed by complete. complete signals that Fin is done. By then the original agent conversation has been closed. An escalation Operator Workflow may act on it afterwards, but it is closed again once the workflow's first steps have run, so only steps that run later (for example after a wait) can reopen it. On the Intercom Helpdesk the handoff continues in the new conversation routed to your team inbox, which stays open there, and on Fin for Platforms you hand the conversation to a human on your own platform.

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

{
  "conversation_id": "ext-123",
  "status": "escalated"
}

When escalating on behalf of a user, Fin creates an agent conversation for the escalation and closes it once the handoff completes. The response returns the conversation_id Fin generated for it, along with its intercom_conversation_id:

{
  "conversation_id": "escalate-1a2b3c4d5e6f7a8b",
  "intercom_conversation_id": "987654321",
  "status": "escalated"
}

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",
  "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'"
      }
    }
  }
}

Conversations you drive through /fin/start are billed on outcomes. You're charged at most once per conversation, and only when Fin reaches a billable outcome such as a resolution.

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

POST /fin/csat records a customer's satisfaction rating for a conversation, with an optional free-text remark.

Fin asks for a rating when a conversation reaches a point where CSAT collection is enabled — this reuses the CSAT settings on your Fin workflow, so you control when a rating is requested from Intercom, not through 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 with this endpoint.

POST /fin/csat and the csat_requested event are available on API version 2.14 and above.

Submitting the same rating again (with no new remark) is a no-op that succeeds even after the rating window has closed, so an at-least-once client can safely retry. Submitting a different rating updates the stored rating, but only while the rating window is still open. A first remark can be added to an already-rated survey — even after the window has closed — but once a remark has been recorded, the rating is permanently locked and can no longer be changed.

curl -X POST https://api.intercom.io/fin/csat \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Intercom-Version: 2.16" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "ext-123",
    "rating": "amazing",
    "remark": "Fin solved my problem in seconds."
  }'

{
  "conversation_id": "ext-123",
  "rating": "amazing",
  "status": "rated"
}

A rating that can't be recorded returns a 422 with an errors message. Common causes:

Fin fires events during its workflow to convey its status and deliver replies to the user. These events are delivered via Webhooks.

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.

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. Once Fin's reply is done, a separate fin_status_updated event with status awaiting_user_reply is fired.

Once Fin finishes and the conversation reaches complete, a csat_requested survey may follow if CSAT is enabled on your Fin workflow.

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. [1]</p>",
    "timestamp_ms": "2025-01-24T09:01:00.456Z",
    "sources": [
      {
        "title": "Managing your account",
        "type": "article",
        "url": "https://www.example.com/help/en/articles/1-managing-your-account"
      }
    ]
  },
  "status": "replying",
  "created_at_ms": "2025-01-24T10:00:00.123Z"
}

Fin fires this event when it asks the user to rate the conversation. It carries the rating options to present; collect the user's choice and submit it 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.

CSAT Requested Example

{
  "event_name": "csat_requested",
  "conversation_id": "ext-123",
  "user_id": "7891",
  "csat": {
    "options": [
      { "key": "terrible", "emoji": "😠", "label": "Terrible" },
      { "key": "bad", "emoji": "🙁", "label": "Bad" },
      { "key": "ok", "emoji": "😐", "label": "Okay" },
      { "key": "good", "emoji": "😃", "label": "Great" },
      { "key": "amazing", "emoji": "🤩", "label": "Amazing" }
    ]
  },
  "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 and react accordingly.

Which statuses you see depends on the endpoint. thinking is sent when Fin starts running a procedure, not on every turn. A turn ends with awaiting_user_reply when Fin has answered and is waiting for the user's next message (on API version 2.16 and above this is sent as a fin_status_updated event; on 2.15 and earlier it is the status of the fin_replied events), or with complete when Fin is done: it resolved the conversation, escalated, finished a procedure, closed the conversation after the user went inactive, or detected spam. A one-shot Ask Fin call always ends with complete and never enters awaiting_user_reply. replying accompanies each reply part. 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.

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.

• fin_replied — Each event carries a part of Fin's answer as rich text (HTML) in message.body.
• 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 to know once Fin's reply is done.

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.

By default, the message.body field in fin_replied events contains server-rendered HTML. If you set response_format to markdown, it contains Markdown instead and the HTML elements below do not apply, unless Fin could not convert the reply and sent HTML instead. Render each reply according to message.format. 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: