Skip to content
Home/Webhooks

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

Notify Fin of Conversation Events

Request

This endpoint handles two distinct use cases depending on whether an event_type is provided:

1. Conversation Synchronization (default behavior)

When you omit the event_type field, Fin will synchronize the conversation by pulling the latest data from your endpoints. Use this when:

  • An agent sends a message
  • The conversation state changes (status, assignee, etc.)
  • Any other conversation data changes that Fin should know about

Example payload:

{
  "conversation_id": "conv_456"
}

2. Agent Typing Indicator

When you set event_type to agent_typing, Fin will display a typing indicator to the end-user in the Fin Messenger. No synchronization occurs - this is purely a real-time UI update.

Use this when an agent starts typing a response in your helpdesk. The typing indicator automatically dismisses after a few seconds.

Important: When using event_type: "agent_typing", the data.agent field is required and must include the agent's id, user_type, name, and email.

Example payload:

{
  "conversation_id": "conv_456",
  "event_type": "agent_typing",
  "data": {
    "agent": {
      "id": "agent_001",
      "user_type": "agent",
      "name": "Sarah Johnson",
      "email": "sarah.johnson@company.com"
    }
  }
}
Security
WebhookSignature
Path
integration_idstringrequired

The ID of your integration. You can find this in the Fin Deployment UI.

Example: a3c729d4e8f6b15c
Bodyapplication/jsonrequired
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 when event_type is agent_typing.

curl -i -X POST \
  https://api.intercom.io/hooks/standalone/custom_helpdesk_conversation_event/a3c729d4e8f6b15c \
  -H 'Content-Type: application/json' \
  -H 'X-Webhook-Key: YOUR_API_KEY_HERE' \
  -d '{
    "conversation_id": "conv_456"
  }'

Responses

Webhook accepted

Models

Schemas