Skip to content
Home/
/
Conversation

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

Webhooks

Notify Fin when conversations change

Operations

Models

Schemas

EndUser

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

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

Attributes associated with the end-user

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

Agent

Agent having a conversation with an end-user.

idstring

Unique identifier for the user in your system

Example: "agent_123456"
user_typestring

Type of user

Value"agent"
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"
aliasstring or null

Agent's display alias (shown to end-users instead of real name)

Example: "Support Jane"
{
  "id": "agent_123456",
  "user_type": "agent",
  "name": "Jane Doe",
  "email": "jane.doe@example.com",
  "photo_url": "https://example.com/avatars/jane.jpg",
  "alias": "Support Jane"
}

Conversation

idstringrequired

Unique identifier for the conversation in your system

Example: "conv_456"
statusstringrequired

Current conversation status:

  • open - Conversation is actively ongoing with the end-user
  • resolved - Conversation is resolved by Fin
  • closed - Conversation is finished/archived
  • ended - Conversation is ended by the end-user or agent
Enum"open""resolved""closed""ended"
userobject(EndUser)required

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

user.​idstringrequired

Unique identifier for the user in your system

Example: "user_123456"
user.​user_typestringrequired

Type of user

Value"end_user"
user.​namestring or null

User's display name

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

User's email address

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

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

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

Attributes associated with the end-user

Example: {"plan_type":"enterprise","signup_date":"2024-01-15","is_premium":true}
titlestring or null

Conversation title or subject

Example: "Question about pricing plans"
tagsArray of strings or null

List of tags associated with the conversation in your system. Can be used to power routing within the Fin workflow among other things.

Example: ["pricing","sales"]
attributesobject

Attributes associated with the conversation

Example: {"issue_type":"Billing","priority":"High"}
assigneeobject(Agent)

Agent having a conversation with an end-user.

created_atstring(date-time)required

When the conversation was created (ISO 8601 UTC)

Example: "2025-10-27T14:30:00.000Z"
updated_atstring(date-time)required

When the conversation was last updated (ISO 8601 UTC)

Example: "2025-10-27T15:45:00.000Z"
{
  "id": "conv_456",
  "status": "open",
  "user": {
    "id": "user_123456",
    "user_type": "end_user",
    "name": "Jane Doe",
    "email": "jane.doe@example.com",
    "photo_url": "https://example.com/avatars/jane.jpg",
    "attributes": { … }
  },
  "title": "Question about pricing plans",
  "tags": [
    "pricing",
    "sales"
  ],
  "attributes": {
    "issue_type": "Billing",
    "priority": "High"
  },
  "assignee": {
    "id": "agent_123456",
    "user_type": "agent",
    "name": "Jane Doe",
    "email": "jane.doe@example.com",
    "photo_url": "https://example.com/avatars/jane.jpg",
    "alias": "Support Jane"
  },
  "created_at": "2025-10-27T14:30:00.000Z",
  "updated_at": "2025-10-27T15:45:00.000Z"
}

Message

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

{
  "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": [
    { … }
  ]
}

Attachment

urlstring(uri)

URL where the attachment can be accessed. Must be HTTPS. Consider using signed URLs with expiration for sensitive files.

Example: "https://example.com/files/pricing-guide.pdf"
filetypestring

File type/extension.

Example: "pdf"
filenamestring

Display name for the file

Example: "Pricing Guide 2025"
{
  "url": "https://example.com/files/pricing-guide.pdf",
  "filetype": "pdf",
  "filename": "Pricing Guide 2025"
}