Skip to content
Home/
/
Get User

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

Get User

Request

Retrieve an end-user by their ID.

Used to load an end-user from the customer's system. We will call this during synchronization to get the latest data about the end-user to drive the Fin workflows and tasks correctly. If using the Fin messenger with a logged in and verified end-user, we will load the end- user when they start a new conversation.

Security
BearerAuth
Bodyapplication/json
user_idstring

ID of the end-user in your system

Example: "user_123"
curl -i -X POST \
  https://helpdesk.example.com/api/fin/get_user \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "user_id": "user_123"
  }'

Responses

Find a user by their ID

Bodyapplication/json
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.

Response
application/json
{
  "data": {
    "id": "user_123",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "photo_url": "https://example.com/avatars/john.jpg",
    "user_type": "end_user",
    "attributes": { … }
  }
}

Update User

Request

Update an end-user by their ID.

Security
BearerAuth
Bodyapplication/json
user_idstring

ID of the end-user in your system

Example: "user_123"
attributesobject(CustomAttributes)

Attributes associated with the end-user

Example: {"plan_type":"enterprise","signup_date":"2024-01-15","is_premium":true}
curl -i -X POST \
  https://helpdesk.example.com/api/fin/update_user \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "user_id": "user_123",
    "attributes": {
      "plan_type": "enterprise",
      "signup_date": "2024-01-15",
      "is_premium": true
    }
  }'

Responses

User updated successfully

Bodyapplication/json
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.

Response
application/json
{
  "data": {
    "id": "user_123",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "photo_url": "https://example.com/avatars/john.jpg",
    "user_type": "end_user",
    "attributes": { … }
  }
}

Create User

Request

When an end-user starts a conversation in the Fin Messenger and there is no information about them in the third party we request a new record be created.

Security
BearerAuth
Bodyapplication/json
namestring or null

User's name (may not be known at creation time)

Example: "Jane Doe"
emailstring or null(email)

User's email (may not be known at creation time)

Example: "jane.doe@example.com"
object_idstring

Unique identifier for the user in our system

Example: "123456"
attributesobject or null
Example: {"plan_type":"enterprise","signup_date":"2024-01-15","is_premium":true}
curl -i -X POST \
  https://helpdesk.example.com/api/fin/create_user \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Jane Doe",
    "email": "jane.doe@example.com",
    "object_id": "123456",
    "attributes": {
      "plan_type": "enterprise",
      "signup_date": "2024-01-15",
      "is_premium": true
    }
  }'

Responses

End-user created successfully

Bodyapplication/json
idstringrequired

Unique identifier for the user in your system

Example: "user_123456"
user_typestringrequired

Type of user

Value"end_user"
namestring or null

User's display name

Example: "Jane Doe"
emailstring or null(email)

User's email address

Example: "jane.doe@example.com"
photo_urlstring or null(uri)

URL to user's avatar/profile picture (displayed in Fin Messenger)

Example: "https://example.com/avatars/jane.jpg"
attributesobject or null
Example: {"plan_type":"enterprise","signup_date":"2024-01-15","is_premium":true}
Response
application/json
{
  "data": {
    "id": "user_123456",
    "name": "Jane Doe",
    "email": "jane.doe@example.com",
    "photo_url": "https://example.com/avatars/jane.jpg",
    "user_type": "end_user",
    "attributes": { … }
  }
}

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