# Start a conversation with Fin

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" name="Managed Availability" %}
The Fin Agent API is currently under managed availability. 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.

Endpoint: POST /fin/start
Version: 2.14
Security: bearerAuth

## Header parameters:

  - `Intercom-Version` (string)
    Intercom API version.By default, it's equal to the version set in the app package.
    Enum: "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", "Unstable"

## Request fields (application/json):

  - `conversation_id` (string, required)
    The ID of the conversation that is calling Fin via this API.
    Example: "ext-123"

  - `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, 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.
    Example: "2025-01-24T10:01:20.000Z"

  - `message.timestamp_ms` (string)
    The timestamp when the message was created, with millisecond precision.
Only present in webhook 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"

  - `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.
    Example: {"plan_type":"Pro","subscription_status":"active"}

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

  - `conversation_metadata` (object)
    Metadata about the conversation, including history and attributes.

  - `conversation_metadata.history` (array)
    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.

  - `conversation_metadata.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.
    Example: {"priority_level":"high","department":"sales"}

## 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.
- thinking: Fin is currently thinking about a response
- awaiting_user_reply: Fin is waiting for a user to reply
- escalated: The conversation has been escalated
- resolved: The user's query has been resolved
- complete: Fin has completed its workflow
    Enum: "thinking", "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.user.attributes` (object)
    Map of user attribute names to error messages.
    Example: {"invalid_attr":"User attribute 'invalid_attr' does not exist"}

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

  - `errors.conversation.attributes` (object)
    Map of conversation attribute names to error messages.
    Example: {"bad_attr":"Conversation attribute 'bad_attr' does not exist"}

## Response 400 fields (application/json):

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

  - `request_id` (string,null)
    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,null)
    Optional. Human readable description of the error.
    Example: "Access Token Invalid"

  - `errors.field` (string,null)
    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,null)
    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,null)
    Optional. Human readable description of the error.
    Example: "Access Token Invalid"

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