Skip to content
Home/Webhooks/
Notify Fin of Conversatio...

Fin Custom Helpdesk API (0.0.1)

The Fin Custom Helpdesk API allows you to integrate your custom helpdesk with Fin through a standardized set of API endpoints and webhooks.

Note that the names of the endpoints are set by the custom helpdesk's API. They do not need to conform to the names given in this API spec (e.g. create_message).

FAQ

Q: Can POST be used for all API requests instead of GET?

A: Yes. All endpoints now support POST requests.

Q: Must field names use snake_case or can camelCase be used?

A: snake_case is required. The format of the responses outlined in the documentation must be followed, including the snake_case key names. Intercom cannot support different naming conventions for different customers.

Message & Idempotency

Q: Does create_message API provide a unique message ID for idempotency?

A: Yes. An object_id field is available on all create type requests: create_message, create_conversation, and create_user. This represents the ID of the object in the Intercom system.

Q: Do message APIs support attachments?

A: Yes, attachments are supported. The format of attachments is outlined in the Messages section of the API docs.

Messages can contain:

  • Text body only (no attachments)
  • Attachments only (no text body - body can be null or empty string)
  • Both text body and attachments

However, a message cannot be completely empty - it must have either a body or at least one attachment.

Q: What HTML is supported in message content?

A: The following HTML tags are supported in the Message object:

  • Paragraphs: <p>
  • Headings: <h1>, <h2> (note: h3-h6 appear as h2)
  • Text formatting: <b> (bold), <i> (italic)
  • Links: <a>
  • Images: <img> (can be linked)
  • Line breaks: <br>
  • Code blocks: <code>
  • Lists: <ul> (unordered), <ol> (ordered)

Example HTML:

<!-- Headings (h1–h6) -->
<h1>Heading 1</h1>
<h2>Heading 2</h2>
<h3>Heading 3</h3>
<h4>Heading 4</h4>
<h5>Heading 5</h5>
<h6>Heading 6</h6>

<!-- Paragraphs with inline formatting and link -->
<p>
  Normal paragraph with <a href="https://example.com">a link</a>, <b>bold</b>,
  <i>italic</i>, and a line break<br />right here.
</p>

<!-- Image and linked image -->
<img src="https://placehold.co/600x400/png" alt="Example image" />
<a href="https://example.com"
  ><img src="https://placehold.co/200x120/png" alt="Linked image"
/></a>

<!-- Lists: unordered, ordered-->
<ul>
  <li>Unordered item 1</li>
  <li>Unordered item 2</li>
</ul>

<ol>
  <li>Ordered item 1</li>
  <li>Ordered item 2</li>
</ol>

<!-- Code block -->
<code> console.log('hello world!'); </code>

Agent & Conversation Management

Q: Does the get_agent API need conversation ID parameters?

A: No. get_agent is only used during initial Fin configuration to select which agent represents Fin in the external system. You can return a single hardcoded bot agent here.

Q: How will Intercom inform us that a human agent needs to join a conversation?

A: Intercom sends an update_conversation call with assignee_id set to null.

Attributes & Data Structure

Q: Are conversation-level attributes separate from user attributes?

A: Yes. Structure is:

{
  "conversation": {
    "attributes": {
      // conversation-specific data like locale, topic, sentiment, order_id
    },
    "user": {
      "id": "...",
      "type": "end-user",
      "name": "...",
      "attributes": {
        // user-specific custom attributes
      }
    }
  }
}

Q: When EndUser attributes change, will update_conversation be called?

A: Yes. Conversation and user state is synchronized on each inbound/outbound event (new messages, user data updates via workflows, for example an Email Collector step, etc.).

Request Verification

Q: How do I verify that incoming requests are genuine?

A: We provide two extra headers on our requests to your servers:

  • X-Fin-Request-Timestamp - This is the timestamp of the request (in seconds since epoch). You may use this to reject requests that are too old.
  • X-Fin-Signature - This is the SHA256 HMAC signature of {timestamp}:{request_body}. You may use this to verify the authenticity of the request from us.

Note as there is no body for GET requests, we instead sign: {timestamp}:{request_params_sorted_alphabetically}.

