Skip to content
Home/
/
Get 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

Get Conversation

Request

Used to load a known conversation from the customer's system. Used during ongoing synchronizations.

Security
BearerAuth
Query
conversation_idstring
curl -i -X GET \
  'https://helpdesk.example.com/api/fin/conversation?conversation_id=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Conversation found successfully

Bodyapplication/json
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"
Response
application/json
{
  "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"
}

Update Conversation

Request

Called at the end of a synchronization run to push the latest derived data into the Customer’s system.

Security
BearerAuth
Bodyapplication/json
conversation_idstring

ID of the conversation to update

Example: "conv_456"
titlestring or null

Conversation title

Example: "Pricing inquiry - resolved"
tagsArray of strings

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"}
statusstring

Conversation status

Enum"open""resolved""closed""ended"
Example: "resolved"
assignee_idstring

Agent ID (Fin agent). Set to null when handing over to a human agent.

Example: "agent_fin"
last_user_read_atstring or null(date-time)

When user last read the conversation

Example: "2025-10-27T15:45:00.000Z"
curl -i -X PUT \
  https://helpdesk.example.com/api/fin/conversation \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "conversation_id": "conv_456",
    "title": "Pricing inquiry - resolved",
    "tags": [
      "pricing",
      "sales"
    ],
    "attributes": {
      "issue_type": "Billing",
      "priority": "High"
    },
    "status": "resolved",
    "assignee_id": "agent_fin",
    "last_user_read_at": "2025-10-27T15:45:00.000Z"
  }'

Responses

Conversation updated successfully

Bodyapplication/json
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"
Response
application/json
{
  "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"
}

Create Conversation

Request

Called when a new conversation has been created via the Fin Messenger. Note we provide the initial message from the conversation as we know many help desks require this to be provided when creating a conversation. The response requires both the conversation object and the message object so that these can be mapped correctly to their Fin equivalents.

Security
BearerAuth
Bodyapplication/json
titlestring or null

Conversation title (may be blank)

Example: "Question about pricing"
user_idstring

ID of the end-user in your system

Example: "user_123"
object_idstring

Unique identifier for the conversation in our system

Example: "123456"
initial_messageobject
curl -i -X POST \
  https://helpdesk.example.com/api/fin/conversation \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Question about pricing",
    "user_id": "user_123",
    "object_id": "123456",
    "initial_message": {
      "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",
      "attributes": {
        "issue_type": "Billing",
        "priority": "High"
      },
      "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

Conversation created successfully

Bodyapplication/json
conversationobject(Conversation)required
conversation.​idstringrequired

Unique identifier for the conversation in your system

Example: "conv_456"
conversation.​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"
conversation.​userobject(EndUser)required

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

conversation.​user.​idstringrequired

Unique identifier for the user in your system

Example: "user_123456"
conversation.​user.​user_typestringrequired

Type of user

Value"end_user"
conversation.​user.​namestring or null

User's display name

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

User's email address

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

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

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

Attributes associated with the end-user

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

Conversation title or subject

Example: "Question about pricing plans"
conversation.​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"]
conversation.​attributesobject

Attributes associated with the conversation

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

Agent having a conversation with an end-user.

conversation.​created_atstring(date-time)required

When the conversation was created (ISO 8601 UTC)

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

When the conversation was last updated (ISO 8601 UTC)

Example: "2025-10-27T15:45:00.000Z"
initial_messageobject(Message)required
initial_message.​idstringrequired

Unique identifier for the message in your system

Example: "msg_001"
initial_message.​conversation_idstringrequired

ID of the parent conversation

Example: "conv_456"
initial_message.​message_typestringrequired

Type of message

Value"comment"
initial_message.​bodystringrequired

Message content in HTML format

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

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

initial_message.​author.​idstringrequired

Unique identifier for the user in your system

Example: "user_123456"
initial_message.​author.​user_typestringrequired

Type of user

Value"end_user"
initial_message.​author.​namestring or null

User's display name

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

User's email address

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

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

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

Attributes associated with the end-user

Example: {"plan_type":"enterprise","signup_date":"2024-01-15","is_premium":true}
initial_message.​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"
initial_message.​created_atstring(date-time)required

When the message was created (ISO 8601 UTC)

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

Files attached to the message

Response
application/json
{
  "conversation": {
    "id": "conv_456",
    "status": "open",
    "user": { … },
    "title": "Question about pricing plans",
    "tags": [ … ],
    "attributes": { … },
    "assignee": { … },
    "created_at": "2025-10-27T14:30:00.000Z",
    "updated_at": "2025-10-27T15:45:00.000Z"
  },
  "initial_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": { … },
    "visibility": "public",
    "created_at": "2025-10-27T14:35:00.000Z",
    "attachments": [ … ]
  }
}

Messages

Manage messages within conversations

Operations

Webhooks

Notify Fin when conversations change

Operations

Models

Schemas