Documentation - Crescent AI Customer Service

Requirements

Node.js

18.0 or above

MySQL

5.7 or above

Alibaba Cloud Account

Bailian + Machine Translation

Installation

1

Step 1: Install dependencies

Double-click to run 安装全部依赖.bat and wait for all dependencies to finish installing.

安装全部依赖.bat

2

Step 2: Start the project

Double-click to run 启动项目.bat to start the development server.

启动项目.bat
# http://127.0.0.1:3000

3

Step 3: Complete the setup wizard

Open http://127.0.0.1:3000 in your browser. The system will guide you through database setup and admin account creation.

The setup wizard automatically runs SQL table creation, creates the admin account, and writes config files — fully visual, no manual database work needed.

Database Structure

The system uses 7 tables, all created automatically by the setup wizard:

Table	Description
`users`	Admin and agent accounts, supporting admin and agent roles
`clients`	Site configuration — one record per integrated website, storing Alibaba Cloud Agent IDs and more
`chat_sessions`	Visitor sessions — records IP, device, referrer, and current service mode
`chat_messages`	Chat messages — all message content and sender type (visitor / agent / AI)
`knowledge_base`	Knowledge base Q&A pairs with category, keywords, and priority
`knowledge_files`	Files uploaded to Alibaba Cloud knowledge base and their sync status
`system_config`	Global system config including Alibaba Cloud API keys and translation keys

Alibaba Cloud Setup

The system requires two Alibaba Cloud services: Bailian (AI replies) and Machine Translation. Log into the admin panel, go to System Settings, and fill in the following:

ali_api_key Bailian API Key

Created in the Alibaba Cloud Bailian console, used to call the Q&A Agent.

ali_workspace_id Workspace ID

Visible in the top-right of the Bailian console, formatted like ws-xxxxxxxx.

ali_translate_key_id Translation AccessKey ID

Created in the Alibaba Cloud RAM console after enabling Machine Translation.

ali_translate_key Translation AccessKey Secret

Paired with the AccessKey ID — save it at creation time, it cannot be viewed again.

About Agent IDs：Each integrated site needs its own knowledge base and Agent created in Alibaba Cloud Bailian. After creation, enter the Agent ID and knowledge base ID in the Site Management section of the admin panel.

Website Integration

Once installed, embed the chat window into your website so visitors can start chatting without leaving the page.

Step 1: Create a site

Log into the admin panel, go to Site Management, and create a new site with your website domain. The system generates a unique client code.

Step 2: Embed the code

Paste the snippet below before the tag in your website HTML. Replace YOUR_LOCALE with a language code (e.g. en) and YOUR_CLIENT_CODE with your site's client code:

<script>
  (function() {
    var btn = document.createElement('a');
    btn.href = 'https://your-domain.com/YOUR_LOCALE/chat?client=YOUR_CLIENT_CODE';
    btn.target = '_blank';
    btn.rel = 'noopener noreferrer';
    btn.title = '联系客服';
    btn.style.cssText = 'position:fixed;bottom:24px;right:24px;width:56px;height:56px;border-radius:50%;background:#2563eb;display:flex;align-items:center;justify-content:center;box-shadow:0 4px 16px rgba(37,99,235,.45);z-index:9999;transition:transform .15s';
    btn.innerHTML = '<svg width="28" height="28" viewBox="0 0 24 24" fill="none" stroke="#fff" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"/></svg>';
    btn.onmouseover = function(){ btn.style.transform = 'scale(1.1)'; };
    btn.onmouseout  = function(){ btn.style.transform = 'scale(1)'; };
    document.body.appendChild(btn);
  })();
</script>

Step 3: Set up the knowledge base

Create a knowledge base in Alibaba Cloud Bailian, upload your business documents, and create a Q&A Agent. Then enter the Agent ID in Site Management — the AI will automatically reply to visitor questions.