Skip to main content
Chatbot Implementation Guide

Integrating the Chatbot

Embedding the ept AI chat widget on your website with authentication and configuration options.

Integrating the Chatbot

📋 Select Chatbot Version:
Latest (v2.0)RECOMMENDED
Version 2.0STABLE
Version 1.0.0DEPRECATED
💡 Tip: Use the latest version for new integrations. Version-specific docs help with maintenance and troubleshooting.

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. Configure your channel in the ept AI dashboard
  2. Create a secure backend endpoint for token authentication
  3. Initialize and configure the chatbot in your web application

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
    • Allowed Domain Origin: Add your website domain(s) (e.g., https://example.com) - this restricts chatbot access to authorized domains only
    • Security Settings: Configure confidentiality and access controls as needed

Step 2: Create a Secure Token Endpoint​

To keep your credentials secure, you need to create a backend endpoint that your frontend can call to obtain access tokens. This endpoint will:

  1. Keep your client_id secure on the server (never exposed to the browser)
  2. Request access tokens from the ept AI authentication API
  3. Return tokens to your frontend for chatbot initialization

How it works:

  • Your backend calls https://chat.ept.ai/access_token/?client_id={YOUR_CLIENT_ID} with an Origin header
  • The ept AI API validates your credentials and returns a short-lived access token
  • Your backend forwards this token to your frontend

Create an endpoint at /api/ept-token (or your preferred path) using your backend framework:

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);
Security Best Practices
  • Never expose your client_id in frontend code - always keep it on the server
  • Add rate limiting to your token endpoint to prevent abuse
  • Validate requests to ensure they're coming from your own frontend (e.g., check referer, use CORS)

Step 3: Initialize the Chatbot​

Now that you have a secure token endpoint, you can fetch tokens from your backend and initialize the chatbot widget in your web application.

Basic Integration​

<script>
  // Configure the chatbot (token fetched from your backend endpoint)
  window.eptAIConfig = {
    accessToken: 'your-access-token-from-backend',
    botName: 'Support Bot',
    defaultQuestions: ["What are your products?"]
  };
</script>

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

Version Targeting​

By Major.Minor Version​

<!-- Latest 2.x version (recommended) -->
<script src="https://assets.ept.ai/chatbot/loader.js" data-version="2.0" async></script>

By Track​

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

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

By Specific Patch​

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

Configuration Parameters​

The window.eptAIConfig object supports the following configuration parameters:

Required Parameters​

ParameterTypeDescription
accessTokenstringRequired. Authentication token obtained from your secure backend endpoint.

Appearance & Behavior​

ParameterTypeDefaultDescription
botNamestring'AI'Display name for the bot
defaultQuestionsstring[][]Suggested questions to display
darkModebooleanfalseEnable dark theme
hideLogobooleanfalseHide ept AI branding
fullWindowbooleanfalseFull browser window mode
inlinebooleanfalseInline embedding mode
parentDivstringnullContainer element for inline mode
botImagestringdefaultCustom bot avatar image URL
userImagestringdefaultCustom user avatar image URL
headerIconstring'💬'Custom header icon
headerChatNamestring'Chat'Custom header chat name
showMaximizeButtonbooleantrueShow/hide maximize button
initiallyHiddenbooleanfalseStart widget hidden by default
brandingstring''Customer-specific branding (alphanumeric and hyphens)

Text & Messages​

ParameterTypeDefaultDescription
introTextstring"Hi, I'm {botName}..."Welcome message
placeholderTextstring'Type your message here...'Input placeholder
loadingTextstring''Fallback loading text (server loading messages are localized separately)
networkErrorTextstring'Connection Lost...'Network error message
disclaimerTextstring''Custom disclaimer text
disconnectRetryMessagestring'Connection lost. Please try again.'Message shown when a stream is interrupted
retryLastMessageButtonTextstring'Retry last message'Retry button label after an interrupted stream

Advanced Features​

ParameterTypeDefaultDescription
enableFileUploadbooleanfalseEnable file upload functionality
enableChatPersistencebooleantruePersist conversation history in localStorage (24 hours)
advancedWelcomeTextobjectnullWelcome message with icon, title, and description
eptMetaDataobjectnullMetadata sent with each message (language, page context, and other fields)

Advanced Welcome Text Object​

advancedWelcomeText: {
  icon: "👋",
  title: "Welcome to Support",
  description: "How can we help you today?"
}

Localization​

Loading status during AI generation and the rest of the widget chrome use two different mechanisms. Do not mix them up.

Server-Side Loading Messages​

Loading messages shown while the AI is generating a response are sent by the server. To localize them, set the language on eptMetaData:

window.eptAIConfig = {
  accessToken: 'your-token',
  eptMetaData: {
    knowledge_configuration: {
      language: 'ko'  // ISO 639-1 language code
    }
  }
};

