N8N Integration

N8N is a powerful open-source workflow automation platform that connects various apps and services. You can integrate N8N with Evolution API to create sophisticated WhatsApp automation workflows.

What is N8N?

N8N provides:

Visual workflow builder with 400+ integrations
Custom code execution (JavaScript/Python)
Webhook triggers and actions
Database connectors
API integrations
Conditional logic and branching
Error handling and retry logic
Scheduled workflows

Enable N8N Integration

Add this environment variable to your .env file:

# Enable N8N integration
N8N_ENABLED=true

Configuration Settings

Create Default Settings

Before creating N8N bots, configure default behavior settings for your instance.

curl -X POST https://your-api.com/n8n/settings/{instance} \
  -H "apikey: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "expire": 300,
    "keywordFinish": "#EXIT",
    "delayMessage": 1000,
    "unknownMessage": "I did not understand your message.",
    "listeningFromMe": false,
    "stopBotFromMe": false,
    "keepOpen": false,
    "debounceTime": 10,
    "ignoreJids": []
  }'

Settings Parameters

expire

number

required

Session expiration time in seconds. Default: 300 (5 minutes)

keywordFinish

string

required

Keyword to terminate the bot session. Example: “#EXIT”, “bye”

delayMessage

number

required

Delay in milliseconds between messages. Default: 1000

unknownMessage

string

required

Message sent when bot encounters an error or cannot respond

listeningFromMe

boolean

required

Whether bot responds to messages sent by the instance owner

stopBotFromMe

boolean

required

Whether instance owner can stop the bot session

keepOpen

boolean

required

Keep session open after completion. Default: false

debounceTime

number

required

Seconds to wait before processing rapid messages. Default: 10

ignoreJids

array

required

List of JIDs (phone numbers) to ignore

Create an N8N Bot

Create N8N Workflow

Build your automation workflow in N8N with a Webhook node as the trigger.

Get webhook URL

Copy the production webhook URL from your N8N workflow.

Configure authentication (optional)

If using Basic Auth in N8N, note your username and password.

Create bot in Evolution API

Test the integration

Send a message matching your trigger to invoke the N8N workflow.

curl -X POST https://your-api.com/n8n/create/{instance} \
  -H "apikey: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "description": "Order Processing Workflow",
    "webhookUrl": "https://n8n.yourdomain.com/webhook/order-process",
    "basicAuthUser": "n8n-user",
    "basicAuthPass": "secure-password",
    "triggerType": "keyword",
    "triggerOperator": "startsWith",
    "triggerValue": "order",
    "expire": 300,
    "keywordFinish": "#EXIT",
    "delayMessage": 1000,
    "unknownMessage": "Sorry, something went wrong.",
    "listeningFromMe": false,
    "stopBotFromMe": false,
    "keepOpen": false,
    "debounceTime": 10
  }'

Request Parameters

enabled

boolean

required

Enable or disable this bot

description

string

required

Description of the bot purpose

webhookUrl

string

required

N8N webhook URL (production URL from your workflow)

basicAuthUser

string

Basic authentication username (if webhook is protected)

basicAuthPass

string

Basic authentication password (if webhook is protected)

triggerType

string

required

Trigger type: “all”, “keyword”, or “advanced”

triggerOperator

string

For keyword triggers: “equals”, “contains”, “startsWith”, “endsWith”, “regex”

triggerValue

string

The keyword or regex pattern to trigger this bot

Webhook Payload

When a trigger is matched, Evolution API sends this payload to your N8N webhook:

{
  "chatInput": "user message content",
  "sessionId": "unique-session-id",
  "remoteJid": "[email protected]",
  "pushName": "User Name",
  "instanceName": "my-instance",
  "messageType": "conversation",
  "message": {
    "key": {
      "remoteJid": "[email protected]",
      "fromMe": false,
      "id": "message-id"
    },
    "message": {
      "conversation": "user message"
    },
    "messageTimestamp": 1234567890
  }
}

Payload Fields

chatInput

string

The text content of the user’s message

sessionId

string

