n8n-nodes-agent-chat-interface

v0.0.56

Published

4 months ago

N8N custom node that serves a React chat interface as static content

0High
0Medium
0Low

lelemm

n8n n8n-nodes-base chat interface react

N8N Chat Interface Node

A powerful N8N custom node that serves a fully customizable React chat interface as static content. This node encapsulates a complete AI chat application and allows you to deploy it with custom theming, feedback collection, and webhook integration without requiring additional servers or port management.

🌟 Features

🎨 Complete Theme Customization: Configure all colors for both light and dark modes with HSL values
📏 Interactive Resize Functionality: Drag-to-resize grip with ghost preview for both standalone and floating chat modes
🔧 Dynamic Configuration: Set chat API URL, title, and all UI settings through node parameters
📦 Self-Contained: No external servers, databases, or port binding required
🚀 Production Ready: Builds and serves optimized React app as static content
🔍 SPA Routing: Handles single-page application routing correctly
👍 Feedback System: Built-in thumbs up/down feedback collection with configurable endpoints
🔗 Webhook Integration: Convert static asset paths to webhook calls for dynamic serving
📱 Responsive Design: Mobile-first design that works on all screen sizes
🌐 Markdown Support: Rich text rendering in chat messages with reference support
👋 Welcome Messages: Configurable welcome messages with full ChatResponse JSON support
🔘 Interactive Options: Dynamic option buttons for guided conversation flows
🔒 Input Control: Programmatically disable/enable text input based on conversation state
🎯 Smart Conversation Flow: Guide users through structured interactions with option buttons
📝 Advanced Agent Message Footnotes:
- Configurable disclaimer messages under every AI response with full markdown support
- Customizable footnote titles and collapsible toggle functionality (similar to References)
- Flexible timing options: show immediately, after response completion, or let the agent decide per message
- Agent-controlled display: API responses can include showFootnote: true to control footnote visibility dynamically
- Automatic base64 encoding/decoding for complex content with special characters
- Support for multiline content, code blocks, links, and rich formatting
🔄 Redux State Management: Built-in Redux store for message persistence and state management
🛡️ Robust Error Handling: Graceful handling of API errors and undefined responses
🔌 Flexible API Integration: Supports both output and message response fields
🛠️ Cache-Busting Technology: Automatic cache prevention for iframe environments with dynamic configuration updates

📦 Installation

🌟 NPM Installation (Recommended)

Install as a community node using N8N's built-in community node manager:

Via N8N UI (Easiest):
- Go to Settings → Community Nodes
- Click Install a community node
- Enter: n8n-nodes-agent-chat-interface
- Click Install

Via NPM Command:

npm install n8n-nodes-agent-chat-interface

Restart N8N: The node will be automatically available after restart

🛠️ Development Installation

For development or custom modifications:

Clone Repository: Get the source code from the repository

Install Dependencies (from project root):

# Install all workspace dependencies
yarn install
   
# Build chat interface library first (required dependency)
yarn workspace chat-interface-lib build
   
# Build the n8n node (includes React app bundling)
yarn workspace n8n-nodes-agent-chat-interface build

Link Locally:

# From the n8n-nodes-agent-chat-interface directory
npm link
   
# In your N8N installation directory
npm link n8n-nodes-agent-chat-interface

Restart N8N: Restart your N8N instance to load the new node

✅ Verify Installation

After installation, look for "Chat Interface" in the N8N node palette under the "Output" category.

📋 Requirements

N8N Version: Compatible with N8N 0.200.0+
Node.js: Version 16.9+ required
NPM: Latest version recommended

Note: This package includes pre-built React assets and requires no additional dependencies beyond what's included in the npm package.

🚀 Quick Start Guide

Basic Chat Interface Setup

Add the Node: Drag "Chat Interface" node to your workflow
Configure Mandatory Parameters:
- Request Path: / (serves the main chat interface)
- Chat API URL: https://your-api.com/chat (your backend endpoint)
- Chat Title: My AI Assistant (displayed in header)

Test the Setup: Input:

{ "requestPath": "/" }

Output:

{ 
  "statusCode": 200, 
  "content": "PGh0bWw+Li4uPC9odG1sPg==", 
  "contentType": "text/html" 
}

