Migrating to the New Chat Widget

This guide helps you migrate from the legacy ept AI chatbot to the new, improved chat widget. The new widget offers better performance, enhanced security, modern architecture, and improved customization options.

🚀 Quick Migration Summary

What's new in 2.0:

• 🎨 Modern UI Design - Completely redesigned interface
• 🚀 Version Control - Choose stable, beta tracks or specific versions (e.g., 2.0.5)
• 📁 File Upload Support - Upload documents and images
• ⚙️ Enhanced Configuration - New customization options

What stays the same:

• Your accessToken configuration and backend setup
• All existing configuration parameters
• Same integration process

Migration Overview

Migrating to version 2.0 brings significant improvements:

• 🎨 Modern UI Design: Completely redesigned chat interface
• 🚀 Version Control: Track-based deployment (stable, beta) and specific version targeting
• 📁 File Upload: Upload documents and images in chat
• ⚙️ Enhanced Features: Advanced welcome messages, custom headers, show/hide controls
• 🏗️ Modern Architecture: Built with TypeScript, better error handling
• 📦 Better Performance: Optimized bundle size and faster loading

Key Differences

1. Modern UI Design

Version 1.0.0:

• Basic chat interface
• Limited customization options
• Standard message bubbles

Version 2.0.5:

• 🎨 Modern UI Design - Completely redesigned interface
• 🎨 Enhanced Visual Hierarchy - Better message organization
• 🎨 Smooth Animations - Modern transitions and micro-interactions
• 🎨 Updated Typography - Modern font styling

2. Version Control System

Version 1.0.0:

<!-- Fixed script URL -->
<script src="https://assets.ept.ai/chat/v0/ept_chat_loader.bundle.js"></script>

Version 2.0.5:

<!-- Track-based deployment -->
<script src="https://assets.ept.ai/chatbot/loader.js" data-track="stable" async></script>

<!-- Specific version targeting -->
<script src="https://assets.ept.ai/chatbot/loader.js" data-version="2.0.5" async></script>

3. New Features in 2.0.4

Enhanced Configuration:

window.eptAIConfig = {
  accessToken: 'your-token',
  // New 2.0.0 features
  headerIcon: '🤖',
  headerChatName: 'AI Support',
  enableFileUpload: true,
  advancedWelcomeText: {
    icon: '👋',
    title: 'Welcome to Support',
    description: 'How can we help you today?'
  }
};

Widget Control:

// Show/hide widget programmatically
window.eptAIConfig.show();
window.eptAIConfig.hide();

Migration Steps

Step 1: Update Script URL

Simply change your script source to the new loader:

Before:

<script src="https://assets.ept.ai/chat/v0/ept_chat_loader.bundle.js"></script>

After:

<script src="https://assets.ept.ai/chatbot/loader.js" data-track="stable" async></script>

Step 2: Choose Version Control Strategy

Select how you want to manage versions:

Option A: Track-Based (Recommended)

<!-- Stable track - production ready -->
<script src="https://assets.ept.ai/chatbot/loader.js" data-track="stable" async></script>

<!-- Beta track - early access to new features -->
<script src="https://assets.ept.ai/chatbot/loader.js" data-track="beta" async></script>

Option B: Specific Version

<!-- Pin to major version -->
<script src="https://assets.ept.ai/chatbot/loader.js" data-version="2.0" async></script>

<!-- Pin to exact patch -->
<script src="https://assets.ept.ai/chatbot/loader.js" data-version="2.0.5" async></script>

Step 3: Add New 2.0.0 Features (Optional)

Enhance your configuration with new features:

window.eptAIConfig = {
  accessToken: 'your-token',
  botName: 'Support Bot',
  // Keep existing config, add new 2.0.0 features
  headerIcon: '🤖',
  headerChatName: 'AI Support',
  enableFileUpload: true,
  advancedWelcomeText: {
    icon: '👋',
    title: 'Welcome to Support',
    description: 'How can we help you today?'
  }
};

Step 3: Choose Deployment Track (IMPORTANT)

🎯 This is a key new feature! Select the appropriate deployment strategy:

Track-Based Deployment (Recommended)

