The intercom API reference.
Home//
REST API Reference
/- Submit human input to a Fin Procedure HITL step
Collect Agent Input Request
Submit human input to a F...
Intercom API (Preview)
Download OpenAPI description
Overview
URL
License
Languages
Servers
The production API server
https://api.intercom.io/
The european API server
https://api.eu.intercom.io/
The australian API server
https://api.au.intercom.io/
AI Content
With the AI Content APIs, you can create and manage External Pages and Content Import Sources for your Fin Content Library.
External Pages are pages that you want Fin to be able to answer questions about. The API for External Pages is a great way to ingest into your Fin Content Library pages that are not publicly accessible and hence can't be crawled by Intercom.
Content Import Sources are the sources of those pages, and they are used to determine the default audience for the pages (configured via the UI). You should create a Content Import Source for each source of External Pages that you want to ingest into your Fin Content Library.
You can then iterate through the content from that source via its API and POST it to the External Pages endpoint. That endpoint has an external_id parameter which allows you to specify the identifier from the source. The endpoint will then either create a new External Page or update an existing one as appropriate.",
SchemasOperations
Custom Object Instances
Everything about your Custom Object instances.
Permission Requirements
From now on, to access this endpoint, you need additional permissions. Please head over to the Developer Hub app package authentication settings to configure the required permissions.
SchemasOperations
Fin Agent
Access Fin programmatically via the Fin Agent API endpoints.
Please reach out to your accounts team to discuss access and tailored, hands-on support.
Integration is centered around two endpoints (/fin/start and /fin/reply) and a set of events that notify your application of Fin's status and responses. Events can be delivered via webhooks or Server-Sent Events (SSE).
Events
Configure a webhook endpoint in the Fin Agent API settings to receive events, or use the sse_subscription_url from the API response to subscribe via SSE. See the setup guide for configuration details.
fin_status_updated- Fired when Fin's status changes (awaiting_user_reply, escalated, resolved, complete)fin_replied- Fired when Fin sends a reply to the userfin_reply_chunk- SSE-only streaming event fired during reply generation (requires streaming enabled)
All webhook requests include an X-Fin-Agent-API-Webhook-Signature header for request validation.
Schemas
Procedures
Submit human-collected input to Fin Procedures via the HITL (Human in the Loop) API.
When a Fin Procedure reaches a HITL step with the API channel enabled, Intercom sends a procedure.hitl_notification.created webhook to your system. Your system collects the required input and responds via the callback endpoint documented here.
This API requires the Procedures HITL API feature to be enabled for your workspace and an OAuth token with the write_conversations scope.
SchemasOperations
Collect Agent Input Request
Request body for submitting human-collected input to a HITL procedure step.
The step_id from the webhook payload, identifying which HITL step this response is for.
Example: "d5b81f72-adb9-4317-b973-75b3c3624c09"
Array of attribute values matching the attributes_to_collect from the webhook payload. Must include a value for every attribute listed.
Must exactly match an identifier from the webhook's attributes_to_collect array.
Example: "workflow_local_variables.72c5a6b3-3cce-41d8-8e30-14da40791958"
{ "step_id": "d5b81f72-adb9-4317-b973-75b3c3624c09", "attribute_values": [ { … } ] }
Request
Submit human-collected input to a Fin Procedure that is paused at a Human in the Loop (HITL) step.
When a procedure reaches a HITL step with the API channel enabled, Intercom sends a procedure.hitl_notification.created webhook. Use the callback_url from that webhook payload to call this endpoint with the collected attribute values.
The step_id must match the one from the webhook payload, and attribute_values must include a value for every attribute listed in attributes_to_collect.
Authentication
This endpoint requires an OAuth token with the write_conversations scope. The admin associated with the token must have access to the conversation.
Feature access
This endpoint requires the Procedures HITL API feature to be enabled for your workspace.
Security
bearerAuth
The step_id from the webhook payload, identifying which HITL step this response is for.
Example: "d5b81f72-adb9-4317-b973-75b3c3624c09"
Array of attribute values matching the attributes_to_collect from the webhook payload. Must include a value for every attribute listed.
Must exactly match an identifier from the webhook's attributes_to_collect array.
Example: "workflow_local_variables.72c5a6b3-3cce-41d8-8e30-14da40791958"
- The production API serverhttps://api.intercom.io/procedures/{conversation_id}/collect_agent_input
- The european API serverhttps://api.eu.intercom.io/procedures/{conversation_id}/collect_agent_input
- The australian API serverhttps://api.au.intercom.io/procedures/{conversation_id}/collect_agent_input
- curl
- Node.js
- Ruby
- PHP
- Python
- Java
- Go
- C#
- R
curl -i -X POST \
https://api.intercom.io/procedures/215473853299345/collect_agent_input \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-H 'Intercom-Version: Preview' \
-d '{
"step_id": "d5b81f72-adb9-4317-b973-75b3c3624c09",
"attribute_values": [
{
"identifier": "workflow_local_variables.72c5a6b3-3cce-41d8-8e30-14da40791958",
"value": true
},
{
"identifier": "workflow_local_variables.5adb55fb-f549-44a0-8ee9-7e652ad77c25",
"value": "85f00ba7-558c-4b02-a397-6f5c3659941c"
}
]
}'Response
application/json
{}