Advanced Setup with Welcome Message and Feedback

{
  "requestPath": "/",
  "chatApiUrl": "https://api.example.com/chat",
  "chatTitle": "Customer Support Bot",
  "webhookUrl": "https://your-n8n-instance.com/webhook/your-webhook-id",
  "agentSid": "[email protected]",
  "welcomeMessage": "{\"output\":\"Welcome to Customer Support! How can I help you today?\",\"options\":[\"Report a bug\",\"Request a feature\",\"Ask a question\",\"Speak to a human\"],\"disableInput\":true}",
  "agentMessageFootnote": "This response was generated by AI. Please verify important information.",
  "feedbackEnabled": true,
  "thumbsUpUrl": "https://api.example.com/feedback/positive",
  "thumbsDownUrl": "https://api.example.com/feedback/negative",
  "lightThemeColors": {
    "primary": "220 98% 61%",
    "secondary": "220 20% 95%"
  },
  "darkThemeColors": {
    "primary": "220 98% 61%",
    "secondary": "220 20% 15%"
  }
}

Note: The webhookUrl should be the webhook URL of the same N8N flow where you placed this Chat Interface node. This allows the chat interface to serve all its assets (CSS, JS, images) through N8N webhooks instead of requiring a separate web server.

⚙️ Node Parameters

🔴 Mandatory Parameters

These parameters are required for the chat interface to function:

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | Request Path | string | ✅ | / | The path to serve (/, /assets/style.css, etc.) | | Chat API URL | string | ✅ | - | MUST be configured - Your chat backend API endpoint | | Chat Title | string | ✅ | AI Assistant Chat | Title displayed in the chat interface header |

🔧 Core Configuration

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | Webhook URL | string | "" | The webhook URL of the N8N flow containing this node. Enables serving assets via N8N webhooks by converting all paths to ?path= queries | | Agent SID | string | "" | Optional user identifier (email, username, or ID) to include in chat API requests for user tracking and personalization | | Welcome Message | string | "" | Optional welcome message as ChatResponse JSON. Automatically displayed when user opens chat. Supports all ChatResponse features: output, options, references, disableInput, showFootnote. | | Enable Agent Message Footnote | boolean | false | Enable footnote display under agent messages | | Agent Message Footnote | string | "" | Footnote message to display under every agent message (supports markdown formatting) | | Footnote Title | string | "Disclaimer" | Title to display above the footnote content | | Footnote Collapsible | boolean | true | Allow users to expand/collapse the footnote content (similar to References) | | Show Footnote | options | "After Response Received" | When to display the footnote:• Immediately: Show as soon as message appears• After Response Received: Show only after AI response is complete• Let Agent Decide: Show only when API response includes showFootnote: true |

👍 Feedback Configuration

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | Enable Feedback | boolean | false | Enable thumbs up/down feedback buttons on AI responses | | Thumbs Up URL | string | "" | POST endpoint for positive feedback (required if feedback enabled) | | Thumbs Down URL | string | "" | POST endpoint for negative feedback (required if feedback enabled) |

🎨 Theme Configuration

Light Theme Colors

All colors use HSL format without the hsl() wrapper (e.g., 220 98% 61%):

| Parameter | Default | Description | |-----------|---------|-------------| | Background | 0 0% 100% | Main page background | | Foreground | 0 0% 3.9% | Primary text color | | Card | 0 0% 100% | Chat components background | | Card Foreground | 0 0% 3.9% | Text on cards | | Primary | 220 98% 61% | Button colors, send button, links | | Primary Foreground | 0 0% 98% | Text on primary colored elements | | Secondary | 0 0% 96.1% | Secondary UI elements | | Secondary Foreground | 0 0% 9% | Text on secondary elements | | Muted | 0 0% 96.1% | Subtle backgrounds | | Muted Foreground | 0 0% 45.1% | Muted text, timestamps | | Border | 0 0% 89.8% | Component borders | | Input | 0 0% 89.8% | Input field backgrounds |

Dark Theme Colors

Same structure as light theme with dark-optimized defaults:

