n8n Integration - Omnara Documentation

Overview

The Omnara n8n integration (n8n-nodes-omnara) enables workflows to communicate with users in real-time through the Omnara platform. Perfect for approval workflows, agent conversations, and guided automation. Key Capabilities:

Send non-blocking status updates
Ask questions and wait for responses
AI Agent compatibility
Multi-channel notifications (email, SMS, push)
Session management

Installation

Install the community node in your n8n instance:

npm install n8n-nodes-omnara

Or via the n8n UI:

Go to Settings → Community Nodes
Search for n8n-nodes-omnara
Click Install

View on npm

Full package documentation and changelog

Quick Start

Add Credentials

In n8n, go to Credentials → New
Select Omnara API
Enter your API key from omnara.com/dashboard
Optionally set custom server URL for self-hosted instances

Add Omnara Node

Drag the Omnara node into your workflow

Configure Operation

Choose an operation:

Send Message: Non-blocking status update
Send and Wait: Ask question and pause workflow
End Session: Mark agent session as complete

Test It

Execute your workflow and check the Omnara dashboard for messages

Operations

Send Message (Non-blocking)

Send informational messages without waiting for response. When to use:

Progress updates
Status notifications
Logging agent actions

Example:

{
  "operation": "send",
  "agentType": "Deployment Agent",
  "message": "Build completed successfully ✅",
  "options": {
    "sendPush": true
  }
}

Returns:

message_id: ID of created message
agent_instance_id: Session identifier
queued_user_messages: Any pending user responses

Check queued_user_messages on every send to catch user responses sent between operations.

Send and Wait (Blocking)

Ask questions and pause workflow until user responds. When to use:

Approval workflows
User input required
Decision points

Two Modes:

Webhook Mode (Default)
Sync Mode (AI Agents)

For regular workflows

Uses n8n’s webhook system
Efficient, event-driven
Resumes workflow when user responds
Max wait: 7 days

{
  "operation": "sendAndWait",
  "message": "Approve deployment to production?",
  "limitWaitTime": true,
  "limitType": "afterTimeInterval",
  "resumeAmount": 1,
  "resumeUnit": "hours"
}

End Session

Mark agent session as completed.

{
  "operation": "endSession",
  "agentInstanceId": "{{ $json.agent_instance_id }}"
}

Configuration Examples

Simple Approval Workflow

{
  "nodes": [
    {
      "name": "Build App",
      "type": "n8n-nodes-base.executeCommand",
      "parameters": {
        "command": "npm run build"
      }
    },
    {
      "name": "Request Approval",
      "type": "n8n-nodes-omnara.omnara",
      "parameters": {
        "operation": "sendAndWait",
        "agentType": "Deployment Bot",
        "message": "Build complete. Deploy to production?",
        "options": {
          "sendEmail": true,
          "sendPush": true
        },
        "limitWaitTime": true,
        "resumeAmount": 1,
        "resumeUnit": "hours"
      }
    },
    {
      "name": "Deploy",
      "type": "n8n-nodes-base.executeCommand",
      "parameters": {
        "command": "npm run deploy"
      }
    }
  ]
}

AI Agent Integration

{
  "nodes": [
    {
      "name": "AI Agent",
      "type": "@n8n/n8n-nodes-langchain.agent",
      "parameters": {
        "tools": ["omnara"],
        "prompt": "You can ask the user questions using the omnara tool."
      }
    },
    {
      "name": "Omnara Tool",
      "type": "n8n-nodes-omnara.omnara",
      "parameters": {
        "operation": "sendAndWait",
        "message": "{{ $json.question }}",
        "options": {
          "syncMode": true,        // Required for AI Agents
          "syncTimeout": 600,
          "pollInterval": 5,
          "sendEmail": true
        }
      }
    }
  ]
}

Agent Instance Management

Session Tracking

Each workflow execution should use a consistent agent_instance_id: Pattern 1: Webhook-triggered (Recommended)

// Omnara dashboard triggers workflow with pre-generated ID
{
  "agent_instance_id": "{{ $json.agent_instance_id }}", // From webhook
  "agent_type": "{{ $json.agent_type }}"
}

Pattern 2: Self-generated

// Generate UUID in Set node
{
  "agent_instance_id": "{{ $uuid() }}",
  "agent_type": "My Workflow"
}
// Reference in all subsequent Omnara nodes

Queued Messages

Omnara returns queued user messages with every agent message:

const response = await omnaraNode.execute();
// response.queued_user_messages contains any user responses since last check