Track	Use Case	Update Frequency	Stability
stable	Production websites	Monthly	High - thoroughly tested
beta	Staging/testing	Weekly	Medium - new features
lts	Enterprise/critical	Quarterly	Highest - minimal changes

<!-- Production: Most stable, recommended for live sites -->
<script 
  src="https://assets.ept.ai/chatbot/loader.js" 
  data-track="stable"
  async>
</script>

<!-- Beta: Early access to new features -->
<script 
  src="https://assets.ept.ai/chatbot/loader.js" 
  data-track="beta"
  async>
</script>

<!-- LTS: Long-term support, minimal updates -->
<script 
  src="https://assets.ept.ai/chatbot/loader.js" 
  data-track="lts"
  async>
</script>

Version Pinning (Advanced)

Pin to a specific version for complete control:

<!-- Pin to specific version (no automatic updates) -->
<script 
  src="https://assets.ept.ai/chatbot/loader.js" 
  data-version="1.0.2"
  async>
</script>

⚠️ Important: Choose either data-track OR data-version, not both.

Step 4: Update Customization (Optional)

The new widget supports CSS custom properties for easier theming:

Old Approach:

/* High specificity selectors needed */
html body div#eptai-chat-container {
  background-color: #your-color;
}

New Approach:

/* Simple CSS variables */
:root {
  --ept-custom-primary-color: #your-brand-color;
  --ept-custom-background-color: #your-bg-color;
  --ept-custom-font-family: 'Your Font', sans-serif;
  --ept-custom-border-radius: 12px;
}

Step 5: Remove Backend Token Endpoint (Optional)

If you choose to use the new automatic token management, you can remove your backend token endpoint:

1. Keep the endpoint if you need custom authentication logic
2. Remove the endpoint if you're using standard ept AI authentication

Migration Examples

Example 1: Basic Migration

Before:

<script>
(async function () {
  const r = await fetch('/api/ept-token');
  const { access_token } = await r.json();
  
  window.eptAIConfig = {
    accessToken: access_token,
    botName: 'Support Bot',
    defaultQuestions: ['How can I help?']
  };

  const script = document.createElement('script');
  script.src = 'https://assets.ept.ai/chat/v0/ept_chat_loader.bundle.js';
  script.async = true;
  document.body.appendChild(script);
})();
</script>

After:

<script>
  // Fetch token from your existing backend (same as before)
  fetch('/api/ept-token')
    .then(r => r.json())
    .then(data => {
      window.eptAIConfig = {
        accessToken: data.access_token,  // Same token usage
        botName: 'Support Bot',
        defaultQuestions: ['How can I help?']
      };
    });
</script>

<script 
  src="https://assets.ept.ai/chatbot/loader.js" 
  data-track="stable"
  async>
</script>

Example 2: React Component Migration

Before:

import { useEffect } from 'react';

function EptAIChatbot() {
  useEffect(() => {
    const initializeChatbot = async () => {
      try {
        const response = await fetch('/api/ept-token');
        const { access_token } = await response.json();
        
        window.eptAIConfig = {
          accessToken: access_token,
          defaultQuestions: ["What are your products?"]
        };
        
        const script = document.createElement('script');
        script.src = 'https://assets.ept.ai/chat/v0/ept_chat_loader.bundle.js';
        script.async = true;
        document.body.appendChild(script);
      } catch (error) {
        console.error('Failed to initialize ept AI chatbot:', error);
      }
    };
    
    initializeChatbot();
  }, []);
  
  return null;
}

After:

import { useEffect } from 'react';

function EptAIChatbot() {
  useEffect(() => {
    const initializeChatbot = async () => {
      try {
        // Fetch token from your existing backend (same as before)
        const response = await fetch('/api/ept-token');
        const { access_token } = await response.json();
        
        // Set configuration with same token usage
        window.eptAIConfig = {
          accessToken: access_token,  // Same as before
          defaultQuestions: ["What are your products?"]
        };
        
        // Load the new widget
        const script = document.createElement('script');
        script.src = 'https://assets.ept.ai/chatbot/loader.js';
        script.setAttribute('data-track', 'stable');
        script.async = true;
        document.body.appendChild(script);
      } catch (error) {
        console.error('Failed to initialize ept AI chatbot:', error);
      }
    };
    
    initializeChatbot();
  }, []);
  
  return null;
}