| Parameter | Default | Description | |-----------|---------|-------------| | Background | 0 0% 3.9% | Dark background | | Foreground | 0 0% 98% | Light text | | Primary | 220 98% 61% | Accent color (often same as light) | | Secondary | 0 0% 14.9% | Dark secondary elements | | Border | 0 0% 14.9% | Dark borders |

📏 Interactive Resize Functionality

The chat interface includes built-in resize functionality that allows users to adjust the chat window size for optimal viewing.

Resize Modes

Standalone Chat (Centered Resize):

Resize grip appears on the right edge of the chat interface
Dragging expands the chat equally on both sides (centered expansion)
Ideal for full-screen or embedded applications
Maintains chat position while adjusting width

Floating Chat (Edge Resize):

Resize grip appears on the left edge of the floating chat window
Dragging resizes from the edge (right side remains fixed)
Perfect for floating chat windows positioned on screen edges
Maintains floating position while adjusting width

Visual Features

Interactive Grip Handle: Subtle grip icon that becomes visible on hover
Ghost Preview: Dashed border preview shows new size while dragging
Smooth Transitions: Animated resize with visual feedback
Responsive Constraints: Minimum (600px) and maximum (95% viewport) width limits
Cursor Feedback: Resize cursor appears during drag operations

Usage

The resize functionality is automatically enabled in:

Standalone chat applications (like the web app version)
Floating chat implementations (with appropriate resize mode)
All chat interfaces served through the N8N node

Users can simply hover over the resize grip and drag to adjust the chat width to their preference. The interface remembers the size during the session and provides visual feedback throughout the resize operation.

📡 API Integration

Chat Message Payload

When users send messages, the chat interface makes a POST request to your Chat API URL with this payload:

{
  "message": "User's message text",
  "guid": "session-uuid-12345",
  "agent_sid": "optional-user-identifier"
}

Payload Fields:

message (string): The user's input text
guid (string): Unique session identifier (generated per chat session)
agent_sid (string, optional): User identifier from the Agent SID parameter, SharePoint context, or other sources

Expected Chat API Response

Your backend should respond with this JSON structure:

{
  "output": "AI response text with **markdown** support",
  "message": "Alternative field name (also supported)",
  "options": [
    "Continue with Option A",
    "Tell me more about this topic",
    "I need help with something else"
  ],
  "disableInput": true,
  "references": [
    {
      "name": "Document Title",
      "content": "Optional document content for sidebar",
      "url": "https://example.com/doc" 
    }
  ],
  "showFootnote": true
}

Response Fields:

output (string, required): The AI's response text (supports markdown)
message (string, alternative): Alternative field name for the AI's response (also supported)
options (array, optional): Array of clickable option buttons for guided conversation flow
disableInput (boolean, optional): When true, disables the text input field forcing users to use option buttons
references (array, optional): List of reference documents/links
- name (string): Display name for the reference
- content (string, optional): Full document content (opens in sidebar)
- url (string, optional): External URL (opens in new tab)
showFootnote (boolean, optional): When footnote timing is set to "Let Agent Decide", controls whether to show the footnote for this specific message

Note: The chat interface supports both output and message fields in the API response. Use whichever field name your backend API returns.

🔘 Interactive Options & Input Control

The chat interface supports interactive option buttons and dynamic input control:

Option Buttons

When your API response includes an options array, clickable buttons are displayed below the message:

Users click buttons instead of typing responses
Button text is sent as the user's message when clicked
Great for guided conversations, menu selection, and structured workflows

Dynamic Input Control

Use the disableInput field to control when users can type freely:

disableInput: true - Forces users to use option buttons only
disableInput: false or omitted - Allows normal text input
Provides complete control over conversation flow

Example Use Cases:

Customer Support Triage: Present categorized options first
Onboarding Flows: Guide new users through setup steps
Survey/Feedback: Collect structured responses
Menu Systems: Create hierarchical navigation
Form Filling: Guide users through data collection

Example API Response with Options:

{
  "output": "I can help you with several things. What would you like to do?",
  "options": [
    "Check my account status",
    "Report a technical issue", 
    "Request a new feature",
    "Speak with a human agent"
  ],
  "disableInput": true
}

When a user clicks "Check my account status", that text is sent as their next message to your API.

