INintercom
Fin Agent

Start a conversation with Fin

Changed on

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.

{% 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 %}

Once Fin is initialized, it progresses through a series of statuses such as thinking, 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.

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.

post/fin/start

Request

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

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

The ID of the conversation that is calling Fin via this API.

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",
  "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"
  },
  "user": {
    "id": "123456",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "attributes": {
      "plan_type": "Pro",
      "subscription_status": "active"
    }
  },
  "attachments": [
    {
      "type": "url",
      "url": "https://example.com/document.pdf",
      "name": "screenshot.png",
      "content_type": "image/png",
      "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk..."
    }
  ],
  "conversation_metadata": {
    "history": [
      {
        "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"
      }
    ],
    "attributes": {
      "priority_level": "high",
      "department": "sales"
    }
  },
  "environment": "a1b2c3d4e5"
}

Response

Fin conversation 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.

status'thinking' | '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",
  "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