Supported Languages:

LanguageISO 639-1 Code
Englishen (default)
Germande
Frenchfr
Chinesezh
Japaneseja
Koreanko

This is not the same as eptMetaData.locale used for context-aware chat. knowledge_configuration.language controls server loading-message copy only.

Client-Side UI Strings​

All other user-facing strings (tooltips, error messages, connection status, refresh banners) are not auto-translated from knowledge_configuration.language. Set them on window.eptAIConfig for the language of your page:

ParameterDefaultDescription
tooltipCopyText'Copy'Copy button tooltip
tooltipLikeText'Like'Like button tooltip
tooltipDislikeText'Dislike'Dislike button tooltip
connectionStatusConnecting'Connecting...'Connection status label
connectionStatusConnected'Connected'Connection status label
connectionStatusDisconnected'Disconnected'Connection status label
connectionStatusError'Error'Connection status label
errorNoAccessToken'Authentication required. Please refresh the page.'Error message
errorConnectionLost'Connection lost. Your message could not be sent.'Error message
errorConnectionFailed'Unable to connect. Please check your internet connection and refresh the page.'Error message
errorSessionExpired'Session expired. Please refresh the page to continue.'Error message
errorReconnectionTimeout'Connection timed out. Please try again.'Error message
errorInvalidInput'Invalid input. Please check your message and try again.'Error message
errorGeneratorFailed'Something went wrong while generating the response. Please try again.'Error message
errorFeedbackFailed'Failed to send feedback. Please try again.'Error message
errorConfigurationFailed'Configuration error. Please contact support.'Error message
errorGeneric'An unexpected error occurred. Please try again.'Error message
refreshButtonText'Refresh Page'Refresh banner button text
refreshSessionExpiredText'Your session has expired. Please refresh the page to get a new session.'Refresh banner message
refreshAuthFailedText'Authentication failed. Please refresh the page to reconnect.'Refresh banner message
refreshTimeoutText'The connection timed out. Please check your internet and refresh the page.'Refresh banner message
refreshDefaultText'Unable to establish connection after multiple attempts. Please check your internet connection and refresh the page.'Refresh banner message
connectingTitle'Connecting...'Connecting overlay title

Token Management​

Important: Access tokens expire after 24 hours. The ept AI system returns the same access token for all requests until it expires.

Decoding the Access Token​

The access token is a JWT (JSON Web Token) that contains information including its expiration time. You can decode it to check when it expires and implement intelligent caching. To test it, you can paste the access token in https://www.jwt.io/ and see the content.

Server-Side Token Caching​

To optimize performance and reduce unnecessary API calls, we recommend caching the access token on your server. This eliminates the need to request a new token from ept AI for every user interaction.

// Refresh token seamlessly
async function refreshToken() {
  const response = await fetch('/api/ept-token');
  const { access_token } = await response.json();
  window.eptAIConfig.accessToken = access_token;
}

// Auto-refresh every 23 hours
setInterval(refreshToken, 23 * 60 * 60 * 1000);

Widget Control​

Show/hide the widget programmatically:

window.eptAIConfig.show();
window.eptAIConfig.hide();

window.eptAIConfig.setDarkMode(true);
window.eptAIConfig.setDarkMode(false);

Add ?chatbot_state=open to any page URL to auto-open the widget, including when initiallyHidden is true.

Version-Specific Features & Release Notes​

For detailed feature lists, configuration options, and release notes:

Migration​

If you're upgrading from version 1.0.x, see our Migration Guide for step-by-step instructions.

Important Considerations​

Conversation Retention​

By default (enableChatPersistence: true), conversation history is saved in the browser for 24 hours and restored when the user returns. Set enableChatPersistence: false to start a new chat on each page load.

Next Steps​

After successfully integrating the chatbot:

  1. Configure the Design - Customize the visual appearance
  2. Context-Aware Chat - Make your chatbot intelligent about user context
  3. Set up Continuous Improvement - Monitor performance and optimize responses
  4. Explore Advanced Integrations - Connect with CRM, support systems, and other platforms

📧 Stay Updated on Chat Widget Releases​

Get notified when we release new versions of the ept AI chat widget with new features, improvements, and bug fixes.

What you'll receive:

  • ✨ Early access to new features
  • 🐛 Important bug fixes and security updates
  • 📚 Detailed release notes and migration guides
  • 🎯 No spam - only version updates

📧 Get Release Notifications

Stay up to date with the latest chat widget releases. Subscribe to receive email notifications when new versions are available with new features, improvements, and bug fixes.

  • ✨ Early access to new features
  • 🐛 Important bug fixes and security updates
  • 📚 Detailed release notes and migration guides
  • 🎯 No spam - only version updates