👋 Welcome Messages

Configure automatic welcome messages that appear when users first open the chat. Welcome messages support the full ChatResponse format, including options and input control.

Welcome Message Examples:

Simple Welcome:

{
  "welcomeMessage": "{\"output\":\"Hello! I'm your AI assistant. How can I help you today?\"}"
}

Welcome with Options:

{
  "welcomeMessage": "{\"output\":\"Welcome to Customer Support! Please select your inquiry type:\",\"options\":[\"Technical Issue\",\"Billing Question\",\"Feature Request\",\"General Help\"],\"disableInput\":true}"
}

Welcome with References:

{
  "welcomeMessage": "{\"output\":\"Welcome! I can help you with questions about our products and services.\",\"references\":[{\"name\":\"User Guide\",\"url\":\"https://docs.example.com\"}],\"options\":[\"Get started\",\"Browse help topics\"]}"
}

📝 Agent Message Footnotes

The chat interface supports displaying custom footnote messages under every AI response. This is useful for:

Legal disclaimers: "This response was generated by AI. Please verify important information."
Usage guidelines: "This assistant is for informational purposes only."
Company policies: "This response follows our company's AI usage guidelines."
Custom branding: "Powered by [Your Company] AI Assistant"

Footnote Features:

Markdown Support: Use bold, italic, code, and links in your footnote text
Discreet Styling: Small, muted text that doesn't interfere with the main conversation
Conditional Display: Only appears when a footnote message is configured
Theme Integration: Automatically adapts to light/dark mode

Example Footnotes:

{
  "agentMessageFootnote": "This response was generated by AI. Please verify important information."
}

{
  "agentMessageFootnote": "**Disclaimer**: This assistant is for informational purposes only.\n\nFor official guidance, please contact support.\n\n```\nCode examples work fine too!\n```"
}

{
  "agentMessageFootnote": "⚠️ **Important Notice**:\n\n- This response was generated by AI\n- Please verify important information\n- For support, contact [[email protected]](mailto:[email protected])\n\n---\nPowered by **Company Name** AI • [Privacy Policy](https://company.com/privacy)"
}

Feedback Payload

When feedback is enabled and users click thumbs up/down, a POST request is sent to the configured feedback URLs:

{
  "messageId": "unique-message-id",
  "messageContent": "The AI response that was rated",
  "feedback": "positive",
  "timestamp": "2024-01-01T12:00:00.000Z"
}

Feedback Fields:

messageId (string): Unique identifier for the message
messageContent (string): The full AI response text
feedback (string): Either "positive" or "negative"
timestamp (string): ISO timestamp of when feedback was given

🛣️ URL Routing & Asset Serving

Supported Request Paths

