N8N Chat UI
Docs
Session Management

Session Management

Learn how to manage separate chat conversations for multi-page or multi-context implementations.

The n8nchatui.sessionKey field in metadata allows you to create separate chat conversations even when multiple chat widgets point to the same n8n chatbot. This solves the common issue of shared conversation history across different contexts.

The Problem This Solves

By default, chat conversations are tied to your n8n webhook URL. This means if you embed multiple chat widgets on different pages that use the same n8n chatbot, they will all share the same conversation history. Users might see messages from other pages, creating a confusing and unprofessional experience.

Example scenario without session management:

  • User visits your product page, asks "What's the price?"
  • Later visits your support page, and sees the previous product question
  • Creates confusion about context and conversation flow

How It Works

When you provide this field in your metadata's n8nchatui configuration object, the chat widget creates separate conversation storage for each unique identifier. Each session maintains its own independent chat history, stored locally in the user's browser.

<script type="module" defer>
  import Chatbot from "https://n8nchatui.com/v1/embed.js";
 
  // Product page chat
  Chatbot.init({
    n8nChatUrl: 'YOUR_N8N_CHAT_WEBHOOK_URL',
    metadata: {
      // Widget configuration
      n8nchatui: {
        sessionKey: 'product-page-electronics'
      },
      // Your business metadata
      category: 'electronics',
      pageType: 'product'
    }
  });
</script>
<script type="module" defer>
  import Chatbot from "https://n8nchatui.com/v1/embed.js";
 
  // Support page chat (same n8n webhook, different session)
  Chatbot.init({
    n8nChatUrl: 'YOUR_N8N_CHAT_WEBHOOK_URL', // Same webhook URL
    metadata: {
      // Widget configuration
      n8nchatui: {
        sessionKey: 'support-page-general'
      },
      // Your business metadata
      category: 'support',
      pageType: 'help'
    }
  });
</script>

Configuration Structure

The session management features are organized under the n8nchatui object in your metadata. This dedicated namespace:

  • Keeps widget configuration separate from your business metadata
  • Prevents naming conflicts with your custom fields
  • Allows future expansion of widget-specific features
  • Makes the code more organized and easier to maintain
metadata: {
  // Widget-specific configuration
  n8nchatui: {
    sessionKey: 'user-123-checkout'
  },
 
  // Your business metadata
  userId: '123',
  department: 'sales',
  customField: 'value'
}

Best Practices & Guidelines

✅ Recommended Session Identifiers

Use stable, descriptive identifiers that represent the conversation context:

  • product-category-electronics - Product category page
  • support-billing-issues - Specific support section
  • homepage-visitor - Homepage interactions
  • tenant-acme-corp - Multi-tenant application isolation

⚠️ Critical Things to Avoid

Never use dynamic or changing values:

  • ❌ Timestamps: session-2024-01-15-14:30:25
  • ❌ Random numbers: session-${Math.random()}
  • ❌ Date-based keys: chat-${new Date().getTime()}

Why this breaks functionality: Dynamic keys create a new conversation session every time, preventing users from continuing their previous conversations.

Other important restrictions:

  • ❌ Sensitive data (passwords, tokens, personal info)
  • ❌ Very long identifiers (recommended max: 30 characters)

Common Use Cases

  • Multi-page websites Create different chat experiences for product pages, support sections, and general inquiries while using the same underlying chatbot.

  • User-specific conversations Maintain separate chat histories for each logged-in user, even when they use the same device.

  • Multi-tenant applications Isolate conversations per organization, client, or tenant in SaaS applications.

  • A/B testing Run different chat configurations or personalities while keeping conversations separate for accurate testing.

Important Consideration

Session Management Only Affects Local Storage This feature only manages conversation history storage in the user's browser. All messages are still sent to the same n8n webhook with your metadata. Your n8n workflow receives the session identifier and can handle different contexts appropriately.

Fallback Behavior

If you don't provide this field, the chat widget automatically uses your n8n webhook URL as the session identifier.

Related Documentation

Chat Widget ControlsRender Markdown & HTML in Responses