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.

To request access to the Fin Agent API, go to Settings > Integrations > Fin Agent API in your workspace and tell us about your use case. Once access is granted, Fin Agent API appears under Fin AI Agent > Deploy.

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:"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

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

environmentstring

The identifier of the environment to start the conversation in, if your Fin for Platforms workspace has environments. Use the same value as messenger_environment in your Messenger installation. Defaults to the workspace's default environment; an identifier that matches no environment is rejected.

Example:"a1b2c3d4e5"

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: 2.14' \
  -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"

intercom_conversation_idstring

The internal Intercom conversation ID, useful for matching this Agent API session to the conversation in Intercom.

Example:"192837465"

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",
  "intercom_conversation_id": "192837465",
  "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"
}