Unique session identifier for tracking conversation context

remoteJid

string

WhatsApp JID of the sender

pushName

string

Display name of the sender

instanceName

string

Name of the Evolution API instance

messageType

string

Type of message: “conversation”, “imageMessage”, “audioMessage”, etc.

message

object

Complete WhatsApp message object with metadata

N8N Response Format

Your N8N workflow should return a response in this format:

{
  "messages": [
    {
      "type": "text",
      "content": "Thank you for your order! Your order number is #12345."
    },
    {
      "type": "image",
      "content": "https://example.com/order-confirmation.png",
      "caption": "Order Confirmation"
    }
  ]
}

Message Types

Text Message:

{
  "type": "text",
  "content": "Your message here"
}

Image Message:

{
  "type": "image",
  "content": "https://example.com/image.jpg",
  "caption": "Optional caption"
}

Audio Message:

{
  "type": "audio",
  "content": "https://example.com/audio.mp3"
}

Document Message:

{
  "type": "document",
  "content": "https://example.com/document.pdf",
  "fileName": "invoice.pdf"
}

Trigger Types

All Messages

Respond to every message (only one “all” trigger allowed per instance):

{
  "triggerType": "all"
}

Keyword Trigger

Trigger based on specific keywords:

{
  "triggerType": "keyword",
  "triggerOperator": "startsWith",
  "triggerValue": "order"
}

Available operators:

equals - Exact match
contains - Contains the keyword
startsWith - Message starts with keyword
endsWith - Message ends with keyword
regex - Regular expression match

Advanced Trigger

Use regex for complex pattern matching:

{
  "triggerType": "advanced",
  "triggerValue": "^order\\s+(\\d+)$"
}

Update N8N Bot

Modify an existing N8N bot configuration:

curl -X PUT https://your-api.com/n8n/update/{instance}/{botId} \
  -H "apikey: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "description": "Updated Workflow",
    "webhookUrl": "https://n8n.yourdomain.com/webhook/new-workflow"
  }'

Delete N8N Bot

Remove an N8N bot from your instance:

curl -X DELETE https://your-api.com/n8n/delete/{instance}/{botId} \
  -H "apikey: your-api-key"

Fetch N8N Bots

Retrieve all N8N bots configured for your instance:

curl -X GET https://your-api.com/n8n/fetch/{instance} \
  -H "apikey: your-api-key"

Session Management

Change Session Status

Update the status of an active N8N session:

curl -X POST https://your-api.com/n8n/changeStatus/{instance} \
  -H "apikey: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "remoteJid": "[email protected]",
    "status": "closed"
  }'

Fetch Sessions

Get all active N8N sessions:

curl -X GET https://your-api.com/n8n/fetchSessions/{instance} \
  -H "apikey: your-api-key"

N8N Workflow Examples

Order Processing

Webhook trigger receives order message
Parse order details with code node
Create order in database (PostgreSQL/MySQL node)
Send confirmation email (Email node)
Update inventory (HTTP Request node)
Return confirmation message to WhatsApp

CRM Integration

Webhook receives customer message
Search for contact in CRM (Salesforce/HubSpot node)
Create or update contact record
Log interaction in CRM
Check for open tickets
Return personalized response

Support Ticket Creation

Webhook receives support request
Extract issue details with AI (OpenAI node)
Create ticket in system (Jira/Zendesk node)
Assign to team member
Send ticket number to customer
Set up follow-up reminder (Schedule Trigger)

Use Cases

E-commerce Automation

Automate sales processes:

Order placement and confirmation
Inventory checks and updates
Payment processing
Shipping notifications
Order status tracking

CRM Integration

Connect WhatsApp to your CRM:

Auto-create/update contacts
Log all interactions
Trigger sales workflows
Update deal stages
Sync customer data

Support Ticketing

Streamline customer support:

Auto-create support tickets
Route to appropriate teams
Update ticket status
Send notifications
Gather customer feedback

Multi-System Orchestration

Connect multiple platforms:

Database operations
API integrations
File processing
Data transformation
Cross-system synchronization

