Skip to content
Home/Messages

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.

Download OpenAPI description
api.json
api.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

Get Messages

Request

Called during synchronization to pull in the messages from the conversation in your system. Messages which have already been synchronized will be ignored. New messages will be pulled into Fin’s version of the Conversation.

Security
BearerAuth
Query
conversation_idstring

The ID of the conversation in your system.

after_idstring

ID of the last seen message ID from the external system. As an optimization, the external service may choose to return only messages created after this.

curl -i -X GET \
  'https://helpdesk.example.com/api/fin/messages?conversation_id=string&after_id=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Messages retrieved successfully

Bodyapplication/jsonArray [
idstringrequired

Unique identifier for the message in your system

Example: "msg_001"
conversation_idstringrequired

ID of the parent conversation

Example: "conv_456"
message_typestringrequired

Type of message

Value"comment"
bodystringrequired

Message content in HTML format

Example: "<p>Thank you for reaching out! I'd be happy to explain our pricing plans.</p>"
authorEndUser (object) or Agent (object)required
One of:

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

author.​idstringrequired

Unique identifier for the user in your system

Example: "user_123456"
author.​user_typestringrequired

Type of user

Value"end_user"
author.​namestring or null

User's display name

Example: "Jane Doe"
author.​emailstring or null(email)

User's email address

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

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

Example: "https://example.com/avatars/jane.jpg"
author.​attributesobject or null

Attributes associated with the end-user

Example: {"plan_type":"enterprise","signup_date":"2024-01-15","is_premium":true}
visibilitystringrequired

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"
created_atstring(date-time)required

When the message was created (ISO 8601 UTC)

Example: "2025-10-27T14:35:00.000Z"
attachmentsArray of objects(Attachment)

Files attached to the message

]
Response
application/json
[
  {
    "id": "msg_101",
    "conversation_id": "conv_456",
    "message_type": "comment",
    "body": "<p>Thank you for reaching out! I'd be happy to help.</p>",
    "author": { … },
    "visibility": "public",
    "created_at": "2025-10-27T14:35:00.000Z",
    "attachments": []
  },
  {
    "id": "msg_102",
    "conversation_id": "conv_456",
    "message_type": "comment",
    "body": "<p>Great! Can you tell me about the Enterprise plan?</p>",
    "author": { … },
    "visibility": "public",
    "created_at": "2025-10-27T14:37:00.000Z",
    "attachments": []
  }
]

Create Message

Request

Used during synchronization to push new messages into your helpdesk. These messages may come from either the end-user or Fin. Note that the author of the Fin messages will be the agent selected to represent Fin on initial setup of the integration.

Security
BearerAuth
Bodyapplication/json
conversation_idstring

ID of the parent conversation

Example: "conv_456"
message_typestring

Type of message

Value"comment"
bodystring

Message content in HTML format.

Supported HTML tags are:

  • Paragraphs <p>
  • Heading 1, Heading 2 <h1> <h2> (note h3 to h6 appears as a h2)
  • Bold <b>
  • Italic <i>
  • Links <a>
  • Images <img> (can be linked)
  • Line breaks <br>
  • Code blocks <code>
  • Unordered lists <ul>
  • Ordered lists <ol>
Example: "<p>Hi! I'd like to know more about your pricing plans.</p>"
authorobject

The user who authored the message.

visibilitystring

Message visibility

Enum"public""private"
created_atstring(date-time)

ISO 8601 timestamp

Example: "2025-10-27T14:30:00.000Z"
object_idstring

Unique identifier for the message in our system

Example: "123456"
attachmentsArray of objects(Attachment)

Array of attachments (can be empty)

curl -i -X POST \
  https://helpdesk.example.com/api/fin/messages \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "conversation_id": "conv_456",
    "message_type": "comment",
    "body": "<p>Hi! I'\''d like to know more about your pricing plans.</p>",
    "author": {
      "id": "user_123456",
      "user_type": "end_user"
    },
    "visibility": "public",
    "created_at": "2025-10-27T14:30:00.000Z",
    "object_id": "123456",
    "attachments": [
      {
        "url": "https://example.com/files/pricing-guide.pdf",
        "filetype": "pdf",
        "filename": "Pricing Guide 2025"
      }
    ]
  }'

Responses

Message created successfully

Bodyapplication/json
idstringrequired

Unique identifier for the message in your system

Example: "msg_001"
conversation_idstringrequired

ID of the parent conversation

Example: "conv_456"
message_typestringrequired

Type of message

Value"comment"
bodystringrequired

Message content in HTML format

Example: "<p>Thank you for reaching out! I'd be happy to explain our pricing plans.</p>"
authorEndUser (object) or Agent (object)required
One of:

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

author.​idstringrequired

Unique identifier for the user in your system

Example: "user_123456"
author.​user_typestringrequired

Type of user

Value"end_user"
author.​namestring or null

User's display name

Example: "Jane Doe"
author.​emailstring or null(email)

User's email address

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

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

Example: "https://example.com/avatars/jane.jpg"
author.​attributesobject or null

Attributes associated with the end-user

Example: {"plan_type":"enterprise","signup_date":"2024-01-15","is_premium":true}
visibilitystringrequired

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"
created_atstring(date-time)required

When the message was created (ISO 8601 UTC)

Example: "2025-10-27T14:35:00.000Z"
attachmentsArray of objects(Attachment)

Files attached to the message

Response
application/json
{
  "id": "msg_001",
  "conversation_id": "conv_456",
  "message_type": "comment",
  "body": "<p>Thank you for reaching out! I'd be happy to explain our pricing plans.</p>",
  "author": {
    "id": "user_123456",
    "user_type": "end_user",
    "name": "Jane Doe",
    "email": "jane.doe@example.com",
    "photo_url": "https://example.com/avatars/jane.jpg",
    "attributes": { … }
  },
  "visibility": "public",
  "created_at": "2025-10-27T14:35:00.000Z",
  "attachments": [
    { … }
  ]
}

Webhooks

Notify Fin when conversations change

Operations

Models

Schemas