ffs-agent-chat-interface

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

Package Information

Released: 11/5/2025
Downloads: 11 weeklyΒ /Β 48 monthly
Latest Version: 0.2.6

Available Nodes

FFS - Chat Interface UI icon
FFS - Chat Interface UI
No description available

Documentation

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
  • 🎯 Interactive API Buttons: Clickable buttons in chat messages that can make API calls with customizable responses
  • πŸ“„ PDF Annotation System: Interactive PDF annotation with guided and free-form modes for document collaboration
  • πŸ“‹ Dynamic Form System: Interactive forms with validation, multiple field types (text, numeric, password, toggle), and real-time feedback
  • 🎯 Intent Guidance System: Smart workflow management that can disable chat input and guide users through structured interactions
  • 🎀 Audio Messages: Support for audio/voice messages with playback controls and base64 encoding
  • βˆ‘ Mathematical Notation: KaTeX integration for rendering complex mathematical equations and formulas
  • πŸ“Š Mermaid Diagrams: Support for rendering flowcharts, sequence diagrams, and other technical diagrams
  • 🌐 Internationalization: Multi-language support with automatic language detection and translation capabilities
  • πŸ“ Enhanced Markdown: Advanced markdown rendering with custom plugins, syntax highlighting, and rich formatting

πŸ“¦ Installation

🌟 NPM Installation (Recommended)

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

  1. Via N8N UI (Easiest):

    • Go to Settings β†’ Community Nodes
    • Click Install a community node
    • Enter: n8n-nodes-ffs-agent-chat-interface
    • Click Install

  2. Via NPM Command:

    npm install n8n-nodes-ffs-agent-chat-interface

  3. Restart N8N: The node will be automatically available after restart

πŸ› οΈ Development Installation

For development or custom modifications:

  1. Clone Repository: Get the source code from the repository
  2. 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-ffs-agent-chat-interface build
  3. Link Locally: 
    # From the n8n-nodes-ffs-agent-chat-interface directory
npm link

# In your N8N installation directory
npm link n8n-nodes-ffs-agent-chat-interface
  4. 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

  1. Add the Node: Drag "Chat Interface" node to your workflow

  2. 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)

  3. 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": "user123@company.com",
  "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
Enable Streaming boolean false Enable streaming responses for real-time message updates (uses the same API URL as regular chat)

πŸ‘ 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,
  "intent": "intent-type",
  "intentData": "intent-specific-data"
}

Response Fields:

  • output (string | object, required): The AI's response text (supports markdown) or an object for structured data. When an object, it's automatically stringified for intent processing while still supporting both formats.
  • 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. Can be simple strings or objects with intent-based actions (see below).
  • 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
  • intent (string, optional): Intent type for special processing (e.g., route, form, pdf-annotate)
  • intentData (string | object, optional): Intent-specific configuration data

Note: The chat interface supports both output and message fields in the API response. Use whichever field name your backend API returns. The output field can be either a string or an object, with automatic handling for both formats.

πŸ”˜ Interactive Options & Input Control

The chat interface supports interactive option buttons with intent-based actions and dynamic input control:

Option Buttons

When your API response includes an options array, clickable buttons are displayed below the message. Options can be either simple strings or objects with specific intents:

Simple String Options:

{
  "options": ["Option 1", "Option 2", "Option 3"]
}

Intent-Based Options:

{
  "options": [
    "Simple text option",
    {
      "text": "Request menu",
      "intent": "request-menu"
    },
    {
      "text": "Route to technical support",
      "intent": "route-request",
      "intentData": {
        "agentName": "tech-support-agent"
      }
    },
    {
      "text": "Submit form",
      "intent": "form-response",
      "intentData": {
        "formId": "contact_form",
        "variables": [...]
      }
    }
  ]
}

Supported Option Intents:

  • message: Simple text message (default for strings)
  • request-menu: Request menu/options from the agent (no intentData required)
  • route-request: Request routing to another agent (requires agentName in intentData)
  • form-response: Submit form data
  • pdf-annotation-response: Submit PDF annotations
  • file-upload-response: Submit file upload data
  • audio-recording-response: Submit audio recording
  • ref: Reference intent with query parameters

Note: When users click any option button, the system automatically includes the user's preferredLanguage in the request payload, enabling proper language handling in your backend.

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 with request-menu intent
  • Agent Routing: Use route-request to direct users to specialized agents
  • Form Filling: Guide users through data collection

Example API Response with Mixed Options:

{
  "output": "I can help you with several things. What would you like to do?",
  "options": [
    "Check my account status",
    {
      "text": "Show main menu",
      "intent": "request-menu"
    },
    {
      "text": "Talk to billing department",
      "intent": "route-request",
      "intentData": {
        "agentName": "billing-agent"
      }
    },
    "Speak with a human agent"
  ],
  "disableInput": true
}

When a user clicks any option, the appropriate message and intent data are sent to your API along with their preferred language setting.

πŸ‘‹ 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 [help@company.com](mailto:help@company.com)\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

🎯 Interactive API Buttons

The chat interface supports interactive buttons that can make API calls directly from chat messages. These buttons allow for seamless integration with external services and provide immediate visual feedback.

