Intercom API (unofficial showcase)
POST/fin/procedures/{procedure_id}/run

Run a Fin procedure

Runs the specified Fin procedure deterministically on a new conversation. Fin reports progress asynchronously through events or Server-Sent Events; if the procedure pauses for user input, send the reply using the Fin reply operation.

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

2 parameters · 5 body fields
procedure_idstringrequired
The identifier of the procedure to run.
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

Procedure run details. conversation_id 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.
userobjectrequired
A user object representing the user in a Fin Agent conversation.
messageobjectoptional
A message exchanged within a Fin Agent conversation.
conversation_metadataobjectoptional
Metadata about the conversation. Only attributes are accepted (no history).
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, procedure 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.
procedure_idstringoptional
The ID of the procedure that was run.
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

    Procedure not found

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 the conversation_id and user object, including user.id, and include message.author, message.body, and message.timestamp if you supply a message. A 401 is returned when the request is unauthorized. The procedure_id path parameter identifies the procedure to run, and environment must match an available environment if supplied.