Description

n8n-nodes-velatir

!Velatir
!n8n-community-node-package
!npm version
!License: MIT

Human approval gate for n8n workflows. This community node integrates Velatir to pause your workflow until a human makes a decision, then returns the result on a single output with a state field you can route downstream.

What does it do?

The Velatir node provides a human-in-the-loop approval gate:

1. Data flows in — gets sent to Velatir for human review
2. Workflow pauses — waits for a human decision (polling at a configurable interval)
3. Decision returned on a single output — the velatir.state field contains approved, rejected, or changerequested

To route on the decision, connect a downstream IF or Switch node that branches on {{ $json._velatir.state }}.

Installation

Option 1: Community Nodes Panel (Recommended)

1. Go to Settings > Community Nodes in n8n
2. Select Install
3. Enter n8n-nodes-velatir
4. Select Install

Option 2: Manual Installation

npm install n8n-nodes-velatir

Setup

1. Get your Velatir API Key

• Sign up at velatir.com
• Get your API key from the dashboard

2. Add Credentials in n8n

• Go to Settings > Credentials
• Create new Velatir API credential
• Enter your API key
• Save

Usage

Basic Usage

Drag the Velatir node into your workflow and add an IF or Switch node after it to route on the decision:

Trigger --> [Your Data] --> Velatir --> Switch (on _velatir.state)
                                          |- "approved"         --> Process Data
                                          |- "rejected"         --> Send Rejection Email
                                          |- "change_requested" --> Request More Info

The node will:

• Automatically use your input data as the approval context
• Show the node name and description to approvers
• Return the decision result (with metadata) on a single output
• Include _velatir.state so you can route with a downstream Switch or IF node

Simple Example: Approve-only gate

If you only care about approved requests, use an IF node that checks {{ $json._velatir.state === "approved" }}:

Trigger --> [Your Data] --> Velatir --> IF (state == "approved") --> Process Approved Data

Configuration Options

| Field | Description | Default |
|——-|————-|———|
| Function Name | Name shown to approvers | Node name |
| Description | What this step does | Empty |
| Polling Interval | Check frequency (seconds) | 5 |
| Timeout | Max wait time (minutes) | 10 |
| LLM Explanation | AI context for approval decision | Empty |

Examples

Example 1: Content Review Workflow

Webhook --> Velatir --> Switch (_velatir.state)
                          |- "approved"         --> Publish Content
                          |- "rejected"         --> Archive Content
                          |- "change_requested" --> Send to Editor

Example 2: User Registration with Feedback

Form Submit --> Velatir --> Switch (_velatir.state)
                              |- "approved"         --> Create Account + Welcome Email
                              |- "rejected"         --> Send Rejection Email
                              |- "change_requested" --> Request Additional Info

Example 3: Invoice Processing

New Invoice --> Velatir --> Switch (_velatir.state)
                              |- "approved"         --> Auto-Pay Invoice
                              |- "rejected"         --> Mark as Disputed
                              |- "change_requested" --> Request Clarification

Example 4: Simple Approval Gate

If you only need to process approved requests:

Manual Trigger --> Set (Campaign Data) --> Velatir --> IF (approved?) --> Send Email

The IF node checks {{ $json._velatir.state === "approved" }}.

What Approvers See

When a request needs approval, your team will see:

• Function Name: “Send Email Campaign” (or whatever you set)
• Description: “Send marketing email to 1,500 customers”
• Arguments: All the input data from your workflow
• LLM Explanation: AI context about why approval is needed (if provided)
• Metadata: Workflow context (ID, execution, behavior mode, etc.)

Data Output

The single output includes the original data plus _velatir metadata:

{
  "originalData": "your workflow data",
  "_velatir": {
    "reviewTaskId": "uuid-of-review-task",
    "state": "approved|rejected|change_requested",
    "requestedChange": "feedback from approver (if any)"
  }
}

Route on velatir.state using a downstream IF or Switch node. The requestedChange field contains approver feedback when the state is changerequested.

Best Practices

Do:

• Use descriptive node names (they become the function name)
• Add helpful descriptions for complex operations
• Place approval gates before critical/irreversible actions
• Set appropriate timeouts for your team’s response time
• Provide LLM explanations for better approval context
• Use a Switch node after Velatir to handle all three states explicitly

Don’t:

• Put approval gates in loops (can create many approval requests)
• Set very short timeouts for non-urgent operations
• Ignore the _velatir metadata when processing decisions
• Assume the node has multiple outputs — it has one; route with IF/Switch

Error Handling

The node returns all decisions on a single output. Routing is done by inspecting _velatir.state:

| Scenario | Behavior |
|———-|———-|
| Approved | _velatir.state = "approved" — route via Switch/IF |
| Rejected | _velatir.state = "rejected" — route via Switch/IF |
| Change requested | velatir.state = "changerequested" with requestedChange feedback |
| Timeout | Workflow stops after the configured timeout |
| API error (Continue on Fail enabled) | Error details returned on the single output |
| API error (Continue on Fail disabled) | Workflow stops with error message |

Workflow Patterns

Pattern 1: Simple Approval Gate

Data --> Velatir --> IF (approved?) --> Process Data

Use an IF node checking _velatir.state === "approved". Non-approved items fall through to the false branch (or are dropped).

Pattern 2: Full Decision Handling

Data --> Velatir --> Switch (_velatir.state)
                       |- "approved"         --> Process Data
                       |- "rejected"         --> Log Rejection
                       |- "change_requested" --> Request Info

A Switch node with three branches covers all decision types.

Pattern 3: Feedback Loop

Data --> Velatir --> Switch --> "approved"         --> Process
                            --> "rejected"         --> Archive
                            --> "change_requested" --> Edit --> Velatir (New Review)

Use change requests to improve and resubmit.

Pattern 4: Escalation Workflow

Data --> Velatir --> Switch --> "approved"         --> Execute
                            --> "rejected"         --> End
                            --> "change_requested" --> Senior Velatir --> Execute

Escalate change requests to higher approval levels.

Pattern 5: Conditional Approval

Data --> IF (high_value?) --> Velatir --> Switch --> Process
                          --> Direct Process

Only require approval for certain conditions.

Troubleshooting

| Issue | Solution |
|——-|———-|
| “Request timeout” | Increase timeout or check if approvers are available |
| “API key invalid” | Verify credential configuration in n8n |
| “Request declined” | Check velatir.state and approver feedback in velatir.requestedChange |
| Node doesn’t appear | Restart n8n after installation |
| “Unexpected state” | Update to latest node version (API may have changed) |
| Data not flowing as expected | Verify your Switch/IF node is branching on _velatir.state |

Support

• Velatir Documentation
• n8n Community Forum
• Report Issues
• Contact Support

License

MIT