Skip to content
Home/
/
WebhookConversationEventR...

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

Models

Schemas

CreateMessageRequest

Message input fields for creation. Either body or attachments (or both) must be provided. A message cannot be empty - it must contain either text content or at least one attachment.

message_typestring(MessageType)

Type of message

Value"comment"
Example: "comment"
bodystring or null
Example: "<p>Hi! I'd like to know more about your pricing plans.</p>"
authorobject(MessageAuthor)

The user who authored the message

visibilitystring(MessageVisibility)

Who can see the message:

  • public - Visible to end-users (appears in Fin Messenger)
  • private - Only visible to agents (internal notes)
Enum"public""private"
Example: "public"
object_idstring

Unique identifier for the message in our system

Example: "123456"
attachmentsArray of objects(Attachment)

Array of attachments (can be empty)

conversation_idstring

ID of the parent conversation

Example: "conv_456"
{
  "message_type": "comment",
  "body": "string",
  "author": {
    "id": "user_123456",
    "user_type": "end_user",
    "name": "Jane Doe",
    "email": "jane.doe@example.com",
    "photo_url": "https://example.com/avatars/jane.jpg"
  },
  "visibility": "public",
  "object_id": "123456",
  "attachments": [
    { … }
  ],
  "conversation_id": "conv_456"
}

WebhookConversationEventRequest

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.
{
  "conversation_id": "conv_456",
  "event_type": "agent_typing",
  "data": {
    "agent": { … }
  }
}

EndUserResponse

dataobject(EndUser)

End user having a conversation with Fin or with an agent.

errorobject(ProblemDetails)

The error returned by the API. This is an RFC 7807 problem details object: https://www.rfc-editor.org/rfc/rfc7807.html.

{
  "data": {
    "id": "user_123456",
    "user_type": "end_user",
    "name": "Jane Doe",
    "email": "jane.doe@example.com",
    "photo_url": "https://example.com/avatars/jane.jpg",
    "attributes": { … }
  },
  "error": {
    "type": "string",
    "title": "string",
    "status": 0,
    "detail": "string",
    "instance": "string"
  }
}