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.

Please reach out to your accounts team to discuss access.

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 via webhook, at which point control of the conversation passes back to the client.

Security

bearerAuth

Intercom-Versionstring(intercom_version)

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

Default:"2.16"

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

Example:2.16

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.16' \
  -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"
}