INintercom
Fin Agent

Run a Fin procedure

Changed on

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. If the procedure pauses for user input, the conversation status becomes awaiting_user_reply — send the user's response with /fin/reply.

{% admonition type="warning" %} 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. {% /admonition %}

post/fin/procedures/{procedure_id}/run

Request

  • Base URL
    https://api.intercom.io
  • Auth
    HTTP bearer

Path parameters

procedure_idstring required

The ID of the procedure to run.

Headers

Intercom-Version'1.0' | '1.1' | '1.2' | '1.3' | '1.4' | '2.0' | '2.1' | '2.2' | '2.3' | '2.4' | '2.5' | '2.6' | '2.7' | '2.8' | '2.9' | '2.10' | '2.11' | '2.12' | '2.13' | '2.14'

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

Example:2.14

Request body

conversation_idstring required

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

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 request

{
  "conversation_id": "ext-123",
  "user": {
    "id": "123456",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "attributes": {
      "plan_type": "Pro",
      "subscription_status": "active"
    }
  },
  "message": {
    "author": "user",
    "body": "How can I see my account details?",
    "timestamp": "2025-01-24T10:01:20.000Z",
    "timestamp_ms": "2025-01-24T10:01:20.456Z"
  },
  "conversation_metadata": {
    "attributes": {
      "order_id": "98765"
    }
  },
  "environment": "a1b2c3d4e5"
}

Response

Procedure run started successfully

conversation_idstring

The ID of the conversation.

intercom_conversation_idstring

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

user_idstring

The ID of the user.

procedure_idstring

The ID of the procedure that was run.

status'thinking' | 'replying' | 'awaiting_user_reply' | 'escalated' | 'resolved' | 'complete'

Fin's current status in the conversation workflow.

created_at_msstring date-time

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

Example 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",
  "errors": {
    "user": {
      "attributes": {
        "invalid_attr": "User attribute 'invalid_attr' does not exist"
      }
    },
    "conversation": {
      "attributes": {
        "bad_attr": "Conversation attribute 'bad_attr' does not exist"
      }
    }
  }
}

Changes