Skip to content
Home/
/Fin Agent

Fin Agent

Access Fin programmatically via the Fin Agent API endpoints.

 

To request access to the Fin Agent API, please fill out this form.

 

Integration is centered around two endpoints (/fin/start and /fin/reply) and a set of events that notify your application of Fin's status and responses. Events can be delivered via webhooks or Server-Sent Events (SSE). You can also record a customer satisfaction rating with /fin/csat.

 

Pricing

Conversations you start with /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. See Understanding Fin outcomes.

 

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 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.

Schemas

Start a conversation with Fin

Request

Initialize Fin by passing it the user's message along with 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.

To request access to the Fin Agent API, please fill out this form.

Once Fin is initialized, it progresses through a series of statuses such as thinking, awaiting_user_reply, or resolved before ending with a status of complete.

During this workflow, the client should allow Fin to continue uninterrupted until a final complete status is returned via webhook, at which point control of the conversation passes back to the client.

Pricing

Conversations you start with /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. See Understanding Fin outcomes.

Security
bearerAuth
Headers
Intercom-Versionstring(intercom_version)

Intercom API version.
By default, it's equal to the version set in the app package.

Default:"2.14"
Enum:"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"
Example:2.14
Bodyapplication/jsonrequired
conversation_idstringrequired

The ID of the conversation that is calling Fin via this API.

Example:"ext-123"
messageobject(Fin Agent Message)required

A message exchanged within a Fin Agent conversation.

userobject(Fin Agent User)required

A user object representing the user in a Fin Agent conversation.

attachmentsArray of objects, <= 10 items(Fin Agent Attachment)

An array of attachments to include with the message. Maximum of 10 attachments.

conversation_metadataobject(Fin Agent Conversation Metadata)

Metadata about the conversation, including history and attributes.

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

Responses

Fin conversation started successfully

Bodyapplication/json
conversation_idstring

The ID of the conversation.

Example:"ext-123"
user_idstring

The ID of the user.

Example:"user-456"
statusstring

Fin's current status in the conversation workflow.

Enum:"thinking""awaiting_user_reply""escalated""resolved""complete"
Example:"thinking"
created_at_msstring, (date-time)

The timestamp the response was created at, with millisecond precision.

Example:"2025-01-24T10:00:00.123Z"
errorsobject(Fin Agent Attribute Errors)

Contains error details if any user or conversation attribute updates failed.

sse_subscription_urlstring

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