Example 3: Simplified Migration (Minimal Changes)

The key benefit is that you can keep your exact same token management:

<script>
(async function () {
  try {
    // Keep your existing token fetching logic exactly the same
    const r = await fetch('/api/ept-token');
    const { access_token } = await r.json();
    
    // Same configuration as before
    window.eptAIConfig = {
      accessToken: access_token,  // No changes needed
      botName: 'Support Bot',
      defaultQuestions: ['How can I help?']
    };
  } catch (error) {
    console.error('Error initializing ept AI chatbot:', error);
  }
})();
</script>

<!-- Only change: new script source and data-track -->
<script 
  src="https://assets.ept.ai/chatbot/loader.js" 
  data-track="stable"
  async>
</script>

Testing Your Migration

1. Verify Widget Loading

Check the browser console for successful loading:

[EPT Chat] Loading manifest from: https://assets.ept.ai/chatbot/manifests/tracks/stable/manifest.json
[EPT Chat] Widget loaded successfully

2. Test WebSocket Connection

The new widget provides better WebSocket monitoring:

// Check connection status
console.log('Connection status:', window.EPTChatApp?.stateManager?.getConnectionStatus());

3. Verify Token Management

Test automatic token refresh (if using eptClientId only):

// The widget will automatically refresh tokens as needed
// Check console for token refresh messages

Troubleshooting

Common Migration Issues

1. Widget Not Loading

Problem: Widget doesn't appear after migration Solution:

• Verify your accessToken is valid and not expired (24-hour limit)
• Check browser console for errors
• Ensure script has data-track or data-version attribute
• Confirm your backend /api/ept-token endpoint is working
• Test your token endpoint directly: curl -H "Origin: your-domain" "your-site/api/ept-token"

2. WebSocket Connection Fails

Problem: WebSocket connection immediately closes Solution:

• Verify your accessToken is valid and matches your registered domain
• Check that you're not mixing old and new implementations
• Remove any old script tags

3. Token Issues

Problem: Authentication errors Solution:

• Verify your accessToken is valid and not expired (24-hour limit)
• Ensure your backend /api/ept-token endpoint is working correctly
• Check token expiration and refresh logic
• Confirm your client_id matches your registered domain

4. Styling Issues

Problem: Widget appearance changed after migration Solution:

• Update CSS to use new custom properties
• Remove old high-specificity selectors
• Test across different browsers

Debug Commands

// Check widget state
window.debugEPTChat?.();

// Check configuration
console.log('Config:', window.eptAIConfig);

// Check WebSocket URL format
// Should not contain client_key parameter

Rollback Plan

If you need to rollback to the old implementation:

1. Revert script source:

   <script src="https://assets.ept.ai/chat/v0/ept_chat_loader.bundle.js"></script>

2. Restore old configuration:

   window.eptAIConfig = {
     accessToken: 'token-from-backend',  // Required
     // ... rest of old config
   };

3. Re-implement token fetching logic

Benefits of Migration

After migrating to the new widget, you'll benefit from:

• ✅ Automatic Token Management: No more manual token refresh logic
• ✅ Better Performance: Faster loading and optimized bundle size
• ✅ Enhanced Security: Improved WebSocket security and token handling
• ✅ Track-Based Deployment: Choose stability level that fits your needs
• ✅ Easier Customization: CSS custom properties for theming
• ✅ Better Error Handling: More robust error recovery
• ✅ Modern Architecture: TypeScript, modular design, comprehensive testing

Next Steps

After successful migration:

1. Configure the Design - Customize the visual appearance using new CSS variables
2. Context-Aware Chat - Leverage enhanced context features
3. Set up Continuous Improvement - Monitor performance with new analytics
4. Explore Advanced Integrations - Use new integration capabilities

Support

If you encounter issues during migration:

1. Check this migration guide
2. Review the troubleshooting section
3. Test with minimal configuration first
4. Contact support with specific error messages and configuration details

---

Ready to migrate? Start with the basic migration example and test in a development environment first!