Human In The Loop Block

The Human In The Loop (HITL) block introduces human oversight into automated workflows. It sends an approval link over a messaging or email platform, pauses the execution, and resumes down either the Approved or Rejected branch once a person decides.

Key Features

• Pause and Resume - The execution is set to PAUSED at the HITL block and resumes when a reviewer submits a decision
• Platform Attachment - The approval link is delivered by an attached block (Slack, Telegram, Gmail, Send Email, Twilio, or WhatsApp)
• Two-Way Branch - Fixed Approved / Rejected outputs, each with its own downstream flow
• Reviewer Response Capture - Optionally save the reviewer's written response into a workflow variable
• Editable Review Data - The approval page shows the output of every upstream block and lets the reviewer edit the values
• Context for Reviewer - Key label/value facts appended to the notification so the reviewer can act without looking anything else up
• Signed Approval Links - Each link carries an HMAC token that the approval page and resume endpoint verify

When to Use Human In The Loop

Configuration

Supported Platform blocks

Attach exactly one of these to the Platform slot. The block appends the approval link (and any context items) to that block's message body before sending it:

Any other block type attached to the slot will be executed, but no link is appended to it — so the reviewer never receives a way to respond.

Setup Guide

Step 1: Add the HITL Block

1. Open your workflow in the editor
2. Navigate to Logic blocks
3. Drag the Human In The Loop block onto your canvas
4. Connect it in the workflow where human review is needed

Step 2: Attach a Platform block

1. Add one of the supported platform blocks to the canvas
2. Connect it to the HITL block's Platform attachment endpoint
3. Configure its credentials and recipient (channel, chat id, or email address)
4. Write any message body you want; the approval link is appended to it automatically

Step 3: Write the Prompt Message

Describe what the reviewer needs to decide. This text appears in the Input Required panel of the approval page.

Step 4: Add Context for the Reviewer

Add label/value pairs so the notification carries the facts needed to decide:

Customer Name  →  {{customerName}}
Order ID       →  {{orderId}}
Amount         →  {{orderTotal}}

These are appended to the notification under a *Context:* heading.

Step 5: Capture the Reviewer's Response (optional)

Select a workflow variable under Save review to variable. The approval page then shows a Your Review textarea, and the text is written into that variable when the reviewer submits — so downstream blocks can reference it.

Step 6: Connect Both Branches

Connect the Approved and Rejected endpoints to their downstream flows. Both branches are always present; there are no custom action options.

The Approval Page

The link points at /approvals/{workflowId}/{executionId}/{blockId}?token=… in the builder app and shows:

• Input Required — the configured prompt message
• Review Data — an accordion of every upstream block's output, rendered as editable fields. The reviewer can change values before deciding, and the edited data is sent back with the decision
• Your Review — a free-text field, only when a review variable is configured
• Reject and Approve buttons

Page states

A second submission (a double click, or another browser tab) returns HTTP 409 and the reviewer is shown the same confirmation rather than an error.

Output Variables

The decision is delivered as a branch, not as an output field — the block itself records no action variable. What you can read downstream is:

Workflow Branching

Human In The Loop
    │
    ├── Approved  ──→ Continue normal workflow
    │
    └── Rejected  ──→ Send rejection notification → End workflow

Internally each edge carries a fixed conditionId (approved-condition or rejected-condition). When the execution pauses, every outgoing edge is parked; on resume the engine prunes the branch that was not chosen, so only one side ever runs.

Use Case Examples

Content Approval Workflow

AI Generates Content → Human In The Loop (Platform: Slack) → Approved → Publish
                                                           → Rejected → Notify author

Configuration:
- Prompt: "New AI-generated blog post needs approval before publishing."
- Context: Title → {{postTitle}}, Audience → {{targetAudience}}
- Save review to variable: editorNotes

Large Order Verification

Order Received → Condition (Amount > 10000) → Human In The Loop (Platform: Send Email)
                                                → Approved → Process Order
                                                → Rejected → Cancel and notify customer

Configuration:
- Prompt: "This order exceeds the $10,000 threshold. Please review and approve."
- Context: Order ID → {{orderId}}, Customer → {{customerName}}, Total → {{orderTotal}}

AI Response Quality Gate

User Query → LLM Agent → AI Judge → (low score) → Human In The Loop (Platform: Slack)
                                                    → Approved → Send response
                                                    → Rejected → Regenerate

Configuration:
- Prompt: "The AI judge flagged this response. Please review before it is sent."
- Context: Question → {{userQuery}}, Draft → {{aiResponse}}
- Save review to variable: reviewerEdit

Best Practices

1. Always attach a Platform block — the block fails without one
2. Provide Complete Context — use context items so the reviewer does not have to look anything up
3. Connect Both Branches — an unconnected Rejected branch silently ends the flow
4. Write an Explicit Prompt — the default text is only "Please review and select an option to continue."
5. Use the Review Variable — capture why a decision was made, not just which button was pressed
6. Keep Review Data Small — every upstream block's output is rendered on the page
7. Treat Links as Secrets — anyone holding the signed link can decide
8. Minimize Fatigue — gate HITL behind a condition or AI Judge so humans only see real edge cases

Error Handling

Troubleshooting

Notifications not arriving:

• Verify the attached platform block's credentials in workspace settings
• Confirm the bot or integration has access to the target channel
• Check the execution logs: the HITL log line names the platform it sent through

Approval link 404s or errors:

• NEXTAUTH_URL must point at the publicly reachable builder URL — the link is built from it
• The token is part of the link; a link copied without the ?token=… query string will not authorise

Workflow stuck waiting:

• There is no timeout. A paused execution waits indefinitely until someone decides
• Check the execution status is PAUSED and re-send the approval link if needed