Skip to main content

Draft replies for your support team in Intercom Fin

In this tutorial, you build a Fin workflow that drafts a reply for every new conversation in your Intercom Fin inbox, from all the knowledge you index with Kapa. Kapa indexes your knowledge sources (your documentation site, Notion, Confluence, GitHub, PDFs, support tickets) into one knowledge base built for accurate retrieval at scale. The workflow sends the customer's first message to Kapa's Chat API and attaches the answer as an internal note: the draft is waiting before your agent even opens the conversation, and they edit and send it, or discard it.

It complements Fin AI Copilot, the assistant your agents may already have in the inbox: Copilot answers only when asked, while this workflow drafts unprompted, grounded in your Kapa knowledge base.

The whole setup happens inside Fin's UI, with no glue code and no separate hosting, and it is deterministic: you decide exactly when Kapa is called and where its answer lands, and a human decides what reaches the customer.

If you would rather let Fin's customer-facing AI Agent search your knowledge base itself and answer customers directly, see Make Intercom Fin better at handling large and complex knowledge bases.

By the end of this tutorial, you will have:

  • A Fin data connector that calls Kapa's Chat API with the customer's first message.
  • A Fin workflow that attaches the Kapa-drafted reply to every new conversation as an internal note.

Before you start​

You need:

  • A Kapa project whose indexed knowledge sources contain the knowledge you want the drafts to draw from. Because every draft passes through a human before anything reaches the customer, internal sources (runbooks, past tickets, internal wikis) are as useful here as public documentation.
  • Admin access on Fin, plus the "Can access developer hub" permission, which you need to manage Data connectors and Authentication tokens.

Get your Kapa credentials​

The Fin side needs three values from the Kapa platform:

  1. Project ID: the unique identifier of your Kapa project. Go to Settings > Projects and copy it from the table.
  2. Integration ID: navigate to Integrations (under Configuration in the sidebar), click Add new integration, choose Custom (API), and copy the new integration's ID. It attributes the drafting workflow's conversations, so they show up separately in the dashboard and Analytics.
  3. API key: navigate to API Keys (under Configuration in the sidebar), click Add new API key, and copy the key.

Keep the three values at hand; you paste them into Fin in the next sections.

Create an Authentication token for your Kapa API key​

Fin keeps API credentials in a dedicated, encrypted store called Authentication tokens, separate from the connector configuration itself. You set the token up once and then reference it from the data connector.

  1. In Fin, go to Settings > Authentication and click New token.
  2. Fill in the fields:
    • Token title: a recognizable name, for example Kapa API Key.
    • Description: optional and internal-only, for example "Kapa API key, used by the reply drafting data connector."
    • Type: select text.
    • Token value: paste your Kapa API key.
    • Token prefix: leave blank. Kapa's API does not use bearer authentication; the key travels in a custom header instead.
    • Key for request header: set to X-API-KEY. Kapa rejects requests that send the key under Authorization or any other header name.
  3. Save the token.

Fin now sends X-API-KEY: <your_kapa_api_key> on every request made by any data connector you attach this token to.

Build the data connector​

This connector calls Kapa's Chat endpoint, which answers a question grounded in your knowledge sources. Go to Settings > Integrations > Data connectors, click + New > Create from scratch, and walk through the four tabs.

API​

  • Name: Draft Kapa reply. Fin uses this label internally, so make it descriptive.

  • Description: "Sends the customer's first message to Kapa and returns a drafted, knowledge-grounded reply."

  • Data inputs: add one input:

    • query: Text, sourced from the conversation's latest customer message. In the Data input configuration, choose Last Message Body to get the latest message from your customer.

  • API endpoint:

    • Method: POST
    • URL: https://api.kapa.ai/query/v1/projects/<YOUR_PROJECT_ID>/chat/, with your Kapa project ID pasted directly into the path.

  • Authentication and headers: select the Kapa API Key token you created earlier. Add one custom header: Content-Type: application/json.

  • Body: paste the following, replacing <YOUR_INTEGRATION_ID> with your Kapa integration ID and using Fin's attribute inserter ({..}) to wire the query input into the payload:

    {
      "integration_id": "<YOUR_INTEGRATION_ID>",
      "query": "Suggest a response for this query, reply with only plaintext: {query}"
    }

    The integration_id associates the conversations with the Custom (API) integration you created, so they show up attributed in the dashboard and Analytics and you can separate the drafting workflow's traffic from your other deployments. Always include it.

