n8n Integration Guide

Connect your ChatWidgetPro widget to n8n workflows

What You'll Learn

This guide covers everything you need to know about integrating ChatWidgetPro with n8n, including webhook setup, data handling, and best practices.

Overview

n8n is a powerful workflow automation tool that can process chat messages, integrate with AI services, query databases, and much more. ChatWidgetPro makes it easy to create a beautiful chat interface for your n8n workflows.

The integration works by sending user messages from the chat widget to your n8n webhook, processing them in your workflow, and returning a response.

Setting Up Your n8n Workflow

1. Create a Webhook Trigger

Start by adding a Webhook node to your workflow:

Drag the "Webhook" node onto your canvas
Set the HTTP Method to "POST"
Choose a path (e.g., "/chat" or "/chatbot")
Set "Respond" to "Immediately"

Make sure to set "Respond" to "Immediately" or use a "Respond to Webhook" node later in your workflow.

2. Understanding the Request Payload

ChatWidgetPro sends a POST request with the following structure:

Request Payload Structurejson

{
  "message": "User's message text",
  "sessionId": "unique-session-identifier",
  "widgetId": "your-widget-id",
  "timestamp": "2024-12-07T10:30:00.000Z",
  "metadata": {
    "userAgent": "Mozilla/5.0...",
    "url": "https://example.com/page",
    "referrer": "https://google.com"
  }
}

Access these values in n8n using expressions:

{{$json.message}} - The user's message
{{$json.sessionId}} - Unique session ID
{{$json.widgetId}} - Widget identifier
{{$json.timestamp}} - Message timestamp
{{$json.metadata}} - Additional context data

3. Process the Message

Add nodes to process the incoming message. Common patterns include:

AI Integration

Use OpenAI, Anthropic, or other AI nodes to generate intelligent responses.

Database Queries

Query your database to fetch information based on the user's question.

API Calls

Make HTTP requests to external APIs to fetch data or perform actions.

Business Logic

Use IF nodes, Switch nodes, and Code nodes to implement custom logic.

4. Return a Response

Your workflow must return a response in the correct format. Use a "Respond to Webhook" node or configure the webhook to respond immediately:

Required Response Formatjson

{
  "response": "Your response message here"
}

Response Tips

Keep responses concise and user-friendly
Use Markdown for formatting (if enabled in widget)
Include links with [text](url) syntax
Break long responses into paragraphs

Example Workflows

Simple Echo Bot

A basic workflow that echoes the user's message:

Webhook trigger (POST)

Set node to create response:

{
  "response": "You said: {{$json.message}}"
}

Respond to Webhook node

OpenAI Chatbot

A workflow that uses OpenAI to generate responses:

Webhook trigger (POST)
OpenAI node with the user's message as input

Set node to format the response:

{
  "response": "{{$json.choices[0].message.content}}"
}

Respond to Webhook node

Database Query Bot

A workflow that queries a database based on user input:

Webhook trigger (POST)
Code node to extract keywords from the message
Database query node (MySQL, PostgreSQL, etc.)
IF node to check if results were found
Set nodes for different response types
Respond to Webhook node

Advanced Features

Session Management

Use the sessionId to maintain conversation context:

Store conversation history in a database using sessionId as the key
Retrieve previous messages for context-aware responses
Track user preferences and state across messages

Session Storage Patterntext

1. Check if sessionId exists in database
2. If exists: Load conversation history
3. If new: Create new session record
4. Process message with context
5. Save new message to history
6. Return response

Metadata Usage

The metadata object contains useful information about the user:

userAgent: Browser and device information
url: Page where the chat was initiated
referrer: Where the user came from

Use this data to:

Provide page-specific responses
Track analytics and conversion sources
Personalize the experience based on device type

Error Handling

Implement proper error handling in your workflow:

Error Response Formatjson

{
  "response": "I'm sorry, I encountered an error processing your request. Please try again."
}

Always return a user-friendly error message. Don't expose internal error details to users.

Streaming Responses

For AI responses, you may want to enable streaming in the widget. To support streaming:

Enable streaming in the Features tab of your widget
Your n8n workflow should return the complete response
ChatWidgetPro will simulate streaming on the client side

True server-side streaming requires a custom implementation outside of n8n's standard webhook flow.

Testing Your Integration

Test in n8n

Click "Listen for Test Event" on your webhook node
Send a test message from ChatWidgetPro editor
Verify the webhook receives the correct data
Step through your workflow to check each node
Confirm the response format is correct

Test in ChatWidgetPro

Go to the Integration tab in the editor
Enter your n8n webhook URL
Click "Test Connection"
Verify you receive a response
Use the live preview to test real conversations

Best Practices

Keep workflows simple: Break complex logic into multiple workflows
Add error handling: Always include error branches in your workflow
Log conversations: Store messages for analytics and debugging
Set timeouts: Configure appropriate timeouts for API calls
Validate input: Check and sanitize user input before processing
Monitor performance: Track webhook response times
Use environment variables: Store API keys and secrets securely

Troubleshooting

No Response Received

Check that your webhook URL is correct and publicly accessible
Verify the workflow is active (not in draft mode)
Ensure "Respond" is set correctly on the webhook node
Check n8n execution logs for errors

Incorrect Response Format

Verify the response includes a "response" field
Check that the response is valid JSON
Use a Set node to ensure proper formatting

Timeout Errors

Reduce workflow complexity
Optimize database queries
Use async processing for long-running tasks
Return an immediate response and process in the background

Ready for More?

Explore advanced widget features and configuration options.

Chat Streaming Voice Input