better-chat

A sophisticated chat UI node for n8n workflows with rich text rendering, file handling, and advanced conversation features

Package Information

Released: 8/30/2025

Downloads: 3,757 weekly / 3,757 monthly

Latest Version: 0.3.26

Author: Jeremy Dawes

Available Nodes

Chat UI Trigger

No description available

Better Chat Trigger

No description available

Documentation

n8n Better Chat UI Node

A feature-rich chat trigger node for n8n workflows with multiple access modes including hosted chat interface, webhook endpoint, and embedded widget support. Provides native AI Agent integration, authentication, CORS configuration, and advanced UI features.

🎉 Version 0.3.17 - Test Chat Interface Support

BetterChatTrigger Node - Now with built-in test chat interface in n8n editor! Test your workflows directly from the canvas with the integrated chat panel, plus complete UI customization including file uploads, color customization, syntax highlighting, and more.

Migration Guide

Existing users: Your workflows will continue to work
Response Mode: Uses "When Last Node Finishes" for reliable operation
All features preserved: Every enhancement is available

Features

🧪 Test Chat Interface (New in v0.3.17!)

Built-in Test Panel - Test your chat workflows directly in the n8n editor
Chat Button - Access the test interface from the workflow canvas
Integrated Logs - View AI agent logs alongside chat conversations
Manual Mode - Keep chat private during development with the public toggle

🚀 Chat Access Modes

Webhook Mode - Basic webhook endpoint for custom integrations
Hosted Chat - Complete chat interface provided by n8n with generated URL
Embedded Chat - Compatible with @n8n/chat widget for embedding

🔐 Security & Access Control

Authentication - Support for Basic Auth to restrict access
CORS Configuration - Control allowed origins for cross-origin requests
Public/Private Toggle - Switch between test and production modes
Session Management - Track conversations with session and thread IDs

🎨 Rich User Interface

Markdown Rendering - Full Markdown support for formatted messages
Code Highlighting - Syntax highlighting with Prism.js for multiple languages
Theme Support - Light, dark, and auto themes
Custom Colors - Full color customization for all UI elements
Adjustable Size - Control width and font size
Responsive Design - Adapts to different screen sizes
Custom Welcome Message - Configure initial greeting

💬 Advanced Chat Features

Conversation Threading - Organize chats into threads
Folder Organization - Categorize conversations visually
Message Actions - Copy, regenerate, pin important messages
File Uploads - Handle documents, images, and other files
Voice Input - Support for voice messages (when enabled)
Search - Find messages within conversations
Export - Download conversations in JSON, Markdown, or HTML

🤖 AI Agent Integration

Native AI Agent Support - Direct chatInput field for seamless integration
Output Format Options - Choose between AI-optimized or detailed output
Works with Any AI Agent - Compatible with all n8n AI nodes
System Prompt Override - Customize AI behavior on the fly
Context Management - Intelligent message history handling
Tool Compatible - Can be used as a tool by AI Agents
Session & Thread Tracking - Automatic conversation management

🏗️ Architecture

Separation of Concerns - UI only, no state management
n8n Native - Follows established n8n patterns
No External Dependencies - Self-contained node
Performance Optimized - Efficient rendering and data handling

Installation

Via n8n UI (Recommended)

Navigate to Settings → Community Nodes
Search for n8n-nodes-better-chat
Click Install
Restart n8n if prompted

Via Command Line

cd /path/to/n8n
npm install n8n-nodes-better-chat@latest
n8n start

Update to Latest Version

npm update n8n-nodes-better-chat
# or specific version
npm install n8n-nodes-better-chat@0.2.0

From Source (Development)

git clone https://github.com/jezweb/n8n-nodes-better-chat.git
cd n8n-nodes-better-chat
npm install
npm run build
npm link
cd ~/.n8n/custom
npm link n8n-nodes-better-chat
n8n start

Usage

Basic Setup

Add the Node: Drag the "Better Chat Trigger" node from the trigger nodes panel
Test Your Workflow:
- Keep "Make Chat Publicly Available" toggle OFF during development
- Click the "Chat" button at the bottom of the canvas to open test interface
- Type messages and see responses directly in the editor
Choose Chat Access Mode:
- Webhook Only: Basic webhook endpoint
- Hosted Chat: n8n provides chat interface with URL (See Setup Guide)
- Embedded Chat: For @n8n/chat widget integration
Configure Webhook Path: Set the path for receiving chat messages (default: webhook)
Choose Output Format:
- AI Agent Compatible: Optimized for AI Agent nodes (default)
- Detailed: Full output with all metadata
Configure Security (for Hosted/Embedded modes):
- Set authentication (None/Basic Auth)
- Configure allowed origins for CORS
- Toggle public availability
Connect to AI Agent: Link the output to an AI Agent node
Get Access URL:
- For Webhook: Click "Webhook URLs"
- For Hosted: Check the chatUrl in output or node UI

Example Workflows

Hosted Chat Interface (v0.2.0+)

[Better Chat Trigger] → [AI Agent]

The node uses "When Last Node Finishes" response mode for optimal performance.

Simple Webhook Integration

[Better Chat Trigger] → [AI Agent]
     ↓                   ↑
  chatInput         {{ $json.chatInput }}

Chat with Memory

[Better Chat Trigger] → [AI Agent] ← [Window Buffer Memory]

Embedded Widget (@n8n/chat)

[@n8n/chat Widget] → [Better Chat Trigger] → [AI Agent]
   (CORS enabled)

## Configuration Options