warning

The body editor sometimes has an interface quirk: if you receive a validation error, changing the body type to "text" and then back to "JSON" can fix it.

Click Test connection. A successful response is a JSON object containing answer, thread_id, is_uncertain, question_answer_id, and a list of source chunks. A 401 means your token is not right; re-check the Authentication token, in particular the X-API-KEY header name. A 404 usually means your project ID is wrong.

Data​

In the Data tab, switch to Manually restrict access and select the answer field: the drafted reply text, which is what your agents see. The other response fields can be passed through too if you want richer notes, but answer is all this workflow needs.

Fin​

Set the trigger mode to Disabled (manual trigger). You do not want Fin's AI Agent picking this connector up autonomously; this connector is only ever called from the workflow.

Security​

Leave customer authentication off unless you already enforce it elsewhere. Run the security check, fix anything it flags, and Set live.

Build the workflow​

Go to Fin AI Agent > Workflows, click New workflow, and start with a blank canvas.

  1. As the trigger, pick Customer sends their first message. The workflow fires once per conversation, on the opening message.

  2. Add a Trigger data connector step and select Draft Kapa reply. Pass the latest customer message as the query input.

  3. Add an Add internal note action. Your note might look like:

    Kapa suggested reply

    {answer}

    Use Fin's attribute inserter to pull answer from the connector's response. The note lands silently in the conversation, visible to agents but not to the customer.

  4. Set the workflow live, scoped to a test audience first if you prefer; Fin's audience controls let you widen it later without rebuilding the workflow.

Tune the drafting style (optional)​

Out of the box, the drafts follow Kapa's default response style. A customization shapes them into how your team actually writes, and because you associate it with the integration, nothing changes on the Fin side.

  1. Navigate to Customizations (under Configuration in the sidebar) and create a new customization. Give it a name, for example Fin drafts.
  2. Under Style & Tone, click + Add item for each rule the drafts should follow. Each instruction has a name and a description, for example:
    • No salutations: "Do not open with a greeting or close with a sign-off. Return only the body of the reply."
    • Short and concise: "Keep the reply as short as possible while answering the question. Do not restate the question or add background the customer did not ask for."
    • No internal links: "Never include links to internal sources, such as past support tickets or internal wiki pages. Use them to inform the answer, but only link public documentation."
  3. Check the preview panel on the right, which shows the system instructions with your changes applied.
  4. In the Integrations selector on the customization, pick your Custom (API) integration and save. The association also works the other way around, from the Customization column of the Integrations table.

Every draft the workflow requests now follows these instructions. The third rule is also what makes internal knowledge sources safe to draw on: the model can use a past ticket to get the answer right without the draft pointing your customer at it. For guidance on writing instructions that models follow reliably, see Write effective instructions.

Verify it works​

Fin's Test connection button fires a real request to Kapa, but with placeholder data inputs, so the first real customer message is the one to watch:

  1. Send a message as a customer (or use a test conversation) and confirm an internal note with a Kapa-drafted reply appears on the conversation.
  2. Open the data connector's Logs tab to spot 4xx and 5xx failures fast; Fin retains 14 days of execution logs.

Summary​

In this tutorial, you:

  • Created a Fin Authentication token that sends your Kapa API key in the X-API-KEY header.
  • Built a data connector that sends the customer's first message to Kapa's Chat API and exposes the drafted answer.
  • Built a workflow that fires on every new conversation and attaches the draft as an internal note for your agents.

Next steps​