HITL Platform icon

HITL Platform

Create human-in-the-loop decision requests and wait for human responses

Overview

This node integrates with a Human-In-The-Loop (HITL) platform to create decision requests that require human responses. It sends tasks or questions to a specified human loop and waits for the response, enabling workflows to incorporate human judgment where automation alone is insufficient.

Common scenarios include:

  • Content moderation where automated filters flag uncertain cases for human review.
  • Quality assurance checks requiring human validation.
  • Complex decision-making tasks needing human input.
  • Gathering subjective feedback or ratings from humans during workflow execution.

Practical example:

  • A workflow detects a suspicious transaction and uses this node to send details to a human reviewer for approval before proceeding.
  • A marketing automation flow asks a human to select the best campaign image from options before launching.

Properties

Name Meaning
Loop Name or ID Selects the human loop group to send the request to. You can choose from a loaded list or specify an ID via expression.
Processing Type Defines how the request is processed:
- Deferred: Normal processing.
- Time-Sensitive: Request has a timeout and requires faster handling.
Content Type Type of content sent in the request:
- Text/Markdown: Plain text or markdown content.
- Image: An image URL included with the request.
Priority Priority level of the request:
- Low
- Medium
- High
- Critical
Request Text The question or task description presented to the human for response.
Image URL URL of the image to include with the request (only shown if Content Type is "Image").
Context Optional additional context data as JSON to provide more information with the request.
Timeout (Seconds) Timeout duration in seconds for time-sensitive requests (range 60–86400). Only applicable if Processing Type is "Time-Sensitive".
Response Type Expected type of human response:
- Multi Select
- Number
- Rating
- Single Select
- Text
- Yes/No
Response Options Comma-separated list of options for single or multi-select response types (e.g., "Yes,No,Maybe").
Rating Minimum Minimum rating value allowed (shown only if Response Type is "Rating").
Rating Maximum Maximum rating value allowed (shown only if Response Type is "Rating").
Default Response Default response value used if the request times out or fails. Its format depends on the Response Type (e.g., a number for rating, a boolean for yes/no).

Output

The node outputs a JSON object per input item containing detailed information about the human-in-the-loop request and its response:

  • request_id: Unique identifier of the HITL request.
  • status: Current status of the request (e.g., completed, answered, failed, timeout).
  • response: The actual response provided by the human or the default response if timed out.
  • response_by: Identifier or info about the user who responded.
  • response_time_seconds: Time taken by the human to respond.
  • message: Informational message about the request outcome (e.g., "Human response received after X seconds").
  • wait_info: Object with metadata about waiting:
    • total_wait_time_seconds: Total time spent waiting for response.
    • polling_cycles: Number of polling attempts made.
    • processing_type: The processing type used.
    • was_timeout: Boolean indicating if the request timed out.
  • polling_used: Always true, indicating the node polls the API until completion.
  • polling_duration_ms: Duration in milliseconds spent polling.
  • full_response: Full raw response data from the API.
  • original_request: Details of the original request sent, including processing type, priority, timeout, broadcast info, notifications, and polling URL.

The node does not output binary data.

Dependencies

  • Requires an API key credential for authenticating with the external HITL platform.
  • Needs network access to the HITL platform's REST API endpoints.
  • Uses HTTP requests to:
    • Load available loops.
    • Create new HITL requests.
    • Poll for request status and responses until completion or timeout.

Troubleshooting

Common Issues

  • Invalid JSON in Context: If the optional context property contains malformed JSON, the node throws an error. Ensure valid JSON formatting.
  • Missing Required Fields: Errors occur if mandatory fields like Loop ID or Request Text are empty.
  • Response Options Missing: For single or multi-select response types, at least one response option must be provided.
  • Invalid Default Response: The default response must match the expected type and constraints (e.g., rating within min/max, boolean as true/false).
  • Image URL Missing: When content type is "Image", the image URL must be provided.
  • API Errors: Network issues or invalid credentials cause API errors. The node surfaces these with messages including HTTP status codes and API error details.
  • Timeouts: Time-sensitive requests may timeout if no human responds in the allotted time, causing the node to return the default response.

Error Messages and Resolutions

  • "Invalid JSON format for context": Fix the JSON syntax in the Context field.
  • "Loop selection is required": Select or specify a valid loop.
  • "Request text is required": Provide a non-empty request text.
  • "Image URL is required when content type is image": Supply a valid image URL.
  • "Response options are required for select types": Enter comma-separated options for single/multi-select.
  • "At least one response option is required for select types": Ensure options are not empty.
  • "Rating maximum must be greater than minimum": Adjust rating min/max values accordingly.
  • "Default response must be a valid number for number/rating type": Correct the default response format.
  • "Default response must be true/false, yes/no, or 1/0 for boolean type": Use valid boolean strings or values.
  • "API Error: ...": Check API key validity, network connectivity, and endpoint availability.

If the node is set to continue on failure, errors will be returned in the output JSON under an error field instead of stopping execution.

Links and References

Discussion