Skip to content
Home/
/Fin Agent

Fin Agent

Access Fin programmatically via the Fin Agent API endpoints.

 

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.

 

Integration centres on the Fin Agent API endpoints — start a conversation with /fin/start and continue it with /fin/reply, or drive Fin from your own agent with /fin/capabilities, /fin/ask, /fin/procedures/{procedure_id}/run, and /fin/escalate — plus a set of events that notify your application of Fin's status and responses. Events are delivered via webhooks. You can also record a customer satisfaction rating with /fin/csat.

 

Events

Configure a webhook endpoint in the Fin Agent API settings to receive events. See the setup guide for configuration details.

  • fin_status_updated - Fired when Fin's status changes (awaiting_user_reply, escalated, resolved, complete)
  • fin_replied - Fired when Fin sends a reply to the user
  • csat_requested - Fired when Fin asks the user to rate the conversation (submit the choice with POST /fin/csat)

All webhook requests include an X-Fin-Agent-API-Webhook-Signature header for request validation.

Schemas

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.

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.

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
Headers
Intercom-Versionstring(intercom_version)

Intercom API version.
If you omit the header, the API uses the version set in your app package, and 1.0 if none is set.

Enum:"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"
Example:2.17
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.

environmentstring

The identifier of the environment to start the conversation in. Only Fin for Platforms workspaces use it; other workspaces ignore it. Use the same value as messenger_environment in your Messenger installation. Defaults to the workspace's default environment. On a Fin for Platforms workspace, an identifier that matches no environment returns a 422 error.

Example:"a1b2c3d4e5"
response_formatstring

The format of the body in Fin's replies. Defaults to html. Requesting markdown on a workspace where it is not enabled returns a 403 error.

Default:"html"
Enum:"html""markdown"
Example:"html"
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.17' \
  -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"
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"
statusstring

Fin's status when the request was accepted. Always thinking; later statuses arrive as events.

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.

Response
{
  "conversation_id": "ext-123",
  "intercom_conversation_id": "192837465",
  "user_id": "user-456",
  "status": "thinking",
  "created_at_ms": "2025-01-24T10:00:00.123Z"
}