Skip to content
Home/
/Procedures

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.

Schemas
Operations

Submit human input to a Fin Procedure HITL step

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
Path
conversation_idstringrequired

The ID of the conversation where the HITL step was triggered.

Example:215473853299345
Headers
Intercom-Versionstring(intercom_version)

Intercom API version.
By default, it's equal to the version set in the app package.

Default:"Preview"
Enum:"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"
Example:Preview
Bodyapplication/jsonrequired
step_idstringrequired

The step_id from the webhook payload, identifying which HITL step this response is for.

Example:"d5b81f72-adb9-4317-b973-75b3c3624c09"
attribute_valuesArray of objectsrequired

Array of attribute values matching the attributes_to_collect from the webhook payload. Must include a value for every attribute listed.

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"
      }
    ]
  }'

Responses

Successful response — the procedure resumes with the provided values.

Bodyapplication/json
object
Response
{}