Best Practices

Always activate your N8N workflows before testing with Evolution API. Use production webhook URLs, not test URLs.

Protect your N8N webhooks with Basic Authentication to prevent unauthorized access.

Use error handling: Add error catch nodes in N8N workflows
Validate inputs: Check and sanitize data from WhatsApp messages
Implement timeouts: Set reasonable timeout values for external API calls
Log executions: Enable execution logging in N8N for debugging
Test workflows: Thoroughly test in N8N before connecting to WhatsApp
Secure webhooks: Always use HTTPS and authentication
Handle async operations: Use webhooks or callbacks for long-running tasks

Troubleshooting

Workflow not triggered

Verify N8N_ENABLED=true in environment
Check that bot is enabled (enabled: true)
Ensure trigger conditions match incoming messages
Verify N8N workflow is activated (not in draft)
Check webhook URL is correct and accessible
Test webhook manually with curl or Postman

Authentication errors

Verify Basic Auth credentials are correct
Check that credentials match N8N webhook settings
Ensure webhook has authentication enabled if using credentials
Test authentication with curl

No response from workflow

Check N8N execution logs for errors
Verify workflow returns proper response format
Ensure all nodes execute successfully
Check for timeout issues in long-running workflows
Verify network connectivity between Evolution API and N8N

Session not maintained

Increase expire time if sessions timeout too quickly
Set keepOpen: true for longer conversations
Use sessionId in N8N workflow for context tracking
Store session data in N8N database for persistence

Advanced Configuration

Multiple Workflows

Deploy different workflows for different purposes:

// Sales workflow
{
  webhookUrl: 'https://n8n.example.com/webhook/sales',
  triggerType: 'keyword',
  triggerValue: 'buy'
}

// Support workflow
{
  webhookUrl: 'https://n8n.example.com/webhook/support',
  triggerType: 'keyword',
  triggerValue: 'help'
}

// General automation (fallback)
{
  webhookUrl: 'https://n8n.example.com/webhook/general',
  triggerType: 'all'
}

Self-Hosted N8N

For self-hosted N8N installations:

{
  "webhookUrl": "https://n8n.yourcompany.com/webhook/whatsapp",
  "basicAuthUser": "your-user",
  "basicAuthPass": "your-password"
}

Ensure your N8N instance is accessible from Evolution API server.

Flowise - LLM workflow automation
Dify - AI application platform
Typebot - Chatbot builder
Chatwoot - Customer support platform

Get Started

Core Concepts

WhatsApp Integration

Chatbot Integrations

Event Systems

Storage & Media

Deployment

​N8N Integration

​What is N8N?

​Enable N8N Integration

​Configuration Settings

​Create Default Settings

​Settings Parameters

​Create an N8N Bot

​Request Parameters

​Webhook Payload

​Payload Fields

​N8N Response Format

​Message Types

​Trigger Types

​All Messages

​Keyword Trigger

​Advanced Trigger

​Update N8N Bot

​Delete N8N Bot

​Fetch N8N Bots

​Session Management

​Change Session Status

​Fetch Sessions

​N8N Workflow Examples

​Order Processing

​CRM Integration

​Support Ticket Creation

​Use Cases

​Best Practices

​Troubleshooting

​Advanced Configuration

​Multiple Workflows

​Self-Hosted N8N

​Related Integrations

Build docs developers (and LLMs) love

N8N Integration

What is N8N?

Enable N8N Integration

Configuration Settings

Create Default Settings

Settings Parameters

Create an N8N Bot

Request Parameters

Webhook Payload

Payload Fields

N8N Response Format

Message Types

Trigger Types

All Messages

Keyword Trigger

Advanced Trigger

Update N8N Bot

Delete N8N Bot

Fetch N8N Bots

Session Management

Change Session Status

Fetch Sessions

N8N Workflow Examples

Order Processing

CRM Integration

Support Ticket Creation

Use Cases

Best Practices

Troubleshooting

Advanced Configuration

Multiple Workflows

Self-Hosted N8N

Related Integrations