Chat UI Trigger icon

Chat UI Trigger

Chat interface trigger for AI workflows with message processing and conversation context

Overview

This node implements a chat interface trigger designed for AI workflows that process messages and maintain conversation context. 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 n8n, 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 chat interface is served on GET requests, allowing users to interact with the workflow through a user-friendly web chat. POST requests handle incoming messages, manage session and thread IDs, apply optional authentication and CORS restrictions, and format the output for downstream nodes.

Practical Examples

  • Customer Support Bot: Use Hosted Chat mode to provide a public-facing chat assistant on your website that routes queries into an AI-powered workflow.
  • Internal Team Assistant: Use Embedded Chat mode to integrate a chat widget inside internal tools, requiring basic authentication.
  • Custom Integration: Use Webhook Only mode to connect external chat clients or services directly to your AI workflows via webhook calls.

Properties

Name Meaning
Chat Access Mode How users will access the chat interface. Options: Webhook Only, Hosted Chat, Embedded Chat.
Webhook Path The URL path where the webhook listens for incoming chat requests.
Options > Response Mode When and how to respond to the webhook request. Options: Last Node (returns response from last executed node), Respond to Webhook (response defined by a Respond to Webhook node).
Public Available (Only for Hosted Chat) Whether the chat is publicly accessible. Should be off during development and enabled when ready for users.
Authentication (For Hosted and Embedded Chat) Access restriction method. Options: None, Basic Auth (requires username and password).
Username (If Basic Auth selected) Username for authentication.
Password (If Basic Auth selected) Password for authentication.
Allowed Origins (CORS) (For Hosted and Embedded Chat) Comma-separated list of allowed origins for cross-origin requests. Use * to allow all origins.
Initial Message (Only for Hosted Chat) Welcome message shown when the chat loads.
Display Mode Chat interface display style. Options: Simple (basic interface), Rich (enhanced interface with Markdown support).
Output Format Structure of the node's output. Options: AI Agent Compatible (simplified output with chatInput field for AI Agent nodes), Detailed (full output with metadata and context).
Features Chat interface features to enable. Multi-select options: Markdown Rendering, Code Highlighting, Copy Button, Timestamps.
UI Settings Collection of UI customization options including:
- Theme (Light, Dark, Auto)
- Compact Mode (boolean for compact message spacing)
- Max Height (px) for chat container size

Output

The node outputs JSON data 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": "Session identifier string",
  "threadId": "Thread identifier string",
  "messages": [ /* Array of message objects with roles, content, timestamps, and metadata */ ],
  "messageCount": 10,
  "timestamp": "ISO timestamp of the response",
  "chatUrl": "URL to hosted chat interface (if applicable)"
}

    This format is simplified for easy consumption by AI agent nodes.

  • Detailed:
    Includes all fields from the AI Agent format plus additional metadata such as:

    • userMessage: The raw user message text.
    • chatMode: The selected chat access mode.
    • publicAvailable: Boolean indicating if chat is public (hosted mode).
    • authentication: Authentication method used.
    • allowedOrigins: CORS allowed origins.
    • initialMessage: The initial welcome message.
    • displayMode: Chat UI display mode.
    • features: Enabled chat features.
    • uiSettings: UI customization settings.
    • context: Object containing webhook path, conversation length, last interaction timestamp, user agent, and IP address.
    • raw: Raw HTTP headers, query parameters, and body data received.

No binary data output is produced by this node.

Dependencies

  • Requires an HTTP webhook endpoint configured in n8n to receive chat messages.
  • Optional Basic Authentication credentials if enabled.
  • No external API keys or third-party service dependencies are required.
  • For Hosted Chat mode, the node serves a built-in HTML/JavaScript chat interface.
  • The node uses standard web technologies (HTML, CSS, JavaScript) for the hosted chat UI.

Troubleshooting

  • Authentication Errors:

    • If Basic Auth is enabled but missing or incorrect credentials are provided, the node responds with HTTP 401 or 403 errors.
    • Ensure correct username and password are set in node properties and sent by the client.

  • CORS Issues:

    • If the origin of the request is not included in the allowed origins list (when not set to *), the node returns HTTP 403.
    • Verify the Allowed Origins property matches the domains making requests.

  • Webhook Path Conflicts:

    • Make sure the Webhook Path is unique and does not conflict with other webhooks in your n8n instance.

  • Chat URL Not Available:

    • The hosted chat URL is only available after saving the workflow.
    • If the URL shows as unavailable, save and activate the workflow.

  • Unexpected Response Formats:

    • Check the Output Format setting to ensure downstream nodes expect the correct data structure.

  • UI Not Loading or Broken (Hosted Chat mode):

    • Confirm the GET request to the webhook path returns the full HTML page.
    • Check browser console for JavaScript errors.
    • Verify network connectivity and no firewall blocking.

Links and References

Discussion