Skip to main content

Integrating the Chatbot

This guide shows you how to integrate the ept AI chatbot into your website or application. After preparing your AI, you'll learn how to:

  1. Set up secure authentication with ept AI
  2. Choose your token management approach
  3. Initialize the chatbot in your web application
  4. Configure deployment tracks and channels

📋 Upgrading from Legacy Widget? If you're already using the old chatbot implementation, see the Migration Guide for step-by-step upgrade instructions.

Security Overview​

Security first: Never expose your client_id in the browser. This guide follows the secure pattern of fetching tokens server-side and passing only short-lived access tokens to the client.

Prerequisites​

Before integrating the chatbot, ensure you have:

  • AI Configuration Complete: Your AI must be prepared with knowledge sources and configurations (see Preparing the AI)
  • ept AI Credentials: Your ept AI application credentials:
    • client_id for your registered domain
    • Access to the ept AI API
  • Backend Infrastructure: A place to run server code (server, serverless function, etc.)
  • Channel Configuration: At least one channel configured in the ept AI system

Environment Variables​

You'll need these environment variables for the examples below:

EPT_CLIENT_ID=ABC123XYZ789ExampleClientID
EPT_ORIGIN=https://example.com

Step 1: Set Up Channel Configuration​

Before implementing the technical integration, you need to configure a channel in the ept AI system:

  1. Navigate to Configuration > Channels in the ept AI dashboard
  2. Click "Create Channel"
  3. Configure your channel:
    • Channel Name: Descriptive name (e.g., "Website Chat", "Support Widget")
    • Channel Type: Select "Websocket"
    • Knowledge Source Configuration: Choose the appropriate KSC for this channel
    • Security Settings: Configure confidentiality and access controls as needed

Step 2: Get an Access Token (Server-Side)​

Create a secure server endpoint that obtains an access token from ept AI. Choose your preferred language:

curl -H "Origin: ${EPT_ORIGIN}" \
  "https://chat.ept.ai/access_token/?client_id=${EPT_CLIENT_ID}"

Step 3: Create a Secure Token Endpoint​

Create a secure endpoint (e.g., /api/ept-token) that your frontend can call to get access tokens. This keeps your ept AI credentials secure on the server.

import express from 'express';
import { request } from 'undici';

const app = express();

app.get('/api/ept-token', async (req, res) => {
  const url = `https://chat.ept.ai/access_token/?client_id=${process.env.EPT_CLIENT_ID}`;
  const r = await request(url, {
    method: 'GET',
    headers: {
      'Origin': process.env.EPT_ORIGIN
    }
  });
  const json = await r.body.json();
  res.json({ access_token: json.access_token });
});

app.listen(3000);

Step 4: Initialize the Chatbot in Your Application​

Now you can load the ept AI chat widget in your web application using your secure token from the backend.

Basic Integration​

<script>
  // Fetch token from your secure backend
  fetch('/api/ept-token', { credentials: 'include' })
    .then(r => r.json())
    .then(data => {
      window.eptAIConfig = {
        accessToken: data.access_token,
        botName: 'Support Bot',
        defaultQuestions: ["What are your products?"]
      };
    })
    .catch(error => {
      console.error('Error fetching access token:', error);
    });
</script>

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

Step 5: Choose Deployment Track (New Release System)​

🚀 New Feature: The widget now supports deployment tracks for better version management and stability control.

Select the appropriate deployment track for your needs:

TrackUse CaseUpdate FrequencyStabilityBest For
stableProduction websitesMonthlyHigh - thoroughly testedMost websites
betaStaging/testingWeeklyMedium - new featuresEarly adopters
ltsEnterprise/criticalQuarterlyHighest - minimal changesEnterprise apps
<!-- 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>

<!-- 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.

Integration with Modern Frameworks​

For React, Vue, or other modern frameworks, you can wrap this logic in a component or hook:

React Example​

import { useEffect } from 'react';

function EptAIChatbot() {
  useEffect(() => {
    // Fetch token from your secure backend
    fetch('/api/ept-token', { credentials: 'include' })
      .then(r => r.json())
      .then(data => {
        window.eptAIConfig = {
          accessToken: data.access_token,
          botName: 'Support Bot',
          defaultQuestions: ["What are your products?"]
        };
        
        // Load the widget with deployment track
        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('Error fetching access token:', error);
      });
  }, []);
  
  return null;
}

export default EptAIChatbot;

Dynamic Token Updates​

For seamless user experience during long sessions, you can update the access token dynamically without reloading the chatbot:

// Update the token when needed (e.g., before expiry)
const refreshToken = async () => {
  try {
    const response = await fetch('/api/ept-token', { credentials: 'include' });
    const { access_token } = await response.json();
    
    // Update the token seamlessly
    window.eptAIConfig.accessToken = access_token;
    console.log('Access token refreshed successfully');
  } catch (error) {
    console.error('Failed to refresh access token:', error);
  }
};

// Example: Refresh token every 30 minutes
setInterval(refreshToken, 30 * 60 * 1000);

This approach maintains the WebSocket connection and prevents authentication interruptions during active conversations.

That's it! The loader will establish the WebSocket connection using your secure token and display the chatbot interface.

Troubleshooting​

Authentication Issues​

  • 401/403 Errors: Ensure your client_id is correct and the Origin header matches your registered domain
  • Token Expiry: If sessions run long, update the token seamlessly using window.eptAIConfig.accessToken = "new-token" (see Dynamic Token Updates section above)
  • Credential Issues: Verify your ept AI client_id is correct and active, and ensure the Origin header matches your domain

Integration Problems​

  • CORS Errors: Configure CORS on your /api/ept-token endpoint to allow your site origin. Never expose your ept AI credentials to public clients
  • Mixed Content: Ensure your page is served over HTTPS in production
  • Loading Failures: Check browser console for script loading errors and network connectivity

Performance Issues​

  • Slow Loading: Consider loading the chatbot script after the main page content
  • Token Refresh: Implement token refresh logic for long-running sessions

Quick Reference​

curl -H "Origin: https://example.com" \
  "https://chat.ept.ai/access_token/?client_id=ABC123XYZ789ExampleClientID"

Next Steps​

After successfully integrating the chatbot:

  1. Migrate to New Chat Widget - Upgrade to the latest version with improved performance and features
  2. Configure the Design - Customize the visual appearance and user experience
  3. Context-Aware Chat - Make your chatbot intelligent about user context and page content
  4. Set up Continuous Improvement - Monitor performance and optimize responses
  5. Explore Advanced Integrations - Connect with CRM, support systems, and other platforms

Configuration Parameters​

The window.eptAIConfig object supports the following configuration parameters:

Required Parameters​

ParameterTypeDescription
accessTokenstringRequired. Authentication token obtained from your secure backend endpoint. This token provides access to the ept AI services.

Appearance & Behavior​

ParameterTypeDefaultDescription
fullWindowbooleanfalseWhether the chatbot takes up the full browser window or appears as a widget. Set to true for full-screen chat experience.
inlinebooleanfalseWhen true, the chatbot embeds inline instead of appearing as an overlay widget.
parentDivstring | ElementnullElement ID (without #, e.g., 'chat-container') or DOM element where the chatbot should be embedded.
darkModebooleanfalseEnable dark theme for the chatbot interface.
hideLogobooleanfalseHide the ept AI branding/logo from the chatbot interface.

Content & Messaging​

ParameterTypeDefaultDescription
botNamestring'AI'Display name for the bot in the chat interface.
botImagestring | nullnullURL to a custom avatar image for the bot. If not provided, uses the default bot avatar.
introTextstring'Hi, I'm AI...'Welcome message displayed when the chat interface first loads.
placeholderTextstring'Type your message here...'Placeholder text shown in the message input field.
loadingTextstring''Text displayed while the AI is processing a response. Leave empty for no loading message.
networkErrorTextstring'Connection Lost...'Error message displayed when network connectivity issues occur.
defaultQuestionsstring[][]Array of suggested questions to display to users, helping them get started with the chatbot.

Advanced Options​

ParameterTypeDefaultDescription
eptClientIdstring''Optional client ID for specific channel selection. Used for advanced channel routing scenarios.
eptMetaDataobject | nullnullOptional metadata object for advanced use cases and custom integrations.

Usage Examples​

Basic Widget Configuration​

window.eptAIConfig = {
  accessToken: 'your-secure-token',
  botName: 'Support Assistant',
  defaultQuestions: ['How can I reset my password?', 'What are your business hours?'],
  darkMode: true
};

Inline Embedded Chat​

window.eptAIConfig = {
  accessToken: 'your-secure-token',
  inline: true,
  parentDiv: 'chat-container', // Specify container ID for embedding
  fullWindow: false,
  botName: 'Help Bot'
};

Full-Screen Experience​

window.eptAIConfig = {
  accessToken: 'your-secure-token',
  fullWindow: true,
  introText: 'Welcome to our AI-powered support center!',
  hideLogo: true
};