Better Chat Trigger

Overview

This node implements an enhanced chat trigger designed to facilitate interactive chat experiences within n8n workflows. It supports both a hosted chat interface served by n8n and an embedded chat widget accessible via webhook calls. The node is useful for scenarios where you want to integrate conversational interfaces into your automation workflows, such as customer support bots, AI assistants, or interactive FAQ systems.

Key features include:

• Public or private chat modes.
• Authentication options (none or basic auth).
• Customizable welcome message.
• Support for file uploads with MIME type restrictions.
• Rich UI enhancements like Markdown rendering, code highlighting, copy buttons, timestamps, and theme selection.
• Flexible response modes controlling when and how the webhook responds.
• Output formats tailored either for AI agent compatibility or detailed metadata.

Practical examples:

• Embedding a chat widget on a website that interacts with backend workflows.
• Hosting a standalone chat page for customer engagement.
• Using the chat to collect user input and trigger complex automations based on conversation context.

Properties

Output

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

• AI Agent Compatible (default):

  {
    "chatInput": "User's latest message text",
    "sessionId": "Unique session identifier",
    "threadId": "Unique thread identifier",
    "messages": [ /* Array of message objects with roles, content, timestamps, and UI flags */ ],
    "messageCount": 10,
    "timestamp": "ISO timestamp of response",
    "chatUrl": "URL to hosted chat interface (if applicable)"
  }
  

• Detailed:
  Includes all fields from the AI Agent format plus:

  • userMessage: Raw user message string.
  • chatMode: Chat mode used ("hostedChat" or "webhook").
  • publicAvailable: Boolean indicating if chat is public.
  • authentication: Authentication method in use.
  • allowedOrigins: CORS allowed origins.
  • initialMessage: Welcome message.
  • displayMode, features, theme, compactMode, maxHeight: UI configuration details.
  • context: Metadata about conversation length, last interaction time, user agent, and IP address.
  • raw: Raw HTTP headers, query parameters, and body data received.

Messages in the messages array are enriched with UI-related flags such as markdown, codeHighlight, actions (e.g., copy button), and timestamps depending on enabled features.

No binary data output is produced by this node.

Dependencies

• Requires an HTTP Basic Authentication credential if Basic Auth is enabled.
• No external API dependencies; all logic is self-contained.
• The node serves an HTML+JS chat interface for hosted chat mode.
• CORS origins can be configured to control cross-origin requests.
• Uses standard web technologies (HTML, CSS, JavaScript) for the chat UI.

Troubleshooting

• Authentication errors: If Basic Auth is enabled but credentials are missing or incorrect, the node returns HTTP 401 or 403 responses. Ensure correct username and password are configured and sent in the Authorization header.
• CORS issues: Requests from origins not listed in the allowed origins will be rejected with HTTP 403. Verify the allowed origins setting matches client URLs.
• Method not allowed: Only GET (for setup) and POST (for chat messages) methods are supported. Other HTTP methods return 405.
• Chat URL unavailable: The hosted chat URL is only available after saving the workflow. Before saving, a placeholder message is shown.
• File uploads disabled: If file uploads are needed, enable them explicitly and specify allowed MIME types.
• UI feature toggles: Some UI features depend on enabling corresponding flags; ensure desired features are selected in the UI Enhancements property.

Links and References

• n8n Documentation - Creating Custom Nodes
• HTTP Basic Authentication
• Cross-Origin Resource Sharing (CORS)
• Markdown Guide