Skip to content
Home/
REST API Reference
/
/
Ask Fin

Ask Fin

Request

Ask Fin a single, self-contained question and receive one informational answer.

Unlike a conversation, /fin/ask is non-conversational: Fin will not ask follow-up questions, will not run procedures, and will not decide to hand over to a human itself. Escalation rules can still match, and the conversation can still be routed to a team or finish without resolution. You can also escalate one yourself with POST /fin/escalate; the ask conversation is already closed after its one-shot answer, and escalation leaves it closed while routing the handoff separately.

Fin's answer is delivered asynchronously via the fin_replied event. The conversation ends with a complete status — there is no awaiting_user_reply cycle.

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

conversation_metadataobject(Fin Agent Conversation Metadata)

Metadata about the conversation, including history and attributes.

attachmentsArray of objects, <= 10 items(Fin Agent Attachment)

An array of attachments to include with the message. Maximum of 10 attachments.

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/ask \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: Preview' \
  -d '{
    "conversation_id": "ext-123",
    "message": {
      "author": "user",
      "body": "How do I reset my password?",
      "timestamp": "2025-01-24T10:01:20.000Z"
    },
    "user": {
      "id": "123456",
      "name": "John Doe",
      "email": "john.doe@example.com"
    }
  }'

Responses

Question accepted successfully

Bodyapplication/json
conversation_idstring

The external 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""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"
}