# Reply to Fin

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.

Endpoint: POST /fin/reply
Version: Preview
Security: bearerAuth

## Header parameters:

  - `Intercom-Version` (string)

## Request fields (application/json):

  - `conversation_id` (string, required)
    The ID of the conversation.
    Example: 123456

  - `message` (object, required)
    A message exchanged within a Fin Agent conversation.

  - `message.author` (string, required)
    The author that created the message.
    Enum: "user", "agent", "fin"

  - `message.body` (string, required)
    The body of the message. Accepts both plain text and HTML format.
When sending a message to Fin, this should contain the user's message.
Fin's response will be returned as HTML.
    Example: How can I see my account details?

  - `message.timestamp` (string)
    The timestamp when the message was created.
Used to deduplicate messages sent within a 5 minute window.
Ideally should include milliseconds for higher precision.
    Example: 2025-01-24T10:01:20.000Z

  - `message.timestamp_ms` (string)
    The timestamp when the message was created, with millisecond precision.
Only present in event responses (fin_replied).
    Example: 2025-01-24T10:01:20.456Z

  - `user` (object, required)
    A user object representing the user in a Fin Agent conversation.

  - `user.id` (string, required)
    The ID of the user. This value will be used to uniquely identify the user
during a conversation with Fin. Maps to the user_id field on the Intercom User object.
    Example: 123456

  - `user.name` (string)
    The name of the user.
    Example: John Doe

  - `user.email` (string)
    The email of the user.
    Example: john.doe@example.com

  - `attachments` (array)
    An array of attachments to include with the message. Maximum of 10 attachments.

  - `attachments.type` (string, required)
    The type of attachment.
    Enum: "url", "file"

  - `attachments.url` (string)
    The URL of the attachment. Required when type is 'url'. Must be publicly accessible.
    Example: https://example.com/document.pdf

  - `attachments.name` (string)
    The name of the file. Required when type is 'file'.
    Example: screenshot.png

  - `attachments.content_type` (string)
    The MIME type of the file. Required when type is 'file'.
    Example: image/png

  - `attachments.data` (string)
    Base64-encoded file data. Required when type is 'file'.
    Example: iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk...

  - `settings` (object)
    Optional settings to control Fin's behaviour for this request.

  - `settings.follow_up_questions` (boolean)
    When `true` (default), Fin may ask clarifying questions and escalate to a human agent
as needed.
When `false`, Fin operates in non-conversational mode: it will not ask follow-up
questions and will not escalate to a human agent. Use this when you want Fin to respond
with a single, self-contained answer — for example, in asynchronous channels where
back-and-forth conversation is not practical.
    Example: true

  - `settings.email` (boolean)
    When `true`, Fin formats its replies as email-style responses, suitable for sending
directly to users via email. This adjusts tone and structure to match email conventions
rather than chat.
Defaults to `false`, which produces chat-style responses.
    Example: true

## Response 200 fields (application/json):

  - `conversation_id` (string)
    The ID of the conversation.
    Example: ext-123

  - `user_id` (string)
    The ID of the user.
    Example: user-456

  - `status` (string)
    Fin's current status in the conversation workflow.
    Enum: "thinking", "replying", "awaiting_user_reply", "escalated", "resolved", "complete"

  - `created_at_ms` (string)
    The timestamp the response was created at, with millisecond precision.
    Example: 2025-01-24T10:00:00.123Z

  - `errors` (object)
    Contains error details if any user or conversation attribute updates failed.

  - `errors.user` (object)
    User-related attribute errors.

  - `errors.conversation` (object)
    Conversation-related attribute errors.

  - `sse_subscription_url` (string)
    Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. When CSAT is enabled and a survey will follow the resolution, `complete` revocation is deferred until the `csat_requested` event is delivered or the token expires.
    Example: https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...

## Response 400 fields (application/json):

  - `type` (string, required)
    The type is error.list
    Example: error.list

  - `request_id` (string)
    Example: f93ecfa8-d08a-4325-8694-89aeb89c8f85

  - `errors` (array, required)
    An array of one or more error objects

  - `errors.code` (string, required)
    A string indicating the kind of error, used to further qualify the HTTP response code
    Example: unauthorized

  - `errors.message` (string)
    Optional. Human readable description of the error.
    Example: Access Token Invalid

  - `errors.field` (string)
    Optional. Used to identify a particular field or query parameter that was in error.
    Example: email

## Response 401 fields (application/json):

  - `type` (string, required)
    The type is error.list
    Example: error.list

  - `request_id` (string)
    Example: f93ecfa8-d08a-4325-8694-89aeb89c8f85

  - `errors` (array, required)
    An array of one or more error objects

  - `errors.code` (string, required)
    A string indicating the kind of error, used to further qualify the HTTP response code
    Example: unauthorized

  - `errors.message` (string)
    Optional. Human readable description of the error.
    Example: Access Token Invalid

  - `errors.field` (string)
    Optional. Used to identify a particular field or query parameter that was in error.
    Example: email