Chat UI Trigger

Overview

This node implements a chat interface trigger designed for AI workflows that require message processing and conversation context management. It provides multiple modes of access to the chat:

• Webhook Only: A simple webhook endpoint for custom integrations.
• Hosted Chat: A fully hosted chat UI provided by the node, accessible via a URL.
• Embedded Chat: For embedding the chat widget in other applications using the @n8n/chat widget.

The node listens for incoming HTTP requests (GET or POST) on a configurable webhook path. In Hosted Chat mode, a rich HTML chat interface is served on GET requests, allowing users to interact with the chat assistant directly in their browser. POST requests handle incoming messages, maintain conversation context, and return responses formatted according to user settings.

Practical Use Cases

• Building conversational AI assistants integrated into n8n workflows.
• Providing a customizable chat interface for customer support bots.
• Embedding chat widgets into websites or apps with controlled authentication and CORS policies.
• Using the webhook-only mode to integrate chat functionality into existing systems without UI.

Properties

Output

The node outputs a JSON object representing the current state of the chat interaction. 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 metadata */ ],
    "messageCount": 5,
    "timestamp": "ISO timestamp of response",
    "chatUrl": "URL to hosted chat interface (if applicable)"
  }
  

  This format is streamlined for integration with AI agent nodes expecting a chatInput field.

• Detailed:

  {
    "chatInput": "User's latest message text",
    "messages": [ /* Full array of messages with detailed metadata */ ],
    "userMessage": "User's latest message text",
    "sessionId": "...",
    "threadId": "...",
    "chatMode": "webhook|hosted|embedded",
    "chatUrl": "...",
    "publicAvailable": true|false,
    "authentication": "none|basic",
    "allowedOrigins": "...",
    "initialMessage": "...",
    "displayMode": "simple|rich",
    "features": [...],
    "uiSettings": {...},
    "context": {
      "webhook_path": "...",
      "conversation_length": 5,
      "last_interaction": "ISO timestamp",
      "user_agent": "...",
      "ip_address": "..."
    },
    "raw": {
      "headers": { ... },
      "query": { ... },
      "body": { ... }
    }
  }
  

  This format includes comprehensive context, configuration, and raw request data useful for advanced workflows.

Messages Array Structure

Each message object contains:

• role: "user" or "assistant"
• content: Text content of the message
• timestamp: ISO string timestamp (added if enabled)
• metadata: Includes session and thread IDs, source info
• Flags for UI features like markdown rendering, code highlighting, and copy button actions depending on enabled features

Binary Data

The node does not output binary data.

Dependencies

• No external API keys or services are required by this node itself.
• The node relies on standard HTTP webhook infrastructure within n8n.
• For Hosted and Embedded chat modes, it serves or expects usage of a web-based chat UI.
• Basic Authentication credentials are configured within the node properties.
• CORS policy is configurable via allowed origins property.

Troubleshooting

• Authentication Errors:

  • If Basic Auth is enabled but credentials are missing or incorrect, the node responds with HTTP 401 or 403 errors.
  • Ensure the client sends correct Authorization headers with base64 encoded username and password.

• CORS Issues:

  • Requests from origins not listed in the allowed origins will be rejected with HTTP 403.
  • Verify the Allowed Origins setting matches the client's origin or use * to allow all.

• Webhook Path Conflicts:

  • Make sure the configured webhook path is unique and not conflicting with other webhooks in your n8n instance.

• Hosted Chat Not Loading:

  • The hosted chat UI is served only on GET requests when Chat Access Mode is set to Hosted.
  • If you see errors or blank pages, check network connectivity and ensure the workflow is saved to generate the chat URL.

• Unexpected Output Format:

  • Confirm the Output Format property matches your downstream node expectations (aiAgent vs detailed).

Links and References

• n8n Webhook Documentation
• Basic Authentication RFC
• Cross-Origin Resource Sharing (CORS) W3C Spec
• Markdown Guide (for understanding markdown rendering feature)

This summary covers the static analysis of the node’s execute logic as implemented in the bundled source code and the provided input properties.