Run a Fin procedure

Request

Deterministically run a specific procedure on a new conversation. Calling this endpoint guarantees that the named procedure runs — there is no non-deterministic routing.

Fin's progress is delivered asynchronously via events or Server-Sent Events. If the procedure pauses for user input, the conversation status becomes awaiting_user_reply — send the user's response with /fin/reply.

Security

bearerAuth

Path

procedure_idstringrequired

The ID of the procedure to run.

Example:12345

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

Your external conversation ID. Fin creates a conversation for this ID. If a conversation already exists for it, use /fin/reply instead.

Example:"ext-123"

userobject(Fin Agent User)required

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

messageobject(Fin Agent Message)

A message exchanged within a Fin Agent conversation.

conversation_metadataobject

Metadata about the conversation. Only attributes are accepted (no history).

settingsobject

Optional settings to control Fin's behaviour for this procedure run.

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

Responses

Procedure run started successfully

Bodyapplication/json

conversation_idstring

The ID of the conversation.

Example:"ext-123"

user_idstring

The ID of the user.

Example:"user-456"

procedure_idstring

The ID of the procedure that was run.

Example:"12345"

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