# Setup

This guide explains how to set up the **Fin over API** integration using a **Custom Channel** in Intercom. It is intended for teams embedding Fin into their own applications via API.

'Fin over API' is currently under managed availability
Please reach out to your accounts team to discuss access and tailored, hands-on support.

## Prerequisites

To complete setup, you will need:

* Access to the **Fin over API** feature (currently under managed availability).
* An application with:
  * A server that can handle **incoming HTTP POST requests** from Intercom (this is also the Callback URL you will configure);
  * A UX that reacts to and integrates with Intercom events


## 1. Navigate to Fin over API Setup Page

![Setup page](/assets/standalone_deploy_page.003ebfe37aefa03939e28b68b979f8879b77c7af144c48de0068083490d9b46d.71a4f21c.png)

From your Intercom workspace:

1. Go to **Deploy > Fin over API** in the side navigation.
2. In the **Integration** section, click **Setup Custom Channel Integration** to expand the configuration form.


## 2. Configure API Settings

![Setup page](/assets/fin_over_api_setup.a6c1e515a9cc8d132810c9883941416e37fae3ced4868c07319dd8efa74eee99.71a4f21c.png)

In the setup form:

* **API Key:** This key is pre-generated and shown (obscured) in the setup page. You should use the key when calling Intercom's Custom Channel Events API.
* **Callback URL:** Enter the HTTPS URL of your backend server that can receive POST events from Intercom.
* (Optional) **Add Authentication Token:** If your endpoint requires additional authentication (which we strongly recommend), you may define a token here. Intercom will include it as a header when sending outbound events.


Click **Save** to persist your integration settings.

## 3. Configure Your Workflow

![Setup page](/assets/fin_over_api_workflow.ac71b3d63b230fb749ba13cc26a5b99ed31622255bb28ff3b508f6249dde459d.71a4f21c.png)

Once your API integration is configured, the next step is to build or edit a workflow in Intercom that uses the **Let Fin answer** step.

1. Go to **Deploy > Fin over API > Manage answer and hand-off** in Intercom.
2. Add the **Let Fin answer** step where appropriate. This enables Fin to respond to the user based on your knowledge base.
3. Configure fallback steps for when Fin cannot resolve the question.
4. Optionally, include other steps like **Data collector**, **Tag**, or **Note** to guide the experience.


When your app triggers the workflow using a `new_conversation` event, Intercom will execute the configured flow and Fin will respond accordingly.

Make sure to publish the workflow when you're done.

## 4. Implement Your Callback Endpoint

Your callback endpoint should be able to receive `POST` requests from Intercom. The payload will include various event types like `new_message`, `typing`, `quick_reply_options`, etc.

Example base structure:


```json
{
  "event_type": "new_message",
  "conversation_id": "intercom_abc123",
  "external_conversation_id": "external_abc123",
  ... // additional event-specific data
}
```

Refer to the **Custom Channel Integration guide** for a complete list of supported events and payloads.

## 5. Trigger Fin Workflows with Inbound Events

Your application can begin a conversation with Fin by sending **inbound events** to Intercom (via the [Custom Channel Events API](https://developers.intercom.com/docs/references/unstable/rest-api/api.intercom.io/custom-channel-events)).

Typical event sequence:

1. `new_conversation` — start a new workflow
2. `new_message` — send a user message
3. `quick_reply_selected` — user selects a predefined button


Ensure you link your messages to the correct conversation using the `external_conversation_id`.

## 6. Test the Integration

Use your app’s interface to:

* Initiate a Fin workflow via `new_conversation`
* Observe outbound responses (e.g., `new_message`, `quick_reply_options`, `typing`)
* Simulate user replies and trigger appropriate inbound events


You can monitor and troubleshoot interactions using your server logs and Intercom's workflow analytics.

## 7. Customize the Experience

Although Fin handles the conversation logic, your app has full control over the **UI/UX**:

* Render Fin responses with your own UI components
* Show loading states using `typing` events
* Display button options from `quick_reply_options`
* Handoff to human support based on `resolution_state_updated` or `workflow_finished`


This model gives you complete flexibility while keeping the intelligence and automation of Intercom Fin.