Button Syntax

The button plugin supports two syntax formats for creating interactive buttons:

Format 1: Plugin Syntax (Recommended)

::button[Button Text](https://api.example.com/action) {method=POST showResponse=true width=400}

Format 2: Link Syntax (Legacy)

[Button Text](api://method=url)
[Check Status](api://GET=https://api.example.com/status)

Button Features

  • Multiple HTTP Methods: Support for GET, POST, PUT, DELETE, and other HTTP methods
  • Visual Feedback: Loading states, success/error indicators, and response display
  • Flexible Response Handling: Choose between showing response text or just success/error status
  • Customizable Styling: Control button width, styling classes, and appearance
  • Error Handling: Graceful handling of network errors and API failures

Example Usage

Plugin Syntax Examples

::button[Delete Item](https://api.example.com/item/123) {method=DELETE showResponse=true width=400}

::button[Check Status](https://api.example.com/health) {method=GET}

::button[Submit Report](https://api.example.com/reports) {method=POST showResponse=false className=custom-btn}

Legacy Syntax Examples

Click here to check the server status: [Check Status](api://GET=https://api.example.com/health)

Or submit this request: [Submit Report](api://POST=https://api.example.com/reports)

Advanced Configuration

Plugin Syntax Parameters

Parameters are specified in curly braces {} with key=value pairs:

::button[Custom Button](https://api.example.com/action) {method=POST showResponse=true width=200px className=my-custom-class}

Legacy Syntax Parameters

Parameters are specified as URL query parameters:

[Custom Button](api://POST=https://api.example.com/action?showResponse=true&width=200px&className=my-custom-class)

Available Parameters:

  • method (string): HTTP method (GET, POST, PUT, DELETE, etc.) - defaults to GET
  • showResponse (boolean): Whether to display the API response text (default: false)
  • width (string): Custom width for the button (e.g., "200px", "50%")
  • className (string): Additional CSS classes for styling

πŸ“„ PDF Annotation System

The chat interface includes a powerful PDF annotation system that allows users to interactively annotate PDF documents with both guided and free-form annotation modes.

Annotation Modes

Free Annotation Mode

  • Full Control: Users can add annotations anywhere on the PDF
  • Multiple Annotation Types: Support for text comments, highlights, drawings, and notes
  • Flexible Workflow: Perfect for document review, collaboration, and feedback

Guided Annotation Mode

  • Structured Workflow: Pre-defined annotation points guide the user through specific sections
  • Required Fields: Ensure all necessary parts of the document are reviewed
  • Validation: System validates that required annotations are completed
  • Customizable Templates: Define specific annotation requirements per document type

PDF Integration

File Sources

  • Direct URLs: Load PDFs from public URLs
  • Data URLs: Support for base64-encoded PDF content
  • File Uploads: Handle user-uploaded PDF files
  • Dynamic Loading: Fetch PDFs programmatically through API callbacks

Viewer Features

  • Zoom Controls: Full zoom in/out functionality
  • Page Navigation: Easy navigation through multi-page documents
  • Search: Find text within PDF documents
  • Print Support: Print annotated documents
  • Mobile Responsive: Works on tablets and mobile devices

Usage Example

{
  "output": "Please review and annotate this contract:",
  "pdfAnnotation": {
    "instructions": "Please review the terms and conditions, then add your comments.",
    "pdfUrl": "https://example.com/contract.pdf",
    "filename": "ServiceContract.pdf",
    "mode": "guided",
    "guidedAnnotations": [
      {
        "id": "terms_review",
        "name": "Terms Review",
        "description": "Review the payment terms on page 3",
        "page": 3,
        "required": true
      }
    ]
  }
}

API Response Format

When users complete PDF annotations, the system sends structured data:

{
  "formId": "pdf_annotation_123",
  "variables": [
    {
      "id": "annotation_data",
      "value": {
        "annotations": [
          {
            "page": 1,
            "type": "text",
            "content": "Please review this section",
            "position": { "x": 100, "y": 200 }
          }
        ],
        "metadata": {
          "totalPages": 5,
          "annotatedPages": [1, 3],
          "completionTime": "2024-01-01T12:00:00Z"
        }
      }
    }
  ]
}

πŸ“‹ Dynamic Form System

The chat interface supports dynamic, interactive forms that can be rendered within chat conversations. Forms include validation, multiple field types, and real-time feedback to guide users through data collection workflows.

Supported Field Types

Text Input

  • Basic text fields with customizable placeholders
  • Password fields with masked input
  • Numeric fields with built-in validation
  • Email and URL validation patterns

Toggle Switches

  • Boolean inputs with on/off states
  • Visual feedback showing current state
  • Required field validation

Form Features

Validation & Error Handling

  • Real-time validation as users type
  • Required field indicators with visual cues
  • Custom error messages for each field type
  • Form submission blocking until all requirements are met

User Experience

  • Progressive disclosure with field descriptions
  • Animated feedback for user interactions
  • Responsive design that works on all devices
  • Accessibility support with proper labels and ARIA attributes

Usage Example

{
  "output": "Please fill out this registration form:",
  "form": {
    "instructions": "Please provide your contact information and preferences.",
    "formId": "user_registration",
    "variables": [
      {
        "id": "full_name",
        "name": "Full Name",
        "type": "text",
        "mandatory": true,
        "description": "Enter your complete name as it appears on your ID"
      },
      {
        "id": "email",
        "name": "Email Address",
        "type": "text",
        "mandatory": true,
        "description": "We'll use this to send you updates"
      },
      {
        "id": "age",
        "name": "Age",
        "type": "numeric",
        "mandatory": false,
        "description": "Optional: helps us personalize your experience"
      },
      {
        "id": "newsletter",
        "name": "Subscribe to Newsletter",
        "type": "toggle",
        "mandatory": false,
        "description": "Receive weekly updates and tips"
      }
    ]
  }
}

API Response Format

When users submit forms, the system sends structured data:

{
  "formId": "user_registration",
  "variables": [
    {
      "id": "full_name",
      "value": "John Doe"
    },
    {
      "id": "email",
      "value": "john.doe@example.com"
    },
    {
      "id": "age",
      "value": "30"
    },
    {
      "id": "newsletter",
      "value": true
    }
  ]
}

Advanced Features

Conditional Logic

  • Field dependencies based on other field values
  • Dynamic field visibility and requirements
  • Complex validation rules

Integration Capabilities

  • External API validation for field values
  • Dynamic field population from APIs
  • Multi-step form workflows

🎯 Intent Guidance System

The Intent Guidance System provides intelligent workflow management that can guide users through structured interactions, disable chat input when needed, and provide contextual instructions for specific tasks.

Core Features

Input Control

  • Dynamic Input Disabling: Programmatically disable chat input during specific workflows
  • Contextual Guidance: Show instructions when users try to interact outside the intended flow
  • Automatic Re-enabling: Restore input capabilities when workflows complete

Visual Feedback

  • Animated Components: Shake animations to draw attention to interactive elements
  • Status Indicators: Visual cues showing current workflow state
  • Progressive Disclosure: Show guidance only when relevant

Supported Intent Types

Form Intents

  • Field-level guidance for form completion
  • Validation feedback with animated error states
  • Submission confirmation with success animations

PDF Annotation Intents

  • Annotation guidance for document review workflows
  • Progress tracking through multi-step annotation processes
  • Completion confirmation when all required annotations are done

Custom Intents

  • Extensible system for custom workflow types
  • Event-driven animations for user interactions
  • State management across complex interactions

Usage Example

{
  "output": "Let's collect some information from you:",
  "form": {
    "instructions": "Please fill out the registration form below.",
    "formId": "user_registration",
    "variables": [...],
    "disableChatInput": true
  },
  "intentGuidance": {
    "type": "form",
    "instructions": "Please complete the form to continue our conversation.",
    "disabled": true
  }
}

Advanced Configuration

Animation Triggers

  • Event-based animations triggered by user actions
  • Component-specific feedback for different UI elements
  • Custom animation types (shake, pulse, highlight)

Workflow States

  • Active workflows with real-time status updates
  • Completion tracking across multiple interaction steps
  • Error recovery with guided user assistance

πŸ”„ Advanced Intent System

The chat interface supports a comprehensive set of intents that enable sophisticated conversation flows and user interactions. These intents are automatically detected and processed based on your API responses.

πŸ“‹ API Response Format

Your API can send responses in two formats:

Format 1: Dual Structure (Recommended)

{
  "message": "Text displayed in the chat balloon",
  "output": { "url": "https://api.example.com/endpoint" },
  "intent": "route"
}
  • message: Text shown to the user
  • output: Intent configuration data (object or string)
  • intent: Intent type

Format 2: Legacy Structure

{
  "output": "Text displayed in the chat balloon",
  "intent": "route",
  "intentData": "{\"url\":\"https://api.example.com/endpoint\"}"
}
  • output: Text shown to the user
  • intentData: Separate JSON string for intent configuration
  • intent: Intent type

Note: When both message and output exist, message is used for display and output contains the intent data.

πŸ“₯ API Response Intents (Complete Examples)

These are intents that your API sends in responses to control the chat behavior and display special content.

1. message Intent (Default)

Simple text response with optional features:

{
  "output": "Hello! How can I help you today?",
  "intent": "message",
  "references": [
    {
      "name": "User Guide",
      "url": "https://docs.example.com/guide"
    }
  ],
  "showFootnote": true
}

2. end-chat Intent

Gracefully ends the conversation:

{
  "output": "Thank you for using our service. Your session has ended.",
  "intent": "end-chat"
}
  • Behavior: Displays "Chat ended" message, disables input, performs final pooling if active
  • Use Case: Completing conversations, session termination, workflow completion

3. route Intent

Changes the API endpoint for subsequent requests:

{
  "intent": "route",
  "output": {
    "url": "https://api.example.com/tech-support",
    "systemMessage": "You are now connected to the Technical Support team.",
    "sessionId": "new-session-123"
  },
  "message": "Let me transfer you to our technical support specialist."
}
  • Behavior: Updates chat API URL, optionally updates session ID, displays system message if provided
  • Use Case: Multi-step workflows, agent handoffs, specialized endpoints

4. pooling Intent

Starts background polling for asynchronous updates:

{
  "output": "Your request is being processed. I'll update you when it's ready.",
  "intent": "pooling",
  "intentData": "{\"url\":\"https://api.example.com/status-updates\",\"interval\":2000}"
}
  • Behavior: Initiates background polling at specified interval (default 1000ms)
  • Use Case: Long-running processes, status updates, asynchronous operations

5. async-response Intent

Handles asynchronous response delivery:

{
  "intent": "async-response"
}
  • Behavior: Removes placeholder message, processes response when received
  • Use Case: Long API calls, external service integration, background processing

6. pdf-annotate Intent

Interactive PDF annotation with guided or free-form modes:

{
  "output": "Please review and annotate this contract:",
  "intent": "pdf-annotate",
  "intentData": "{\"instructions\":\"Review the terms and conditions\",\"pdfUrl\":\"https://example.com/contract.pdf\",\"filename\":\"ServiceContract.pdf\",\"mode\":\"guided\",\"guidedAnnotations\":[{\"id\":\"terms_review\",\"name\":\"Terms Review\",\"description\":\"Review the payment terms on page 3\",\"page\":3,\"required\":true}],\"disableChatInput\":true}"
}
  • Behavior: Opens PDF annotation interface with structured workflow
  • Use Case: Document review, contracts, forms, collaborative editing

7. form Intent

Dynamic form rendering with validation:

{
  "output": "Please provide your contact information:",
  "intent": "form",
  "intentData": "{\"instructions\":\"Fill out the form below\",\"id\":\"contact_form\",\"variables\":[{\"id\":\"name\",\"name\":\"Full Name\",\"type\":\"string\",\"mandatory\":true,\"order\":1},{\"id\":\"email\",\"name\":\"Email\",\"type\":\"string\",\"mandatory\":true,\"order\":2},{\"id\":\"age\",\"name\":\"Age\",\"type\":\"numeric\",\"mandatory\":false,\"order\":3},{\"id\":\"newsletter\",\"name\":\"Subscribe to Newsletter\",\"type\":\"toggle\",\"mandatory\":false,\"order\":4}],\"disableChatInput\":true}"
}
  • Behavior: Displays interactive form with real-time validation
  • Field Types: string, numeric, password, toggle, dropdown
  • Use Case: Data collection, surveys, registration, configuration

8. file-upload Intent

File upload handling:

{
  "output": "Please upload your documents:",
  "intent": "file-upload",
  "intentData": "{\"uploadId\":\"upload_123\",\"acceptedTypes\":[\"application/pdf\",\"image/*\"],\"maxSize\":10485760,\"multiple\":true}"
}
  • Behavior: Displays file upload interface with drag-and-drop
  • Use Case: Document submission, image processing, file analysis

9. file-download Intent

File download handling:

{
  "output": "Your report is ready for download:",
  "intent": "file-download",
  "intentData": "{\"downloadUrl\":\"https://api.example.com/files/report.pdf\",\"fileName\":\"Monthly_Report.pdf\",\"fileType\":\"application/pdf\"}"
}
  • Behavior: Displays download button and handles file download
  • Use Case: Report generation, document delivery, data export

10. ref Intent

Reference document handling:

{
  "output": "I found relevant information in our knowledge base.",
  "intent": "ref",
  "references": [
    {
      "name": "Installation Guide",
      "content": "Full content of the installation guide...",
      "url": "https://docs.example.com/install"
    }
  ]
}
  • Behavior: Displays references in sidebar with content fetching
  • Use Case: Knowledge base, documentation, help systems

πŸ“€ MessageOption Intents (Complete Examples)

These are intents used in option buttons to control what happens when users click them.

1. message Intent (Default)

Simple text message option:

{
  "output": "What would you like to do?",
  "options": [
    "Check account status",
    {
      "text": "View my profile",
      "intent": "message"
    }
  ]
}

2. request-menu Intent

Request menu/options from agent:

{
  "output": "I can help you with several things.",
  "options": [
    {
      "text": "Show main menu",
      "intent": "request-menu"
    }
  ],
  "disableInput": true
}
  • Behavior: Sends request to backend for menu options
  • Use Case: Hierarchical navigation, dynamic menus

3. route-request Intent

Request routing to another agent:

{
  "output": "How can I help you today?",
  "options": [
    {
      "text": "Talk to billing department",
      "intent": "route-request",
      "intentData": {
        "agentName": "billing-agent"
      }
    },
    {
      "text": "Technical support",
      "intent": "route-request",
      "intentData": {
        "agentName": "tech-support-agent"
      }
    }
  ]
}
  • Behavior: Requests agent routing with specified agent name
  • Use Case: Agent handoffs, department routing

4. form-response Intent

Submit form data:

{
  "output": "Form submitted successfully!",
  "options": [
    {
      "text": "Submit another form",
      "intent": "form-response",
      "intentData": {
        "formId": "contact_form",
        "variables": [
          {"id": "name", "value": "John Doe"},
          {"id": "email", "value": "john@example.com"}
        ]
      }
    }
  ]
}
  • Behavior: Sends form data to backend
  • Use Case: Pre-filled forms, quick submissions

5. pdf-annotation-response Intent

Submit PDF annotations:

{
  "output": "PDF annotation completed.",
  "options": [
    {
      "text": "Submit annotations",
      "intent": "pdf-annotation-response",
      "intentData": {
        "filename": "contract.pdf",
        "totalPages": 5,
        "annotations": [
          {
            "page": 1,
            "type": "text",
            "content": "Reviewed and approved",
            "position": {"x": 100, "y": 200}
          }
        ],
        "exportDate": "2024-01-01T12:00:00Z"
      }
    }
  ]
}
  • Behavior: Sends PDF annotation data to backend
  • Use Case: Document review workflows

6. file-upload-response Intent

Submit uploaded file data:

{
  "output": "Files ready to upload.",
  "options": [
    {
      "text": "Confirm upload",
      "intent": "file-upload-response",
      "intentData": {
        "uploadId": "upload_123",
        "files": [
          {
            "name": "document.pdf",
            "size": 102400,
            "type": "application/pdf",
            "data": "base64-encoded-file-data"
          }
        ]
      }
    }
  ]
}
  • Behavior: Sends uploaded file data to backend
  • Use Case: File submission workflows

7. audio-recording-response Intent

Submit audio recording:

{
  "output": "Audio recording ready.",
  "options": [
    {
      "text": "Send voice message",
      "intent": "audio-recording-response",
      "intentData": {
        "recording": "base64-encoded-audio-data",
        "recordingSampleRate": 48000,
        "recordingEncode": "webm"
      }
    }
  ]
}
  • Behavior: Sends audio recording to backend
  • Use Case: Voice messages, audio feedback

8. ref Intent

Reference with query parameters:

{
  "output": "Need more information?",
  "options": [
    {
      "text": "Search knowledge base",
      "intent": "ref",
      "intentData": {
        "query": "installation guide",
        "category": "documentation"
      }
    }
  ]
}
  • Behavior: Sends reference query to backend
  • Use Case: Knowledge base searches, contextual help

9. custom-intent Intent

Custom intent with arbitrary data:

{
  "output": "Choose an action:",
  "options": [
    {
      "text": "Custom action",
      "intent": "custom-intent",
      "intentData": {
        "actionType": "special-workflow",
        "params": {
          "workflowId": "123",
          "step": 2
        }
      }
    }
  ]
}
  • Behavior: Sends custom intent data to backend
  • Use Case: Application-specific workflows

πŸ“Š Intent Property Reference

Detailed property tables for each intent's configuration data.

1. route Intent Properties

Property Type Required Description
url string βœ… Yes New API endpoint URL to use for subsequent chat requests
systemMessage string ❌ Optional System message displayed BEFORE the agent's message to inform user of the routing
sessionId string ❌ Optional New session ID to use for subsequent requests

Example (Dual Structure):

{
  "message": "Connecting you to technical support...",
  "output": {
    "url": "https://api.example.com/tech-support",
    "systemMessage": "You are now connected to Technical Support.",
    "sessionId": "session-456"
  },
  "intent": "route"
}

2. pooling Intent Properties

Property Type Required Description
url string βœ… Yes URL to poll for async message updates
systemMessage string ❌ Optional System message displayed when pooling starts
interval number ❌ Optional Polling interval in milliseconds (default: 1000ms)

Example (Dual Structure):

{
  "message": "Processing your request...",
  "output": {
    "url": "https://api.example.com/status-updates",
    "interval": 2000
  },
  "intent": "pooling"
}

3. pdf-annotate Intent Properties

Property Type Required Description
instructions string βœ… Yes Instructions displayed to user about what to annotate
url string ⚠️ Conditional PDF URL to load (required if base64 not provided)
base64 string ⚠️ Conditional Base64-encoded PDF data (required if url not provided)
filename string βœ… Yes Filename to display and use for downloaded annotated PDF
mode 'free' | 'guided' βœ… Yes Annotation mode: free (user can annotate anywhere) or guided (predefined annotation points)
guidedAnnotations array ⚠️ Conditional Array of guided annotation items (required if mode is 'guided')
guidedAnnotations[].id string βœ… Yes Unique identifier for this annotation point
guidedAnnotations[].name string βœ… Yes Display name for this annotation point
guidedAnnotations[].description string ❌ Optional Additional description or instructions for this point
guidedAnnotations[].mandatory boolean βœ… Yes Whether this annotation point must be completed
disableChatInput boolean ❌ Optional Whether to disable chat text input while PDF is open (default: false)

Example (Dual Structure):

{
  "message": "Please review and annotate this contract:",
  "output": {
    "instructions": "Review the payment terms and add your comments",
    "url": "https://example.com/contract.pdf",
    "filename": "ServiceContract.pdf",
    "mode": "guided",
    "guidedAnnotations": [
      {
        "id": "payment_terms",
        "name": "Payment Terms Review",
        "description": "Review section 3 on page 2",
        "mandatory": true
      }
    ],
    "disableChatInput": true
  },
  "intent": "pdf-annotate"
}

4. form Intent Properties

Property Type Required Description
instructions string βœ… Yes Instructions displayed above the form
id string βœ… Yes Unique form identifier sent back with submission
variables array βœ… Yes Array of form fields to display
variables[].id string βœ… Yes Unique field identifier
variables[].name string βœ… Yes Field label displayed to user
variables[].order number βœ… Yes Field display order (ascending)
variables[].description string ❌ Optional Help text displayed below the field
variables[].type string ❌ Optional Field type: string, numeric, password, toggle, dropdown (default: string)
variables[].mandatory boolean βœ… Yes Whether field must be filled before submission
variables[].options array ⚠️ Conditional Dropdown options (required if type is dropdown)
variables[].options[].id string βœ… Yes Option value
variables[].options[].name string βœ… Yes Option display text
disableChatInput boolean ❌ Optional Whether to disable chat text input while form is open (default: false)

Example (Dual Structure):

{
  "message": "Please fill out this registration form:",
  "output": {
    "instructions": "We need some information to create your account",
    "id": "user_registration",
    "variables": [
      {
        "id": "full_name",
        "name": "Full Name",
        "order": 1,
        "type": "string",
        "mandatory": true
      },
      {
        "id": "email",
        "name": "Email Address",
        "order": 2,
        "type": "string",
        "description": "We'll send a confirmation to this address",
        "mandatory": true
      },
      {
        "id": "age",
        "name": "Age",
        "order": 3,
        "type": "numeric",
        "mandatory": false
      },
      {
        "id": "newsletter",
        "name": "Subscribe to Newsletter",
        "order": 4,
        "type": "toggle",
        "mandatory": false
      }
    ],
    "disableChatInput": true
  },
  "intent": "form"
}

5. file-upload Intent Properties

Property Type Required Description
instructions string βœ… Yes Instructions for what files to upload
id string βœ… Yes Unique upload identifier sent back with files
allowedTypes array βœ… Yes Allowed file extensions (e.g., ['pdf', 'docx', 'jpg', 'png'])
maxSize number βœ… Yes Maximum file size in MB
multiple boolean βœ… Yes Whether multiple files can be uploaded
mandatory boolean βœ… Yes Whether at least one file must be uploaded
disableChatInput boolean ❌ Optional Whether to disable chat text input during upload (default: false)

Example (Dual Structure):

{
  "message": "Please upload your documents:",
  "output": {
    "instructions": "Upload your ID and proof of address",
    "id": "kyc_documents",
    "allowedTypes": ["pdf", "jpg", "png"],
    "maxSize": 10,
    "multiple": true,
    "mandatory": true,
    "disableChatInput": true
  },
  "intent": "file-upload"
}

6. file-download Intent Properties

Property Type Required Description
instructions string βœ… Yes Instructions about the download
id string βœ… Yes Unique download identifier
files array βœ… Yes Array of files available for download
files[].name string βœ… Yes Display name for the file
files[].url string ⚠️ Conditional URL to download file (required if data not provided)
files[].data string ⚠️ Conditional Base64-encoded file data (required if url not provided)
files[].size number ❌ Optional File size in bytes
files[].type string ❌ Optional MIME type (e.g., application/pdf)
files[].description string ❌ Optional File description
disableChatInput boolean ❌ Optional Whether to disable chat text input during download (default: false)

Example (Dual Structure):

{
  "message": "Your report is ready:",
  "output": {
    "instructions": "Download your monthly report below",
    "id": "monthly_report",
    "files": [
      {
        "name": "Report_January_2024.pdf",
        "url": "https://api.example.com/files/report.pdf",
        "size": 1048576,
        "type": "application/pdf",
        "description": "Monthly sales and analytics report"
      }
    ]
  },
  "intent": "file-download"
}

7. ref Intent Properties

Property Type Required Description
(Any key) string | number | boolean | null ❌ Optional Custom query parameters for reference lookup

Note: The ref intent accepts any key-value pairs as query parameters. The actual references are provided in the top-level references array.

Example (Dual Structure):

{
  "message": "I found relevant information:",
  "output": {
    "query": "installation guide",
    "category": "documentation",
    "version": "2.0"
  },
  "intent": "ref",
  "references": [
    {
      "name": "Installation Guide v2.0",
      "content": "Step-by-step installation instructions...",
      "url": "https://docs.example.com/install"
    }
  ]
}

8. end-chat Intent Properties

Property Type Required Description
(No properties) - - This intent takes no configuration data

Example:

{
  "output": "Thank you for using our service. Your session has ended.",
  "intent": "end-chat"
}

9. async-response Intent Properties

Property Type Required Description
(No properties) - - This intent takes no configuration data

Example:

{
  "intent": "async-response"
}

Intent Processing Features

Automatic Detection

  • Smart Intent Recognition: Automatically detects and processes intents from API responses
  • Multiple Sources: Handles intents from regular responses, streaming, pooling, and IndexedDB restoration
  • Conflict Resolution: Prevents duplicate processing when same intent comes from multiple sources

State Management

  • Redux Integration: All intent states are managed through Redux for consistency
  • Session Persistence: Intent states persist across browser sessions
  • Real-time Updates: Immediate UI updates when intents are processed

Error Handling

  • Graceful Degradation: Failed intent processing doesn't break the chat
  • Validation: Intent data validation before processing
  • Logging: Comprehensive logging for debugging intent flows

Intent Response Format

All intents support the standard ChatResponse format with additional intent-specific data:

{
  "output": "User-facing message text",
  "intent": "intent-type",
  "intentData": "{\"key\":\"value\",\"setting\":123}",
  "options": ["Option 1", "Option 2"],
  "disableInput": true,
  "references": [...]
}

Intent Data Field

  • JSON String: intentData should be a JSON string containing intent-specific configuration
  • Type Safety: Each intent type expects specific data structure
  • Validation: Invalid JSON in intentData is logged as error but doesn't break functionality
  • Optional: Many intents work without intentData, using sensible defaults

βˆ‘ Mathematical Notation

The chat interface includes full support for mathematical notation rendering using KaTeX, allowing you to display complex equations, formulas, and mathematical expressions with proper typography.

Supported Syntax

Inline Math

Use single dollar signs for inline mathematical expressions:

The equation $E = mc^2$ shows the relationship between energy and mass.

Block Math

Use double dollar signs for centered, display-style equations:

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

Advanced Features

Equation Numbering

  • Automatic numbering for equations
  • Cross-references to equation numbers
  • Custom labels for important equations

Complex Expressions

  • Matrices and arrays with proper alignment
  • Multi-line equations with alignment points
  • Chemical formulas and reactions
  • Physics notation (vectors, tensors, operators)

Usage Examples

Basic Algebra

$$ax^2 + bx + c = 0$$

Calculus

$$\frac{d}{dx} \int f(x) dx = f(x)$$

Linear Algebra

$$\begin{pmatrix}
a & b \\
c & d
\end{pmatrix}
\begin{pmatrix}
x \\
y
\end{pmatrix} =
\begin{pmatrix}
ax + by \\
cx + dy
\end{pmatrix}$$

Complex Analysis

$$f(z) = \sum_{n=0}^{\infty} \frac{z^n}{n!}$$

Configuration

The mathematical notation system is automatically enabled and requires no additional configuration. KaTeX renders equations client-side for optimal performance and supports:

  • Real-time rendering as equations are typed
  • Error handling for malformed expressions
  • Fallback display for unsupported browsers
  • Theme integration with light/dark mode support

πŸ“Š Mermaid Diagrams

The chat interface supports rendering Mermaid diagrams directly in chat messages, allowing you to create flowcharts, sequence diagrams, Gantt charts, and other technical diagrams using simple text-based syntax.

Supported Diagram Types

Flowcharts

graph TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Great!]
    B -->|No| D[Debug]
    D --> B

Sequence Diagrams

sequenceDiagram
    participant User
    participant Chat
    participant API

    User->>Chat: Send message
    Chat->>API: Forward request
    API-->>Chat: Return response
    Chat-->>User: Display result

Gantt Charts

gantt
    title Project Timeline
    dateFormat YYYY-MM-DD
    section Planning
    Define requirements    :done, req, 2024-01-01, 2024-01-05
    Create mockups        :done, mock, after req, 2024-01-10
    section Development
    Frontend development   :active, front, 2024-01-15, 2024-02-15
    Backend development    :back, after front, 2024-02-01

State Diagrams

stateDiagram-v2
    [*] --> Idle
    Idle --> Processing: User Input
    Processing --> Idle: Complete
    Processing --> Error: Failure
    Error --> Idle: Retry

Advanced Features

Interactive Diagrams

  • Zoom and pan controls for large diagrams
  • Clickable elements with custom actions
  • Dynamic theming that adapts to light/dark modes
  • Responsive scaling for different screen sizes

Custom Styling

  • Color customization for nodes and connections
  • Font and size adjustments for readability
  • Animation effects for state transitions
  • Export capabilities (PNG, SVG formats)

Usage in Chat

Inline Diagrams

Here's the system architecture:

```mermaid
graph LR
    Client[Web Client] --> API[REST API]
    API --> DB[(Database)]
    API --> Cache[(Redis)]


#### Large Diagrams
For complex diagrams, use the full-width display:

```markdown
```mermaid
graph TB
    subgraph "User Interface"
        A[Login Page] --> B[Dashboard]
    end
    subgraph "Backend Services"
        C[Auth Service] --> D[User Service]
        D --> E[Database]
    end
    B --> C


### Configuration

Mermaid diagrams are automatically rendered when detected in code blocks with the `mermaid` language identifier. The system includes:

- **Syntax validation** with error highlighting
- **Performance optimization** for large diagrams
- **Fallback rendering** for unsupported browsers
- **Theme integration** with automatic color scheme adaptation

## 🌐 Internationalization (i18n)

The chat interface includes comprehensive internationalization support, enabling multi-language experiences with automatic language detection and seamless translation capabilities.

### Core Features

#### Automatic Language Detection
- **Browser language detection** using i18next-browser-languagedetector
- **Fallback languages** for unsupported locales
- **User preference storage** across sessions
- **Dynamic language switching** without page reload

#### Translation Management
- **Key-based translations** for consistent terminology
- **Pluralization support** for different number forms
- **Context-aware translations** for gender and formality
- **Namespace organization** for modular translation files

### Supported Languages

The system supports all major world languages including:

- **English** (en) - Default fallback
- **Spanish** (es) - EspaΓ±ol
- **French** (fr) - Français
- **German** (de) - Deutsch
- **Portuguese** (pt) - PortuguΓͺs
- **Chinese** (zh) - δΈ­ζ–‡
- **Japanese** (ja) - ζ—₯本θͺž
- **Korean** (ko) - ν•œκ΅­μ–΄
- **Arabic** (ar) - Ψ§Ω„ΨΉΨ±Ψ¨ΩŠΨ© (RTL support)
- **Hindi** (hi) - ΰ€Ήΰ€Ώΰ€¨ΰ₯ΰ€¦ΰ₯€
- **Russian** (ru) - Русский

### Usage Examples

#### Basic Translations
```javascript
// In your API response
{
  "output": "Hello! How can I help you today?",
  "translated": {
    "greeting": "Β‘Hola! ΒΏCΓ³mo puedo ayudarte hoy?",
    "language": "es"
  }
}

Contextual Messages

{
  "output": "You have 1 new message", // Singular
  "output_plural": "You have {{count}} new messages", // Plural
  "count": 5
}

Configuration

Language Detection Order

  1. Query parameter: ?lang=es
  2. Local storage: Previously selected language
  3. Browser language: Navigator.language
  4. Fallback: English (en)

Custom Language Setup

{
  "i18n": {
    "defaultLanguage": "en",
    "fallbackLanguage": "en",
    "supportedLanguages": ["en", "es", "fr", "de"],
    "namespace": "chat"
  }
}

Advanced Features

Right-to-Left (RTL) Support

  • Automatic text direction detection
  • RTL layout adjustments for Arabic and Hebrew
  • Bi-directional text handling
  • Icon and UI mirroring for RTL languages

Date and Number Formatting

  • Localized date formats (MM/DD/YYYY vs DD/MM/YYYY)
  • Number formatting with proper separators
  • Currency display in local formats
  • Time zone handling for international users

Accessibility

  • Screen reader support in multiple languages
  • Keyboard navigation with localized shortcuts
  • ARIA labels translated for assistive technologies

πŸ“ Enhanced Markdown

The chat interface features an advanced markdown rendering system with custom plugins, syntax highlighting, and rich formatting capabilities that extend beyond standard markdown.

Core Features

Extended Syntax Support

  • GitHub Flavored Markdown (GFM) with tables, strikethrough, and task lists
  • Custom plugins for specialized content types
  • Enhanced code blocks with syntax highlighting
  • Footnote support with collapsible sections

Advanced Formatting

  • Custom heading styles with consistent typography
  • Enhanced link handling with security features
  • Improved list styling with better spacing and indentation
  • Table formatting with responsive design

Custom Plugins

Button Plugin

Interactive buttons within markdown text using the plugin syntax:

::button[Click me](https://api.example.com/action) {method=GET}

::button[Delete Item](https://api.example.com/item/123) {method=DELETE showResponse=true width=400}

Reference Plugin

Structured references with expandable content:

[Reference Name](ref://content)

Code Block Enhancements

Syntax Highlighting

// Enhanced syntax highlighting with themes
function example() {
  console.log("Hello, World!");
}

Language Support

  • 80+ programming languages supported
  • Custom themes for light and dark modes
  • Line numbers and highlighting
  • Copy to clipboard functionality

Advanced Features

Raw HTML Support

Safe rendering of HTML content with security filtering:

<div class="custom-content">
  <h3>Custom HTML Content</h3>
  <p>This content is safely rendered.</p>
</div>

Mathematical Expressions

Integrated KaTeX rendering within markdown:

The formula $E = mc^2$ is fundamental to physics.

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

Diagram Integration

Mermaid diagrams embedded in markdown:

```mermaid
graph TD
    A --> B --> C


### Security Features

#### Content Sanitization
- **XSS protection** with DOMPurify integration
- **Safe HTML rendering** with allowlists
- **Link validation** and external link handling
- **Script injection prevention**

#### Performance Optimizations
- **Lazy loading** for large content blocks
- **Syntax caching** for repeated renders
- **Memory management** for long conversations
- **Progressive rendering** for streaming content

### Configuration

#### Custom Renderers
```javascript
const customComponents = {
  h1: ({ children }) => <h1 className="custom-heading">{children}</h1>,
  code: ({ children }) => <code className="custom-code">{children}</code>
};

Plugin System

  • Extensible architecture for custom plugins
  • Plugin configuration through props
  • Conditional rendering based on content type
  • Performance monitoring and optimization

πŸ›£οΈ URL Routing & Asset Serving

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-ffs-agent-chat-interface dev

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

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

Publishing to NPM

To publish as a community node:

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

# Navigate to package directory
cd packages/n8n-nodes-ffs-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

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

πŸ“ Project Structure

packages/n8n-nodes-ffs-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-ffs-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-ffs-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-ffs-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

Copyright (c) 2025 Fusion Flow Software

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?

  1. Configure your Chat API URL (mandatory)
  2. Set up your feedback endpoints (optional)
  3. Customize your theme colors (optional)
  4. Test with Request Path = /
  5. 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-ffs-agent-chat-interface

Discussion