| Path Pattern | Behavior | Content Type | |--------------|----------|--------------| | / | Serves main chat interface | text/html | | /assets/*.js | Serves JavaScript bundles | application/javascript | | /assets/*.css | Serves stylesheets | text/css | | /assets/*.png, .jpg, etc. | Serves images | image/* | | /any-route (no extension) | Serves index.html (SPA routing) | text/html | | Invalid paths | Returns 404 | text/plain |

Response Format

All responses follow this structure:

{
  "statusCode": 200,
  "content": "base64-encoded-content",
  "contentType": "text/html"
}

🎨 Theme Examples

Corporate Blue Theme

{
  "lightThemeColors": {
    "primary": "220 98% 61%",
    "secondary": "220 20% 95%",
    "background": "220 20% 98%"
  },
  "darkThemeColors": {
    "primary": "220 98% 61%",
    "secondary": "220 20% 15%",
    "background": "220 20% 8%"
  }
}

Success Green Theme

{
  "lightThemeColors": {
    "primary": "142 76% 36%",
    "secondary": "142 20% 95%"
  },
  "darkThemeColors": {
    "primary": "142 76% 46%",
    "secondary": "142 20% 15%"
  }
}

Creative Purple Theme

{
  "lightThemeColors": {
    "primary": "262 83% 58%",
    "secondary": "262 20% 95%"
  },
  "darkThemeColors": {
    "primary": "262 83% 68%",
    "secondary": "262 20% 15%"
  }
}

🔧 Development & Building

Development Workflow

# Start development mode (watches for changes)
yarn workspace n8n-nodes-agent-chat-interface dev

# Clean build artifacts
yarn workspace n8n-nodes-agent-chat-interface clean

# Full production build
yarn workspace n8n-nodes-agent-chat-interface build

Publishing to NPM

To publish as a community node:

# Build the package
yarn workspace n8n-nodes-agent-chat-interface build

# Navigate to package directory
cd packages/n8n-nodes-agent-chat-interface

# Publish to npm
npm publish

Note: Ensure you have proper npm permissions and the package version is updated before publishing.

Build Process

Dependency Check: Ensures chat-interface-lib is built
React App Build: Creates optimized production bundle
Asset Bundling: Packages all static assets
Node Compilation: Builds TypeScript node code
Cleanup: Removes temporary build directories after 1 hour

📁 Project Structure

packages/n8n-nodes-agent-chat-interface/
├── src/
│   ├── ChatInterfaceNode.node.ts    # Main N8N node implementation
│   ├── ChatInterfaceBuilder.ts      # React app build system
│   └── RuntimeThemeInjector.ts      # Runtime configuration injection
├── dist/                            # Compiled N8N node
├── temp-builds/                     # Temporary React builds (auto-cleanup)
├── assets/                          # Pre-built React app assets
├── package.json
├── tsconfig.json
├── chatInterface.svg                # Node icon
└── README.md

⚡ Performance Notes

Build Time: ~30-60 seconds for initial React app build
Runtime Serving: ~3ms response time with optimized caching
Memory Usage: <50MB footprint with asset serving
Asset Bundling: All dependencies bundled at build time (no runtime compilation)
Auto Cleanup: Temporary builds removed after 1 hour to prevent disk usage buildup
Cache-Busting Technology: Automatic cache prevention for iframe environments with dynamic configuration updates

🔧 Cache-Busting Features

The node includes automatic cache-busting to prevent iframe caching issues:

Cache-Control headers: Prevents browser caching of dynamic content
ETag headers: Unique identifiers for each configuration
Meta tags: Additional cache-control directives in HTML

If you experience caching issues, try a hard refresh (Ctrl+Shift+R) or clear your browser cache.

🔍 Troubleshooting

Common Issues

Node not appearing in N8N palette:

Verify the npm package was installed successfully: npm list n8n-nodes-agent-chat-interface
Check N8N logs for loading errors
Ensure N8N instance was restarted after installation
For community nodes, verify the package name: n8n-nodes-agent-chat-interface

Chat interface not loading:

Verify Chat API URL is accessible
Check browser developer console for errors
Ensure request path is correct (/ for main interface)

Welcome message not appearing:

Verify welcomeMessage parameter contains valid JSON
Check browser console for JSON parsing errors
Ensure the JSON includes required fields like output or message

Option buttons not working:

Verify API response includes options array
Check that options are strings, not objects
Ensure options are properly formatted in the response

Input not being disabled:

Verify disableInput: true is included in API response
Check that the field is a boolean, not a string
Confirm the API response structure is correct

Feedback not working:

Verify feedbackEnabled is set to true
Check that feedback URLs are properly configured
Monitor network requests in browser dev tools

Theme not applying:

Ensure HSL values are in correct format (no hsl() wrapper)
Check that theme colors are properly configured
Verify no syntax errors in color values

Footnote content issues:

The system automatically handles base64 encoding/decoding for complex footnote content
Footnotes support full markdown syntax including code blocks, links, and formatting
Newlines and special characters are safely handled through automatic encoding
No manual escaping is required for multiline content or markdown formatting

API response format issues:

The chat interface supports both output and message fields in API responses
Ensure your API returns one of these fields with the AI response text
Check browser console for "Sorry, I received an empty response" messages
Verify API response structure matches the expected format

Development Debugging

# Enable verbose logging
NODE_ENV=development yarn build

# Test specific paths
curl "http://your-n8n-instance/webhook/chat-interface?path=/"
curl "http://your-n8n-instance/webhook/chat-interface?path=/assets/style.css"

Example flow

{
  "name": "Chat Interface Flow",
  "nodes": [
    {
      "parameters": {
        "path": "chat-interface",
        "responseMode": "responseNode",
        "options": {}
      },
      "type": "n8n-nodes-base.webhook",
      "typeVersion": 2,
      "position": [
        48,
        160
      ],
      "id": "5ad9e94c-996a-4135-a947-25f5a5da12c8",
      "name": "Webhook",
      "webhookId": "chat-interface"
    },
    {
      "parameters": {
        "requestPath": "={{ $json.query?.path ?? \"/\" }}",
        "chatApiUrl": "",
        "chatTitle": "Chat Interface",
        "webhookUrl": "={{ $json.webhookUrl }}",
        "agentMessageFootnote": "This response was generated by AI. Please verify important information.",
        "lightThemeColors": {},
        "darkThemeColors": {}
      },
      "type": "n8n-nodes-agent-chat-interface.chatInterface",
      "typeVersion": 1,
      "position": [
        272,
        160
      ],
      "id": "6cc4b7b0-44d7-4e5a-ac71-0ef9234c69e0",
      "name": "Chat Interface"
    },
    {
      "parameters": {
        "jsCode": "return [\n  {\n    json: {\n      statusCode: $input.first().json.statusCode\n    },\n    binary: {\n      data: {\n        data: $input.first().json.content,\n        mimeType: $input.first().json.contentType,\n        fileName: 'aaa'\n      }\n    }\n  }\n];"
      },
      "type": "n8n-nodes-base.code",
      "typeVersion": 2,
      "position": [
        496,
        160
      ],
      "id": "11706cfb-197d-4221-ac6a-8c6b8fcea8e4",
      "name": "Code"
    },
    {
      "parameters": {
        "respondWith": "binary",
        "options": {
          "responseCode": "={{ $json.statusCode }}"
        }
      },
      "type": "n8n-nodes-base.respondToWebhook",
      "typeVersion": 1.4,
      "position": [
        720,
        160
      ],
      "id": "cd399df6-f325-495c-af62-a5644e41b422",
      "name": "Respond to Webhook"
    }
  ],
  "pinData": {},
  "connections": {
    "Webhook": {
      "main": [
        [
          {
            "node": "Chat Interface",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Chat Interface": {
      "main": [
        [
          {
            "node": "Code",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Code": {
      "main": [
        [
          {
            "node": "Respond to Webhook",
            "type": "main",
            "index": 0
          }
        ]
      ]
    }
  },
  "active": true,
  "settings": {
    "executionOrder": "v1"
  },
  "versionId": "93438130-63cd-4799-ac79-3df509bb8dda",
  "meta": {
    "templateCredsSetupCompleted": true,
    "instanceId": "123123123"
  },
  "id": "123123123",
  "tags": []
}

📄 License

Fusion Flow Software Free Use License – n8n Node

This n8n node is licensed, not sold. Fusion Flow Software grants you a limited, non-exclusive, non-transferable, and royalty-free license to use this n8n node in your own n8n workflows, whether for personal, educational, or commercial purposes.

Restrictions:

The source code is proprietary and is not provided.
You may not modify, reverse engineer, decompile, or disassemble any part of this software.
You may not redistribute or sublicense this software or any derivative works.
You may not host or make this node available as a service to others.

Ownership: This n8n node is the proprietary product of Fusion Flow Software. All rights, title, and interest in and to the node, including all intellectual property rights, are and shall remain the exclusive property of Fusion Flow Software. This license does not grant you any ownership rights to the software—only a limited right to use it under the terms described herein.

Disclaimer: This software is provided "as is," without warranty of any kind. Fusion Flow Software shall not be liable for any damages or losses arising from the use or inability to use this software.

Contact: To contact Fusion Flow Software, visit http://www.fusionflowsoftware.com

By using this software, you agree to the terms of this license.

🚀 Ready to Deploy?

Configure your Chat API URL (mandatory)
Set up your feedback endpoints (optional)
Customize your theme colors (optional)
Test with Request Path = /
Deploy to your N8N workflows

Your chat interface will be served as static content with full customization and zero infrastructure overhead!

Feature ask and contact

You can find me at https://github.com/lelemm/n8n-nodes-agent-chat-interface