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

Reply to Fin

Request

Send a follow-up message in an existing conversation. When Fin needs more information to complete an action, it sets the conversation to awaiting_user_reply — send the user's response so Fin can continue.

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

The ID of the conversation.

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

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/reply \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: Preview' \
  -d '{
    "conversation_id": "ext-123",
    "message": {
      "author": "user",
      "body": "Here'\''s the information you requested.",
      "timestamp": "2025-01-24T09:01:00.000Z"
    },
    "user": {
      "id": "123456",
      "name": "John Doe",
      "email": "john.doe@example.com"
    }
  }'

Responses

Reply sent 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"
}