Chat Hub UI

Relevant source files

The following files were used as context for generating this wiki page:

• packages/cli/src/modules/chat-hub/chat-hub-workflow.service.ts
• packages/frontend/@n8n/chat/README.md
• packages/frontend/editor-ui/src/app/components/ChatEmbedModal.vue
• packages/frontend/@n8n/design-system/src/components/AskAssistantChat/AskAssistantChat.stories.ts
• packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/chatbot.ts
• packages/frontend/editor-ui/src/experiments/readyToRunWorkflowsV2/workflows/ai-workflow-v6.ts

The Chat Hub UI is an embeddable chat interface system designed to facilitate communication between end-users and n8n AI-powered workflows. It provides a modular widget that can be integrated into external websites via CDN or package imports (Vue/React), enabling real-time interaction with LangChain-based agents and standard n8n nodes.

The UI supports various messaging states including text, code snippets, tool execution updates, and streaming responses. It acts as the frontend consumer for workflows triggered by the "Chat Trigger" node, allowing users to send messages, upload files, and receive structured or conversational output from the backend.

Sources: packages/frontend/@n8n/chat/README.md, packages/cli/src/modules/chat-hub/chat-hub-workflow.service.ts:318-340

Architecture and Integration

The Chat Hub UI operates as a client-side component that communicates with n8n via production webhooks. The architecture relies on a specialized workflow structure where the "Chat Trigger" node serves as the entry point.

Integration Methods

Users can embed the chat widget using three primary methods provided in the ChatEmbedModal:

1. CDN Embed: A simple <script> tag and stylesheet link.
2. Vue.js Integration: Using the onMounted lifecycle hook to initialize the chat.
3. React Integration: Utilizing the useEffect hook for initialization.

Sources: packages/frontend/editor-ui/src/app/components/ChatEmbedModal.vue:35-65, packages/frontend/@n8n/chat/README.md:37-80

Connection Flow

The following diagram illustrates the interaction between the UI widget and the n8n backend:

The UI sends an action parameter (e.g., sendMessage or loadPreviousSession) to the webhook endpoint to define the request context.

Sources: packages/frontend/@n8n/chat/README.md:27-33, packages/frontend/editor-ui/src/app/components/ChatEmbedModal.vue:80-87

UI Components and Messaging

The chat interface is built to handle multiple message types and assistant states, as evidenced by the Design System stories.

Message Types

The UI supports a variety of visual representations for different interaction phases:

• Text: Standard conversational messages with Markdown support.
• Code Diff: Displays changes in code suggested by the assistant.
• Tool Execution: Shows the state of background tools (Running, Completed, Error) with expandable update details.
• Block: Solutions steps or structured text blocks.
• Feedback: Quick replies and rating systems (Minimal or Regular style) for user feedback.

Sources: packages/frontend/@n8n/design-system/src/components/AskAssistantChat/AskAssistantChat.stories.ts:70-200, packages/frontend/@n8n/design-system/src/components/AskAssistantChat/AskAssistantChat.stories.ts:400-450

Component Configuration

The widget can be configured with several options to control its behavior:

Option	Type	Default	Description
mode	'window' | 'fullscreen'	'window'	Visual rendering mode.
enableStreaming	boolean	false	Enables real-time response rendering.
allowFileUploads	boolean	false	Enables the file upload interface.
chatInputKey	string	'chatInput'	JSON key for the user's message.
chatSessionKey	string	'sessionId'	JSON key for the session ID (Memory).

Sources: packages/frontend/@n8n/chat/README.md:112-160

Backend Workflow Integration

For the UI to function, the backend workflow must follow specific design patterns.

Chat Workflow Construction

The ChatHubWorkflowService programmatically builds workflows for the UI. A standard chat workflow includes:

1. Chat Trigger Node: Receives the UI request.
2. Memory Node: Tracks session state using the chatSessionKey.
3. AI Agent / Model Nodes: Processes the logic.
4. Restore/Clear Memory: Manages the injection and cleanup of chat history.

Sources: packages/cli/src/modules/chat-hub/chat-hub-workflow.service.ts:121-165, packages/frontend/editor-ui/src/experiments/readyToRunWorkflowsV2/workflows/ai-workflow-v6.ts:10-40

Attachment Policy

The UI dynamically adjusts based on the "Chat Trigger" settings. The service parses input modalities to determine if the UI should show the file upload button and which MIME types (e.g., image/*, application/pdf) are permitted.

Sources: packages/cli/src/modules/chat-hub/chat-hub-workflow.service.ts:246-275

Best Practices for Chat Hub UI

The implementation of a Chat Hub interface should follow these architectural guidelines:

• Shared Memory: If multiple triggers exist (e.g., Schedule + Chat), they must connect to the same memoryBufferWindow node to ensure the UI has context of background tasks.
• Session Key Isolation: Use sessionIdType = fromInput for the built-in Chat Trigger to ensure the UI session ID is correctly mapped to AI memory.
• Streaming Response: For an interactive UI experience, the enableStreaming option in the widget must match the Streaming response setting in the Chat Trigger node.
• Attribution: Developers should disable "Append n8n Attribution" in nodes to maintain a clean UI for external users.

Sources: packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/chatbot.ts:10-50, packages/frontend/@n8n/chat/README.md:21-25

Summary

The Chat Hub UI provides a highly customizable, embeddable interface for n8n's AI capabilities. By leveraging a specialized webhook communication layer and supporting complex message states like tool updates and streaming, it bridges the gap between automated backend workflows and user-facing applications. Integration is simplified through the Editor UI's embed modal, ensuring that developers can quickly deploy conversational agents across various web frameworks.