The HMAC key used to validate the signature is found in your deployment settings.

Connecting Fin to your endpoints

1 - Navigate to the Deploy > Fin Messenger section in your Fin Workspace.

standalone-chd-1

2 - You can give your integration a name to identify it. We will support multiple different connections later (e.g. for multiple different sub-brands you may have)

Please note that "Channel type" is currently static with the value "Fin messenger". We will support other channel types at a later time.

Make note of the Identifier value you are given here. This is the identifer you must use in your webhooks back to the Fin system.

3 - Configure your API endpoint URLs. What these endpoints are for and the request/response format is described in the rest of these docs.

standalone-chd-3

4 - Set up authentication for your endpoints. By default we use OAuth for this. Choose the "OAuth token settings" option and configure the OAuth connection with your server.

Note, you may whitelist Intercom's IP address ranges based on the documentation here

standalone-chd-4

standalone-chd-5

5 - Note the webhook secret generated for you. This must be provided in the X-Webhook-Key header in webhook requests to the Fin system.

standalone-chd-6

6 - Choose a agent from your system to attribute Fin's replies to.

When Fin generate a response for the customer, we will use the ID of the agent chosen here when creating messages in your system.

standalone-chd-7

7 - Finally, when you've configured your workflow and installed the Fin Messenger you're ready to activate Fin.

standalone-chd-8

Download OpenAPI description
api-posts-only.json
api-posts-only.yaml
Overview
URL
https://developers.intercom.com
Languages
Servers
Your Custom Helpdesk API (replace with your actual domain)
https://helpdesk.example.com/api/fin/

Users

Manage end-users in your helpdesk system

Operations

Agents

Manage agents in your helpdesk system

Operations

Conversations

Manage conversations between end-users and agents

Operations

Messages

Manage messages within conversations

Operations

Webhooks

Notify Fin when conversations change

Operations

Notify Fin of Conversation Events

Request

This endpoint handles two distinct use cases depending on whether an event_type is provided:

1. Conversation Synchronization (default behavior)

When you omit the event_type field, Fin will synchronize the conversation by pulling the latest data from your endpoints. Use this when:

  • An agent sends a message
  • The conversation state changes (status, assignee, etc.)
  • Any other conversation data changes that Fin should know about

Example payload:

{
  "conversation_id": "conv_456"
}

2. Agent Typing Indicator

When you set event_type to agent_typing, Fin will display a typing indicator to the end-user in the Fin Messenger. No synchronization occurs - this is purely a real-time UI update.

Use this when an agent starts typing a response in your helpdesk. The typing indicator automatically dismisses after a few seconds.

Important: When using event_type: "agent_typing", the data.agent field is required and must include the agent's id, user_type, name, and email.

Example payload:

{
  "conversation_id": "conv_456",
  "event_type": "agent_typing",
  "data": {
    "agent": {
      "id": "agent_001",
      "user_type": "agent",
      "name": "Sarah Johnson",
      "email": "sarah.johnson@company.com"
    }
  }
}
Security
WebhookSignature
Path
integration_idstringrequired

The ID of your integration. You can find this in the Fin Deployment UI.

Example: a3c729d4e8f6b15c
Bodyapplication/jsonrequired
conversation_idstringrequired

ID of the conversation in your system

Example: "conv_456"
event_typestring

Optional. The type of event that occurred.

  • Omitted or null: Fin will synchronize the conversation by pulling the latest data from your endpoints.
  • agent_typing: Displays a typing indicator to the end-user. No synchronization occurs. Requires data.agent to be provided.
Value"agent_typing"
dataobject

Additional event data. Required fields depend on the event_type:

  • For agent_typing: the agent field is required.
curl -i -X POST \
  https://api.intercom.io/hooks/standalone/custom_helpdesk_conversation_event/a3c729d4e8f6b15c \
  -H 'Content-Type: application/json' \
  -H 'X-Webhook-Key: YOUR_API_KEY_HERE' \
  -d '{
    "conversation_id": "conv_456"
  }'

Responses

Webhook accepted

Models

Schemas