---
title: "Start a conversation with Fin"
method: POST
path: "/fin/start"
tags: ["Fin Agent"]
---

# Start a conversation with Fin

`POST /fin/start`

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" %}
Please reach out to your accounts team to discuss access.
{% /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.

## 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.

## Request body

- object
  - `conversation_id` string, required — The ID of the conversation that is calling Fin via this API.
  - `message` FinAgentMessage, required — A message exchanged within a Fin Agent conversation.
    - `author` 'user' | 'agent' | 'fin', required — The author that created the 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.
    - `timestamp` string, date-time, required — The timestamp when the message was created. Used to deduplicate messages sent within a 5 minute window. Ideally should include milliseconds for higher precision.
    - `timestamp_ms` string, date-time — The timestamp when the message was created, with millisecond precision. Only present in webhook event responses (fin_replied).
  - `user` FinAgentUser, required — A user object representing the user in a Fin Agent conversation.
    - `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.
    - `name` string — The name of the user.
    - `email` string, email — The email of the user.
    - `attributes` object — A hash of attributes associated with the user. Attributes can be used by Fin to target content and responses. Limit to 10 attributes.
  - `attachments` FinAgentAttachment[] — An array of attachments to include with the message. Maximum of 10 attachments.
    - `type` 'url' | 'file', required — The type of attachment.
    - `url` string, uri — The URL of the attachment. Required when type is 'url'. Must be publicly accessible.
    - `name` string — The name of the file. Required when type is 'file'.
    - `content_type` string — The MIME type of the file. Required when type is 'file'.
    - `data` string, byte — Base64-encoded file data. Required when type is 'file'.
  - `conversation_metadata` FinAgentConversationMetadata — Metadata about the conversation, including history and attributes.
    - `history` FinAgentMessage[] — An array of previous messages in the conversation before Fin is initialized. This data provides context to Fin and helps generate a better answer. Limit to the last 10 messages.
      - `author` 'user' | 'agent' | 'fin', required — The author that created the 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.
      - `timestamp` string, date-time, required — The timestamp when the message was created. Used to deduplicate messages sent within a 5 minute window. Ideally should include milliseconds for higher precision.
      - `timestamp_ms` string, date-time — The timestamp when the message was created, with millisecond precision. Only present in webhook event responses (fin_replied).
    - `attributes` object — A hash of attributes associated with the conversation. These attributes can be used by Fin to provide more contextual responses. Limit to 10 attributes.

## Response `200`

Fin conversation started successfully

- object
  - `conversation_id` string — The ID of the conversation.
  - `user_id` string — The ID of the user.
  - `status` 'thinking' | 'awaiting_user_reply' | 'escalated' | 'resolved' | 'complete' — Fin's current status in the conversation workflow.
  - `created_at_ms` string, date-time — The timestamp the response was created at, with millisecond precision.
  - `errors` FinAgentAttributeErrors — Contains error details if any user or conversation attribute updates failed.
    - `user` object — User-related attribute errors.
      - `attributes` object — Map of user attribute names to error messages.
    - `conversation` object — Conversation-related attribute errors.
      - `attributes` object — Map of conversation attribute names to error messages.
  - `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.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized

---

[API](https://skmtc.net/intercom/apis/intercom-api.md) · [All operations](https://skmtc.net/intercom/apis/intercom-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/intercom/intercom-api/revisions/9517e80f2642/schema)