human_input_required event in the streaming response. The event carries a form_token that your integration uses to drive the form lifecycle until the workflow resumes.
For per-endpoint reference, see the Human Input API.
Which Forms the API Can Reach
To handle a form in your app, the Human Input node must send it to the end user who started the run:- Old Human Input node: web app delivery is enabled.
- New Human Input node: Initiator is among the recipients.
form_token is null. Tokens sent to a form’s other recipients return 404 not_found.
Steps
The sequence below applies to both Workflow and Chatflow apps. Only the entry endpoint in Step 1 differs between the two.1
Start the app in streaming mode
-
Call Run Workflow (Workflow apps) or Send Chat Message (Chatflow apps), passing your end user’s
useridentifier. -
Watch the SSE stream for the
human_input_requiredevent. Capture itsform_token, and itsworkflow_run_idin case you need to resume listening in Step 5. Ifform_tokenisnull, the node doesn’t send the form to your end user: its other recipients answer it by email, in IM, or in the Dify console. Skip to Step 5 to wait for their answer, or stop the run. If the stream drops before you captureform_token, reopen it with Stream Workflow Events, passing theworkflow_run_idfrom the run’s earlierworkflow_startedevent, the sameuser, andinclude_state_snapshot=true. The new stream replays thehuman_input_requiredevent of each form still waiting, with the sameform_token.
2
Get the form definition
Call Get Human Input Form with
form_token, then render the form for the recipient: form_content is its Markdown body, inputs its fields, and user_actions its buttons. Place each field where its placeholder, {{#$output.<output_variable_name>#}}, appears in the body.To pre-fill a paragraph field, check its default:defaultisnull: leave the field empty.default.typeisconstant: pre-filldefault.value.default.typeisvariable: pre-fillresolved_default_values[output_variable_name], the value Dify resolved for this run. If it’s empty or missing, leave the field empty.
select field, offer the options in option_source.value; Dify has already resolved any that come from a variable.Ignore default.selector and option_source.selector: both are deprecated.If the form isn’t submitted by expiration_time, the paused run follows the node’s configured timeout behavior. A resumed stream then carries human_input_form_timeout instead of human_input_form_filled.3
(File inputs only) Upload local files
If the recipient attaches a local file to a
file or file-list input, upload it first with Upload File. It returns an id you reference as upload_file_id in the submit payload. Use one consistent user across the run, upload, and submit calls (see End User Identity for details).A remote file needs no upload step: attach it inline in the submit as a {transfer_method: remote_url, url} mapping.4
Submit the response
Call Submit Human Input Form with the recipient’s input values, the selected
action, and your user. The action must be one of the actions from the form definition in Step 2.File inputs accept either a {transfer_method: local_file, upload_file_id} mapping (from Step 3) or an inline {transfer_method: remote_url, url} mapping. See Upload First vs. Inline Remote URL for the trade-off.A successful submit is final: it closes the form and resumes the run along the matching action branch, so the same form_token can’t be submitted again.A rejected submit (an invalid action, a missing required input, or a failed remote-file fetch) leaves the form unchanged—fix the inputs and resubmit with the same form_token.5
Resume listening to the workflow
If the original SSE stream closed, reopen it via Stream Workflow Events with the
workflow_run_id from Step 1 and the same user that started the run—a different user gets a 404.The resumed stream includes human_input_form_filled confirming the submission (or human_input_form_timeout if the form expired), then the remaining node events through to completion, like a run that never paused.If the workflow has more than one Human Input node in sequence, the stream closes at each pause by default; pass continue_on_pause=true to keep one stream open across all of them.Stop a Paused Run
To end a paused run instead of answering its form, call Stop Workflow Task (Workflow apps) or Stop Chat Message Generation (Chatflow apps) with the run’stask_id, which the stream’s events carry. For a Chatflow app, pass the same user that started the run: with a different one, nothing stops, though the call still returns success.
The run ends as stopped. Its form expires, so the form_token no longer works. A client listening on Stream Workflow Events receives workflow_finished with status stopped.
Upload First vs. Inline Remote URL
Both patterns work for file inputs:-
Pre-upload, then reference
upload_file_id(recommended) Upload File enforces the file size limits at upload time, so the recipient gets immediate feedback and can retry before committing the whole submission. -
Submit inline with
transfer_method: remote_urlThe backend fetches the file at submit time. Faster to integrate, but any size, type, or fetch failure rejects the entire submission, forcing the recipient to redo other fields.
Example: File-Attached Submission
This example uses a form with afeedback paragraph input, an attachments file-list input, and approve / reject actions.
-
Call Get Human Input Form to get the form definition:
Returns the form definition:
-
For each local file, call Upload File:
Returns
{"id": "1a77f0df-...", ...}. -
Call Submit Human Input Form with the recipient’s input and selected action:
Returns
{}. The workflow resumes along theapprovebranch. - Reconnect to the run’s stream with Stream Workflow Events to follow it through to completion, as in Step 5 of the sequence above.