# Fin Agent

Access Fin programmatically via the Fin Agent API endpoints.

 

{% admonition type="warning" %}
Please reach out to your accounts team to discuss access and tailored, hands-on support.
{% /admonition %}

 

Integration is centered around two endpoints (`/fin/start` and `/fin/reply`) and a set of events that notify your application of Fin's status and responses. Events can be delivered via webhooks or Server-Sent Events (SSE).

 

**Events**

Configure a webhook endpoint in the Fin Agent API settings to receive events, or use the `sse_subscription_url` from the API response to subscribe via SSE. See the [setup guide](/docs/guides/fin-agent-api/setup) for configuration details.

- `fin_status_updated` - Fired when Fin's status changes (escalated, resolved, complete)
- `fin_replied` - Fired when Fin sends a reply to the user
- `fin_reply_chunk` - SSE-only streaming event fired during reply generation (requires streaming enabled)

All webhook requests include an `X-Fin-Agent-API-Webhook-Signature` header for request validation.


## Start a conversation with Fin

 - [POST /fin/start](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/fin-agent/startfinconversation.md): 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.

## Reply to Fin

 - [POST /fin/reply](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/fin-agent/replytofin.md): Once Fin has returned a response to a user's message, its status will be awaiting_user_reply.

If a user replies, use this endpoint to send this response to Fin.

{% admonition type="warning" %}
Please reach out to your accounts team to discuss access.
{% /admonition %}