> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shieldbase.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Interactive Workflow Inputs

> Start and continue workflows with forms, files, and choices

# Interactive workflows for Shieldbase Mini

Existing workflow API requests retain their behavior. This is an opt-in addition for WhatsApp/Telegram clients; no workflow definition changes are needed.

Use the existing external API authentication headers (`X-Client-ID`, `X-API-Key`, `X-Secret`), and `X-Tenant-ID` for the intended tenant. The API key owner is the execution identity. `external_user` is display metadata, not authorization.

1. `POST /external/workflows/{group_id}/runs` with `{"interactive":true}` and optional existing `inputs`/`external_user` fields. Retain the returned `run_id`. Starting is asynchronous.
2. Poll `GET /external/workflows/runs/{run_id}/inputs` (for example every 2 seconds, backing off on errors). `waiting_inputs` contains the current `queue_id`, opaque `task_token`, `step`, and any validation message. An empty list is not completion: inspect `status` and the existing run-detail endpoint for execution errors/results.
3. Ask only for the returned step. `expects` is `form`, `file`, `choice`, `message`, or `approval`. Forms expose `formFields` and `form_sections` with required, conditional, options, repeated-row and file constraints. Do not invent values. Use the existing upload API and pass resulting URLs for files. Approval must be performed by its authorized approver; this endpoint does not grant approval rights.
4. `POST /external/workflows/runs/{run_id}/inputs`:

```json theme={null}
{
  "queue_id": "<returned queue UUID>",
  "task_token": "<returned token>",
  "command_id": "<new UUID for this answer>",
  "answer": {"Employee Name": "BB Tan", "Purpose of Expense": "Dental claim"},
  "file_urls": {"Receipt": "https://your-upload-location/receipt.pdf"}
}
```

For simple forms, `answer` maps exact field names to values. For repeatable forms, send the existing canonical `formFields` payload with row metadata. For text/choices, send a string; choices accept a returned option ID or label. File-only steps may omit `answer`. Submission returns HTTP 202 and continues the **same run and workflow version**; poll again to discover the next actual graph step.

Reuse the same `command_id` and identical body when retrying an uncertain response. A changed answer needs a new command. HTTP 409 means the task changed, was already answered, or needs an approver; refresh state before acting. Invalid form data remains subject to runtime validation and can return as a waiting task with a validation message. HTTP 402/503 credit/rule admission failures must not be presented as success.

The API does not interpret natural language or generate missing values: Mini maps chat messages to the returned schema. Child-workflow approval waits and non-input pauses retain their existing lifecycle; an empty input list must not cause Mini to restart a workflow. Historical failed runs are not automatically repaired or replayed by opting into this mode.

[Download the Word guide](https://docs.shieldbase.ai/guides/workflow-interactive-inputs.docx)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.