Intercom API (unofficial showcase)
POST/fin/start

Start a Fin conversation

Starts a Fin conversation using the user's message, user details, and any supplied conversation context. Include the conversation ID, message, and user; Fin processes the conversation asynchronously and signals completion through a webhook.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 6 body fields
Intercom-Versionstringoptional
The Intercom API version to use. Defaults to 2.17 when omitted; use a supported version.
Allowed:1.01.11.21.31.42.02.12.22.32.42.52.6Default:2.17

Fin conversation initialization details. conversation_id, message, and user are required.

conversation_idstringrequired
The ID of the conversation that is calling Fin via this API.
messageobjectrequired
A message exchanged within a Fin Agent conversation.
userobjectrequired
A user object representing the user in a Fin Agent conversation.
attachmentsarray<FinAgentAttachment>optional
An array of attachments to include with the message. Maximum of 10 attachments.
conversation_metadataobjectoptional
Metadata about the conversation, including history and attributes.
environmentstringoptional
The identifier of the environment to start the conversation in, if your Fin for Platforms workspace has environments. Use the same value as `messenger_environment` in your Messenger installation. Defaults to the workspace's default environment; an identifier that matches no environment is rejected.

3 status codes
200Returns the conversation ID, user ID, current Fin status, creation timestamp, and other conversation details, including an optional SSE subscription URL.
conversation_idstringoptional
The ID of the conversation.
intercom_conversation_idstringoptional
The internal Intercom conversation ID, useful for matching this Agent API session to the conversation in Intercom.
user_idstringoptional
The ID of the user.
statusstringoptional
Fin's current status in the conversation workflow.
Allowed:thinkingreplyingawaiting_user_replyescalatedresolvedcomplete
created_at_msstringoptional
The timestamp the response was created at, with millisecond precision.
errorsobjectoptional
Contains error details if any user or conversation attribute updates failed.
sse_subscription_urlstringoptional
Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. When CSAT is enabled and a survey will follow the resolution, `complete` revocation is deferred until the `csat_requested` event is delivered or the token expires.
400Returned when the request is invalid, such as when required fields are missing or a supplied value does not meet the request requirements.

One documented failure

  • parameter_invalid

    conversation_id is required

typestringrequired
The type is error.list
request_idstringoptional
errorsarray<object>required
An array of one or more error objects
401Returned when the request is unauthorized.

One documented failure

  • unauthorized

    Access Token Invalid

typestringrequired
The type is error.list
request_idstringoptional
errorsarray<object>required
An array of one or more error objects

Error handling

A 400 is returned when required fields are missing or request values are invalid; provide conversation_id, message, and user, including message.author, message.body, and message.timestamp, and user.id. A 401 is returned when the request is unauthorized. Limit attachments and conversation history to 10 items each, user attributes to 10, and conversation attributes to 20; environment must identify an available environment if supplied.