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 changes:

• Script URL: https://assets.ept.ai/chat/v0/ept_chat_loader.bundle.js → https://assets.ept.ai/chatbot/loader.js
• Add deployment track: data-track="stable" (new feature)
• Simplified loading (no more complex async functions)

What stays the same:

• Your accessToken configuration
• Your backend token endpoint
• All other configuration options

New options:

• Choose deployment tracks: stable, beta, lts, or pin to specific versions
• Improved performance and modern architecture

Migration Overview

The new chat widget introduces several improvements:

• 🚀 Track-Based Deployment: Choose stable, beta, lts tracks or pin to specific versions
• ⚡ Simplified Loading: No more complex async initialization required
• 🏗️ Modern Architecture: Built with TypeScript, better error handling, and modular design
• 🔒 Enhanced Security: Improved token management and WebSocket security
• 📦 Better Performance: Optimized bundle size and faster loading
• 🎨 Improved Customization: CSS custom properties for easier theming

Key Differences

1. Script Loading Method

Old Implementation:

<script>
(async function () {
  try {
    const r = await fetch('/api/ept-token', { credentials: 'include' });
    const { access_token } = await r.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('Error initializing ept AI chatbot:', error);
  }
})();
</script>

New Implementation:

<script>
  // Fetch token from your secure backend (simplified approach)
  fetch('/api/ept-token', { credentials: 'include' })
    .then(r => r.json())
    .then(data => {
      window.eptAIConfig = {
        accessToken: data.access_token,
        botName: 'Support Bot',
        introText: 'Hi! How can I help you today?'
      };
    });
</script>

<!-- Load the widget (stable track) -->
<script 
  src="https://assets.ept.ai/chatbot/loader.js" 
  data-track="stable"
  async>
</script>

2. Configuration Changes

Old Configuration:

window.eptAIConfig = {
  accessToken: 'token-from-backend',  // Required - manually fetched
  defaultQuestions: ["What are your products?"],
  fullWindow: false,
  botName: 'AI',
  introText: 'Hi, I\'m AI...',
  placeholderText: 'Type your message here...',
  darkMode: false,
  hideLogo: false
};

New Configuration (same as before):

window.eptAIConfig = {
  accessToken: 'token-from-backend',  // Same token management as before
  defaultQuestions: ["What are your products?"],
  fullWindow: false,
  botName: 'AI',
  introText: 'Hi, I\'m AI...',
  placeholderText: 'Type your message here...',
  darkMode: false,
  hideLogo: false,
  eptMetaData: {}                     // Optional metadata
};

3. Token Management

Old Approach:

• Required manual async token fetching from backend before widget initialization
• Complex script loading with error handling
• Manual token refresh implementation needed

New Approach:

• Same accessToken usage - no change to token configuration
• Simplified script loading - no need for complex async initialization
• Built-in token refresh mechanism
• Seamless token updates without WebSocket reconnection

Migration Steps

Step 1: Update Script Loading

Replace your existing script loading code with the new loader:

Before:

<script>
(async function () {
  const r = await fetch('/api/ept-token');
  const { access_token } = await r.json();
  
  window.eptAIConfig = {
    accessToken: access_token,
    // ... other config
  };

  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 secure backend (simplified approach)
  fetch('/api/ept-token')
    .then(r => r.json())
    .then(data => {
      window.eptAIConfig = {
        accessToken: data.access_token,
        // ... other config (same as before)
      };
    });
</script>

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

Step 2: Update Configuration

Your configuration stays exactly the same - no changes needed:

// Same configuration as before
window.eptAIConfig = {
  accessToken: 'token-from-backend',  // Keep using your existing backend
  botName: 'Support Bot',
  defaultQuestions: ['How can I help?']
};

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 eptClientId is correct
• Check browser console for errors
• Ensure script has data-track or data-version attribute

2. WebSocket Connection Fails

Problem: WebSocket connection immediately closes Solution:

• Verify eptClientId 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:

• If using automatic tokens: verify eptClientId is correct
• If using manual tokens: ensure your backend endpoint still works
• Check token expiration and refresh logic

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!