### Chat Access Mode (v0.2.0+)
- **Webhook Only**: Basic webhook endpoint for custom integrations
- **Hosted Chat**: n8n provides a complete chat interface with generated URL
- **Embedded Chat**: Compatible with @n8n/chat widget for embedding

### Output Format
- **AI Agent Compatible** (default): Simplified output with `chatInput` field for AI Agent nodes
  ```json
  {
    "chatInput": "user message",
    "sessionId": "session_123",
    "threadId": "thread_456",
    "messages": [...],
    "messageCount": 2,
    "timestamp": "2025-08-28T12:00:00Z",
    "chatUrl": "https://n8n.example.com/chat/workflow-id"
  }

Detailed: Full output with all metadata, context, and raw webhook data

Security Options

Authentication: None or Basic Auth (username/password)
Allowed Origins: Comma-separated list for CORS (default: *)
Public Available: Toggle between test and production modes

Display Modes

Simple: Clean, minimal interface for basic conversations
Rich (default): Enhanced with Markdown and code highlighting

Features (Multi-select)

Markdown Rendering - Format text with Markdown
Code Highlighting - Syntax highlighting for code blocks
Copy Button - Easy message copying
Regenerate - Allow AI response regeneration
File Upload - Enable file attachments
Voice Input - Voice message support
Export Chat - Download conversations
Pin Messages - Mark important messages
Search - Search within conversation
Timestamps - Show message timestamps

UI Settings

Theme: Light, Dark, or Auto
Width: Customizable container width (px, %, or auto)
Font Size: Small, Medium, Large, or Extra Large
Max Height: Container height in pixels
Custom Colors:
- Primary Color
- Background Color
- Container Background
- User Message Color
- Assistant Message Color
- Text Color
Compact Mode: Reduced message spacing

File Settings

Allowed Types: Comma-separated extensions (e.g., .pdf,.txt,.png)
Max File Size: Maximum size in MB
Storage Mode: Base64 (small files) or URL reference

Node Properties

Property	Type	Description	Default
chatMode	options	Access mode (webhook/hosted/embedded)	webhook
webhookPath	string	Path for webhook endpoint	webhook
publicAvailable	boolean	Public access for hosted chat	false
authentication	options	Auth type (none/basic)	none
authUsername	string	Username for Basic Auth	-
authPassword	string	Password for Basic Auth	-
allowedOrigins	string	CORS allowed origins	*
initialMessage	string	Welcome message for hosted chat	Hi! How can I help you today?
outputFormat	options	Output structure (aiAgent/detailed)	aiAgent
displayMode	options	Interface complexity level	rich
features	multiOptions	Enabled features	markdown, timestamps
uiSettings	collection	Interface customization	-

Output Format

The node outputs a structured object that AI Agents can process:

{
  messages: [
    {
      role: 'user' | 'assistant' | 'system',
      content: string,
      timestamp: string,
      metadata: {
        thread_id: string,
        folder: string,
        pinned: boolean,
        files: Array
      }
    }
  ],
  action: 'send' | 'regenerate' | 'export',
  displayMode: string,
  features: Array,
  uiState: Object,
  context: {
    thread_id: string,
    session_id: string,
    folder: string
  }
}

Webhook Integration

Sending Messages to the Webhook

The node expects a POST request with the following structure:

// Basic message
{
  "message": "Hello, how can you help me?",
  "thread_id": "optional-thread-id",
  "session_id": "optional-session-id"
}

// With previous messages
{
  "message": "What about this?",
  "messages": [
    { "role": "user", "content": "Previous question" },
    { "role": "assistant", "content": "Previous answer" }
  ]
}

// With files
{
  "message": "Check this document",
  "files": [
    { "name": "document.pdf", "type": "application/pdf", "data": "base64..." }
  ]
}

Webhook URLs

n8n provides two webhook URLs:

Test URL: Use while building workflows (includes test listener)
Production URL: Use when workflow is active

Example curl Request

curl -X POST https://your-n8n.com/webhook/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello from curl!"}'

Best Practices

Memory Management

The node doesn't store conversations - use Memory nodes for persistence
Configure maxMessages in thread options to limit context size
Use pinned messages for important context that should always be included

Performance

Enable only the features you need
Set reasonable file size limits
Use URL storage mode for large files

Integration

Always connect to an AI Agent node for logic
Use Memory nodes for conversation persistence
Add Tool nodes for extended functionality

Troubleshooting

Node Not Appearing

Ensure community nodes are enabled: N8N_COMMUNITY_PACKAGES_ENABLED=true
Check n8n logs for installation errors
Verify the package is installed: npm list n8n-nodes-better-chat

Build Errors (Development)

rm -rf node_modules dist
npm install
npm run build

File Upload Issues

Check allowed file types in settings
Verify file size limits
Ensure proper storage mode for your use case

Examples

Customer Service Bot

// Connect: Webhook → Better Chat UI → AI Agent → CRM Tool
{
  displayMode: 'rich',
  features: ['markdown', 'files', 'export'],
  systemPrompt: 'You are a helpful customer service agent...'
}

Technical Assistant

// Connect: Better Chat UI → AI Agent → Code Execution Tool
{
  displayMode: 'advanced',
  features: ['codeHighlight', 'copy', 'search'],
  systemPrompt: 'You are a technical assistant specializing in...'
}

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: See ARCHITECTURE.md for technical details

License

MIT - See LICENSE.md for details

Author

Jeremy Dawes - Jezweb

Acknowledgments

n8n team for the excellent workflow automation platform
The n8n community for inspiration and feedback

Made with ❤️ for the n8n community