Agent JS SDK 概述
概述
AICC Agent JavaScript SDK (v2.7.3) 是面向座席端的實時通信 SDK，提供座席與呼叫中心系統之間的即時通信能力。SDK 基於 WebSocket 協議，支援座席登錄、通話控制、監督功能等全面的呼叫中心業務。
SDK 特點
- 實時通信：基於 WebSocket 的雙向實時通信
- WebRTC 支持：集成 Janus Gateway 用於音視頻通信
- 完整的 API：涵蓋座席生命週期、通話控制、監督等功能
- 事件驅動：基於事件的異步操作模式
- 易於集成：簡單的初始化和使用方式
版本信息
- SDK 版本：v2.7.3
- 發佈日期：2026-02-12
- 支持的瀏覽器：Chrome 60+、Firefox 55+、Safari 11+、Edge 15+
工作原理
整體架構
┌─────────────┐
│ Web 應用 │
│ (HTML/JS) │
└──────┬──────┘
│
│ SDK API
│
┌──────▼──────────────────┐
│ AICC Agent SDK (JS) │
│ - 事件管理 │
│ - 通話控制 │
│ - 狀態管理 │
└──────┬────────┬──────────┘
│ │
WebSocket WebRTC
│ │
┌──────▼────────▼──────────┐
│ AICC Server │
│ - 會話管理 │
│ - 路由和轉接 │
│ - CDR 記錄 │
└──────┬────────┬──────────┘
│ │
│ Janus Gateway
│ (WebRTC SFU)
│ │
PBX/SIP Real-time Media通信協議
WebSocket 連接
SDK 使用 WebSocket 與 AICC Server 建立持久連接：
ws://your-server-ip:8080/ws
或
wss://your-server-ip:8443/ws (安全連接)建議使用 WSS (WebSocket Secure) 以確保傳輸安全。
JSON 消息格式
所有通信使用 JSON 格式，包含以下基本結構：
json
{
"type": "message_type",
"id": "message_id",
"data": {
"key1": "value1",
"key2": "value2"
}
}消息類型
| 類型 | 方向 | 說明 |
|---|---|---|
login | C→S | 座席登錄請求 |
loginResponse | S→C | 登錄回應 |
setReady | C→S | 設置座席為就緒狀態 |
setNotReady | C→S | 設置座席為非就緒狀態 |
statusChanged | S→C | 座席狀態變更通知 |
incomingCall | S→C | 來電通知 |
answerCall | C→S | 接聽通話請求 |
makeCall | C→S | 撥號請求 |
callStateChanged | S→C | 通話狀態變更通知 |
holdCall | C→S | 保持通話請求 |
resumeCall | C→S | 恢復通話請求 |
transferCall | C→S | 轉接通話請求 |
consultCall | C→S | 諮詢通話請求 |
conferenceCall | C→S | 會議通話請求 |
hangupCall | C→S | 掛斷通話請求 |
logout | C→S | 座席登出請求 |
座席生命週期
狀態轉移圖
┌─────────┐
│ 未登錄 │
│ OFFLINE │
└────┬────┘
│ login()
▼
┌─────────┐
│ 已登錄 │
│ LOGGEDIN │
└────┬────┘
│ setReady()
▼
┌─────────┐ onCall() ┌──────────┐
│ 就緒中 │◄────────────────┤ 通話中 │
│ READY │ │ TALKING │
└────┬────┘ └──────────┘
│ ▲
│ setNotReady() │
▼ answerCall()
┌─────────┐ │
│非就緒中 │────────────────────┘
│NOT_READY │ setReady()
└────┬────┘
│ logout()
▼
┌─────────┐
│ 已登出 │
│ OFFLINE │
└─────────┘狀態說明
| 狀態 | 代碼 | 說明 |
|---|---|---|
| OFFLINE | 0 | 未登錄或已登出 |
| LOGGEDIN | 1 | 已登錄，尚未設置就緒 |
| READY | 2 | 就緒，可接收來電 |
| NOT_READY | 3 | 非就緒，不接收來電 |
| TALKING | 4 | 通話中 |
| HOLDING | 5 | 通話保持中 |
| TRANSFER | 6 | 轉接中 |
| CONSULT | 7 | 諮詢中 |
| CONFERENCE | 8 | 會議中 |
來電處理時序圖
座席 SDK AICC Server PBX
│ │ │ │
│ │◄───────────────┼────────────────│ 來電進入
│ │ │ │
│ incomingCall│ │ │
│◄────────────┤ │ │
│ │ │ │
│ answerCall()│ │ │
├────────────►│ │ │
│ │────────────────► │
│ │ setReady()回應 │ │
│ │◄──────────────── │
│ │ │────────────────►
│ │ │ 連接音視頻 │
│ │◄─┐ │◄────────────────
│ │ └─WebRTC──────┘
│ onCall() │
│◄────────────┤
│ │
│ 通話中... │
│ │
│ hangupCall()│
├────────────►│
│ │────────────────►
│ │ hangup │
│ │◄────────────────
│ │
│ onCallEnded │
│◄────────────┤初始化流程
步驟 1：加載 SDK
html
<script src="https://your-server-ip/static/uni4cc.js"></script>步驟 2：初始化 SDK
javascript
const sdk = uni4cc.init({
server: 'wss://your-server-ip:8443',
agentId: 'agent_001',
agentName: '王小明',
agentTeam: '業務部',
janus: {
server: 'wss://your-server-ip:8443/janus'
}
});步驟 3：監聽事件
javascript
sdk.on('statusChanged', (event) => {
console.log('座席狀態變更:', event.status);
});
sdk.on('incomingCall', (event) => {
console.log('來電:', event.from);
});步驟 4：登錄
javascript
sdk.login('password123').then(() => {
console.log('登錄成功');
}).catch((error) => {
console.error('登錄失敗:', error);
});常見場景示例
場景 1：座席登錄並設置就緒
javascript
// 登錄
await sdk.login('password123');
// 設置就緒
await sdk.setReady();
// 監聽來電
sdk.on('incomingCall', async (event) => {
console.log('來自', event.from, '的來電');
// 自動接聽
await sdk.answerCall();
});場景 2：主動撥號
javascript
// 撥號
await sdk.makeCall({
to: '0912345678',
displayName: '李美香'
});
// 監聽通話狀態
sdk.on('callStateChanged', (event) => {
if (event.state === 'TALKING') {
console.log('通話已連接');
}
});場景 3：通話中轉接
javascript
// 轉接給其他座席
await sdk.transferCall({
to: 'agent_002',
displayName: '張三'
});WebRTC 連接詳情
Janus Gateway 角色
Janus Gateway 作為 WebRTC SFU (Selective Forwarding Unit) 中樞，負責：
- 媒體路由：在座席、客戶和 PBX 之間路由音視頻流
- 编码轉換：根據需要進行编碼轉換
- 质量监测：監測媒體質量和網絡狀態
WebRTC 連接建立
javascript
// SDK 內部自動建立 WebRTC 連接
// 座席無需手動配置
// 可以通過事件監聽連接狀態
sdk.on('webrtcConnected', (event) => {
console.log('WebRTC 連接已建立');
});
sdk.on('webrtcFailed', (event) => {
console.error('WebRTC 連接失敗:', event.reason);
});連接保活機制
Ping/Pong 心跳
SDK 自動發送 Ping 消息保持連接活躍：
- 間隔：30 秒
- 超時：60 秒未收到 Pong 則重連
自動重連
連接中斷時自動重連：
- 首次重連：立即
- 重連間隔：指數級退避 (1s, 2s, 4s, 8s...)
- 最大間隔：30 秒
- 最大重試次數：無限
安全性
認證機制
- 基於 Token 的認證
- WebSocket 連接需要有效的 accessToken
- 定期更新 Token
加密傳輸
- 推薦使用 WSS (WebSocket Secure) 而非 WS
- HTTPS 環境下自動升級為 WSS
- 支持 TLS 1.2 及以上
權限控制
- 座席只能操作自己的會話
- 監督者具有額外的監聽、插話權限
- API 調用時驗證權限
注意事項
- 瀏覽器兼容性：確保使用支持的瀏覽器版本
- 網絡延遲：WebRTC 對網絡延遲敏感，建議延遲 <150ms
- 並發連接：單個座席同時只能有一個 SDK 連接
- 資源清理：在頁面卸載前應調用 logout() 釋放資源
- 錯誤處理：所有異步操作都應包含錯誤處理
操作畫面參考
