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.

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

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.

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

Intercom-Versionstring(intercom_version)

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

Default:"Preview"

Enum:"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"

Example:Preview

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.

settingsobject(Fin Agent Settings)

Optional settings to control Fin's behaviour for this request.

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