Better Chat Trigger icon

Better Chat Trigger

Enhanced chat trigger with rich UI features and full Respond to Webhook compatibility

Overview

This node implements an enhanced chat trigger for n8n workflows, providing a rich and customizable chat interface that can be either publicly accessible or used internally via manual chat. It supports two modes: a hosted chat served by n8n itself, or an embedded chat accessed through a webhook for integration into other pages or widgets.

The node is designed to facilitate conversational interactions within n8n workflows, making it ideal for building chatbots, customer support assistants, or AI agents that respond dynamically based on workflow logic. It supports features like file uploads, authentication, CORS control, and UI customization, enabling flexible deployment scenarios.

Practical examples:

  • Embedding a customer support chat widget on a website that connects to n8n workflows for automated responses.
  • Hosting an internal team assistant chat interface with custom branding and message formatting.
  • Creating AI agent interfaces that interact with external APIs or databases via n8n workflows.

Properties

Name Meaning
Make Chat Publicly Available (public) Boolean flag to make the chat accessible publicly or restrict it to manual chat interface only.
Mode (mode) Chat mode when public: Hosted Chat (chat served by n8n) or Embedded Chat (chat via webhook/widget).
Authentication (authentication) Authentication method for public chat: None or Basic Auth (single username/password for all users).
Initial Message (initialMessage) Welcome message shown when the chat loads (only for Hosted Chat mode).
Options (options) Collection of options including:
- Response Mode: When Last Node Finishes or Using 'Respond to Webhook' Node
- Allowed Origins (CORS): comma-separated URLs or * for all
- Allow File Uploads (boolean)
- Allowed File Mime Types: comma-separated MIME types or *
UI Enhancements (uiEnhancements) Collection of UI customization options:
- Compact Mode (boolean)
- Custom Colors (assistant message, background, container, primary color, text, user message)
- Display Mode: Simple or Rich
- Features: multi-select among Markdown Rendering, Code Highlighting, Copy Button, Timestamps
- Font Size: Small, Medium, Large, Extra Large
- Height, Max Height, Width, Max Width, Min Width (CSS size strings)
- Output Format: AI Agent Compatible (simplified) or Detailed (full metadata)
- Theme: Light, Dark, Auto
- Border Radius, Box Shadow, Border Style, Padding, Margin (CSS styles)
- Font Family: system, sans-serif, serif, monospace
- Line Height: compact, normal, relaxed, loose
- Enable Animations (boolean)
- Animation Speed: fast, normal, slow

Output

The node outputs JSON data representing the chat interaction and context. The structure depends on the selected output format:

  • AI Agent Compatible (default):
    Provides a simplified object containing:

    • chatInput: the user's current message text.
    • sessionId: unique session identifier.
    • threadId: unique thread/conversation identifier.
    • messages: array of processed messages with roles, content, timestamps, and optional metadata.
    • messageCount: total number of messages in the conversation.
    • timestamp: timestamp of the current interaction.
    • If files were uploaded, includes flags and file info (hasFiles, fileCount, fileNames).
    • For hosted chat mode, includes a chatUrl and a formatted _chatAccess string with a link.

  • Detailed:
    Includes all fields from the simplified format plus:

    • userMessage: raw user input.
    • chatMode, publicAvailable, authentication, allowedOrigins, initialMessage.
    • UI display settings such as displayMode, features, theme, compactMode, maxHeight.
    • Contextual info like conversation length, last interaction time, user agent, IP address.
    • Raw HTTP headers, query parameters, and body data (with file data sanitized).

If files are included in the request, they are decoded from base64 and attached as binary properties in the output, preserving filename, MIME type, and size.

Dependencies

  • Requires an API endpoint exposed by the node's webhook for chat communication.
  • Optional Basic Authentication credential if enabled.
  • Uses standard web technologies (HTML, CSS, JavaScript) for the hosted chat UI.
  • External libraries loaded in the hosted chat page for syntax highlighting (Prism.js).
  • No additional external services required; all chat logic is handled within n8n workflows triggered by this node.

Troubleshooting

  • Authentication errors:
    If Basic Auth is enabled but credentials are missing or incorrect, the node returns HTTP 401 or 403 errors. Ensure correct username and password are configured and sent by clients.

  • CORS issues:
    When Allowed Origins is restricted, requests from disallowed origins will be rejected with HTTP 403. Verify the origin header matches allowed URLs or use * to allow all.

  • File upload problems:
    Uploaded files must conform to allowed MIME types. Invalid base64 data or unsupported formats will cause errors logged in the console. Check file encoding and MIME type settings.

  • Method not allowed:
    Only GET (for setup page) and POST (for chat messages) methods are supported. Other HTTP methods return 405 errors.

  • UI rendering issues:
    Custom colors, fonts, or themes may cause unexpected appearance if invalid CSS values are provided. Use valid CSS color codes and font family names.

  • Session ID generation:
    Session IDs are generated client-side and stored in sessionStorage. Clearing browser storage resets sessions.

Links and References

Discussion