User input

Workflow reference | Multi-turn

Kind: UserInput
Configuration object: userInput

Use User input to pause a workflow for a person's response. It supports review gates, bounded choices, and free-text input.

Inputs

Prompt and option templates can read the current input and named incoming values. A standalone request also presents the incoming input as context. In a Multi-turn container, the same configuration supplies follow-up feedback with previous and turn available.

Configuration

When free text is disabled, provide at least one option. Responses must exactly match an available rendered option with case-sensitive comparison.

The host must support user-input requests. Workflow Studio Preview provides the interaction surface. A custom runner must receive a fresh WorkflowUserInputSession and submit a pending response using TrySubmit(requestId, response, out error). Sessions serve one run only.

Outputs

The selected or entered response becomes the output as a string. Typed text such as {"approved":true} remains a string until a downstream jsonParse expression converts it.

The request event includes requestId, nodeId, one-based turn, rendered prompt, rendered options, allowFreeText, and optional context. Submission produces an input-received event before the step completes. Late, repeated, canceled, and expired submissions are rejected.

Example

{
  "id": "approve",
  "name": "Request approval",
  "kind": "UserInput",
  "timeoutSeconds": 600,
  "userInput": {
    "promptTemplate": "Choose how to proceed with order {{input.id}}.",
    "options": ["Approve", "Request changes"],
    "allowFreeText": false
  }
}

With input {"id":"A-17"}, the person sees the rendered order prompt. Connect the result to a Condition with equals(input, literal("\"Approve\"")) to select the approved path.

Operational notes

Waiting for a response consumes the configured step and workflow deadlines. Cancellation, timeout, navigation, or closing the session clears pending requests. Invalid responses remain pending with an actionable submission error.

Response size is bounded by the host's text budget and must contain valid UTF-8. Do not request credentials or unnecessary sensitive data through workflow prompts.