Intercom API (unofficial showcase)
POST/fin/ask

Ask Fin a question

Submits a single, self-contained question to Fin and starts a non-conversational request. Fin returns its answer asynchronously through the fin_replied event and completes the conversation without an awaiting_user_reply cycle.

  • 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

A one-shot question and its context. conversation_id, message, and user are required.

conversation_idstringrequired
Your external conversation ID. Fin creates a conversation for this ID. If a conversation already exists for it, use `/fin/reply` instead.
messageobjectrequired
A message exchanged within a Fin Agent conversation.
userobjectrequired
A user object representing the user in a Fin Agent conversation.
conversation_metadataobjectoptional
Metadata about the conversation, including history and attributes.
attachmentsarray<FinAgentAttachment>optional
An array of attachments to include with the message. Maximum of 10 attachments.
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 external and internal conversation IDs, user ID, current Fin status, creation timestamp, and other conversation details, including an optional SSE subscription URL.
conversation_idstringoptional
The external 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:thinkingreplyingresolvedcomplete
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 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

    External 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 conversation_metadata.history to 10 messages, conversation_metadata.attributes to 20 attributes, and attachments to 10 items; environment must match an available environment if supplied.