This ensures you never miss user input, even if timing is off.

Notifications

Control how users are notified:

sendEmail

boolean

default:"false"

Send email notification

sendSMS

boolean

default:"false"

Send SMS notification (requires phone verification)

sendPush

boolean

default:"false"

Send push notification (via mobile app or web push)

Priority:

Message-level override (in request)
User preferences (in dashboard)
Default: no notifications

Error Handling

{
  "nodes": [
    {
      "name": "Omnara",
      "type": "n8n-nodes-omnara.omnara",
      "continueOnFail": true,
      "parameters": {
        "operation": "send",
        "message": "Status update"
      }
    }
  ]
}

With continueOnFail: true, errors are returned as data:

{
  "error": "Failed to send message: Connection timeout",
  "resource": "message",
  "operation": "send",
  "itemIndex": 0
}

Troubleshooting

Webhook not resuming workflow

Causes:

Using sync mode in regular workflow (use webhook mode)
Webhook URL incorrect in message metadata
Workflow execution already timed out

Fix:

// Ensure sync mode is false (or omitted) for regular workflows
{
  "options": {
    "syncMode": false  // or omit entirely
  }
}

AI Agent tool not working

Causes:

Missing syncMode: true
Using webhook mode in AI Agent context

Fix:

// MUST use sync mode for AI Agents
{
  "options": {
    "syncMode": true,
    "syncTimeout": 600,
    "pollInterval": 5
  }
}

Messages not appearing in dashboard

Causes:

Incorrect API key
Wrong server URL
Network/firewall issues

Fix:

Test credentials: Check credential test passes
Verify server URL (default: https://agent.omnara.com)
Check n8n logs for error details

Timeout waiting for response

Causes:

User didn’t respond in time
Poll interval too long
Sync timeout too short

Fix:

// Adjust timeouts
{
  "limitWaitTime": true,
  "resumeAmount": 2,       // 2 hours instead of 1
  "resumeUnit": "hours",
  "options": {
    "syncTimeout": 1200,   // 20 minutes
    "pollInterval": 3      // Check every 3 seconds
  }
}

API Endpoints

The n8n node uses these Omnara API endpoints:

Endpoint	Method	Purpose
`/api/v1/messages/agent`	POST	Send message (both send & sendAndWait)
`/api/v1/messages/pending`	GET	Poll for user responses (sync mode)
`/api/v1/sessions/end`	POST	End agent session
`/api/v1/auth/verify`	GET	Validate credentials

Best Practices

Use descriptive agent types

// Good
agentType: "Deployment Bot - Production"

// Bad
agentType: "Bot"

Helps identify sessions in dashboard when running multiple workflows.

Set appropriate timeouts

// For urgent approvals
resumeAmount: 30
resumeUnit: "minutes"

// For non-urgent requests
resumeAmount: 24
resumeUnit: "hours"

Balance between user convenience and workflow efficiency.

Always end sessions

// Add at end of workflow
{
  "name": "End Session",
  "operation": "endSession",
  "agentInstanceId": "{{ $('Request Approval').item.json.agent_instance_id }}"
}

Keeps dashboard clean and marks sessions as complete.

Handle queued messages

// Check for user responses on every send
const response = await omnaraNode.send(message);
if (response.queued_user_messages.length > 0) {
  // Process user feedback
  const userMessage = response.queued_user_messages[0];
  console.log('User said:', userMessage.content);
}

Ensures you don’t miss user input sent between operations.

GitHub Actions

Integrate with GitHub workflows

Python SDK

Build custom integrations

REST API

Direct API access

MCP Integration

Connect with MCP clients

Integrations

​Overview

​Installation

View on npm

​Quick Start

​Operations

​Send Message (Non-blocking)

​Send and Wait (Blocking)

​End Session

​Configuration Examples

​Simple Approval Workflow

​AI Agent Integration

​Agent Instance Management

​Session Tracking

​Queued Messages

​Notifications

​Error Handling

​Troubleshooting

​API Endpoints

​Best Practices

​Related Documentation

GitHub Actions

Python SDK

REST API

MCP Integration

Overview

Installation

Quick Start

Operations

Send Message (Non-blocking)

Send and Wait (Blocking)

End Session

Configuration Examples

Simple Approval Workflow

AI Agent Integration

Agent Instance Management

Session Tracking

Queued Messages

Notifications

Error Handling

Troubleshooting

API Endpoints

Best Practices

Related Documentation