Zulip HITL

Human-in-the-loop integration with Zulip

Actions4

Overview

The "Handle User Response" operation in the Zulip HITL (Human-in-the-loop) node monitors a specified Zulip stream (and optionally a topic within that stream) for user responses. It supports different response types such as approval/rejection keywords, choice selections, free-form text input, or automatic detection based on content patterns.

This operation is useful when you want to integrate human feedback or decisions into an automated workflow by waiting for users to respond in Zulip channels. For example, it can be used to:

  • Wait for approval or rejection of a request posted in a Zulip stream.
  • Collect user choices from multiple options.
  • Capture free-text feedback or comments.
  • Automatically detect the type of response and handle accordingly.

The node supports two integration modes: real-time callback processing or periodic polling. It waits for a configurable timeout period for responses before continuing.

Practical Example

A workflow sends a message requesting approval for a deployment. The "Handle User Response" operation monitors the "approval-requests" stream for replies containing approval or rejection keywords. Once a valid response is detected or the timeout expires, the workflow proceeds accordingly.

Properties

Name Meaning
Stream Name Name of the Zulip stream to monitor for responses. Must be lowercase, 1-60 characters, and follow Zulip naming conventions.
Monitor Topic Optional specific topic within the stream to monitor. Leave empty to monitor all topics in the stream.
Response Type Type of response to monitor:
- Approval/Rejection (keywords)
- Choice Selection (multiple options)
- Text Input (free form)
- Auto-Detect (based on content patterns)
Integration Mode How to process responses:
- Callback: process immediately when detected (real-time)
- Polling: check at intervals (batch processing)
Timeout (Minutes) Duration to wait for responses before timing out. Between 1 and 1440 minutes. Longer timeouts allow more time but keep workflow running longer.
Polling Interval (Seconds) Frequency to check for new responses when using polling mode. Minimum 10 seconds, recommended 30-60 seconds to balance responsiveness and API rate limits.
Expected Keywords (for Approval) Comma-separated list of keywords indicating approval. Case-insensitive and partial matches allowed. Examples: "approve", "yes", "confirm".
Rejection Keywords (for Approval) Comma-separated list of keywords indicating rejection. Case-insensitive. Leave empty to only detect approvals. Examples: "reject", "no", "cancel".
Enable Debug Mode Enable detailed debug logging for troubleshooting. May impact performance.
Debug Level Level of detail for debug logs (Debug, Error Only, Info, Trace, Verbose, Warnings).
Debug Categories Specific categories to enable debug logging for (e.g., API calls, Authentication, Network, Performance).
Debug Output Format Format of debug output logs: JSON (machine-readable) or Pretty (human-readable).
Performance Tracking Track operation timing and memory usage for performance analysis. Adds slight overhead.
Include Stack Traces Include stack traces in error/debug logs for deeper debugging. Increases log volume.
Formatting Options Collection of rich text formatting settings:
- Allowed HTML tags
- Enable emoji, markdown, math blocks, mentions, spoilers, tables
- Forbidden HTML tags
- Message style (plain, basic markdown, rich markdown, zulip enhanced)
- XSS protection enabled/disabled

Output

The node outputs a JSON object with fields depending on whether a response was received or a timeout occurred:

  • success: Boolean indicating if a response was successfully received.
  • timedOut: Boolean indicating if the operation timed out waiting for a response.
  • streamName: The monitored Zulip stream name.
  • response (if success): Object containing:
    • id: ID of the Zulip message response.
    • content: Text content of the response.
    • sender: Full name of the user who sent the response.
    • timestamp: Timestamp of the response message.
  • timeoutMinutes: Configured timeout duration (only if timed out).
  • timestamp: ISO timestamp of when the node finished processing.
  • userFeedback: A structured message object providing success or error information for user visibility and logging.

No binary data output is produced by this operation.

Dependencies

  • Requires a valid Zulip API credential with server URL, bot email, and API key.
  • Uses the Zulip API client to connect and monitor streams/topics.
  • Relies on internal modules for markdown processing, validation, recovery management, logging, and user feedback generation.
  • No additional external services beyond Zulip are required.
  • Node configuration must include the Zulip API credentials.

Troubleshooting

Common Issues

  • Missing or invalid credentials: The node will throw an error if no valid Zulip API credentials are provided.
  • Invalid stream or topic names: Names must conform to Zulip naming rules; otherwise, validation errors occur.
  • Timeouts without responses: If no user responds within the configured timeout, the node returns a timeout result.
  • API connection failures: Network issues or incorrect credentials cause connection test failures.
  • Polling interval too low: Values below 10 seconds are rejected to prevent excessive API calls.

Error Messages and Resolutions

  • "No credentials provided": Ensure the node has valid Zulip API credentials configured.
  • "Connection failed": Verify network connectivity and correctness of API credentials.
  • "Stream name required" or "Invalid stream name": Provide a valid stream name following Zulip conventions.
  • "Topic required" or "Invalid topic name": Provide a valid topic name if specified.
  • "Content required" or "Query content cannot be empty": Ensure the message content is not empty.
  • "Timeout must be between 1 and 1440 minutes": Adjust the timeout value within allowed range.
  • "Polling Interval must be between 10 and 3600 seconds": Set polling interval within allowed range.
  • "Failed to send message": Check API permissions and network status.
  • "Approval timeout" or "Response timeout": No user response received within the timeout period.

Enabling debug mode with appropriate levels and categories can help diagnose issues.

Links and References

Discussion