資源中心
承暉資訊官網

附錄 ​

SDK 狀態類型完整列表 ​

座席狀態 (AgentStatus) ​

座席的生命週期狀態，由 sdk.getStatus().status 返回。

狀態值代碼說明可轉移到
OFFLINE0未登錄或已登出LOGGEDIN
LOGGEDIN1已登錄，未設置就緒READY, NOT_READY
READY2就緒，可接收來電NOT_READY, TALKING
NOT_READY3非就緒，不接收來電READY, TALKING
TALKING4通話中HOLDING, TRANSFER, CONSULT, CONFERENCE, READY, NOT_READY
HOLDING5通話保持中TALKING, TRANSFER, CONSULT
TRANSFER6轉接中READY, NOT_READY
CONSULT7諮詢中TRANSFER, READY, NOT_READY
CONFERENCE8會議中READY, NOT_READY

通話狀態 (CallState) ​

通話的當前狀態，由 sdk.getCallInfo(callId).state 返回。

狀態值代碼說明觸發條件
INIT0初始狀態通話剛建立
DIALING1正在撥號發起 makeCall()
CONNECTING2連接中 (振鈴)對方正在響鈴
CONNECTED3已連接 (通話中)對方已接聽
HOLDING4保持中執行 holdCall()
TRANSFER5轉接中執行 transferCall()
CONSULT6諮詢中執行 consultCall()
CONFERENCE7會議中執行 conferenceCall()

連接狀態 (ConnectionState) ​

SDK 與伺服器的連接狀態。

狀態值說明
CONNECTED已連接
CONNECTING連接中
DISCONNECTED已斷開
RECONNECTING重連中
FAILED連接失敗

錯誤代碼參考 ​

認證相關 ​

代碼說明建議
AUTH_001密碼錯誤重新輸入正確的密碼
AUTH_002座席不存在確認座席 ID 是否正確
AUTH_003Token 已過期重新登錄獲取新 Token
AUTH_004Token 無效檢查 Token 格式

連接相關 ​

代碼說明建議
CONN_001連接超時檢查網絡連接和伺服器狀態
CONN_002連接被拒絕檢查伺服器是否在線
CONN_003WebSocket 錯誤檢查瀏覽器控制台錯誤
CONN_004網絡不可用檢查網絡連接

通話相關 ​

代碼說明建議
CALL_001沒有活躍通話先建立或接聽通話
CALL_002無效的通話狀態檢查當前通話狀態
CALL_003撥號失敗檢查被叫號碼是否有效
CALL_004轉接失敗確認轉接目標存在
CALL_005掛斷失敗重試或聯絡技術支援

權限相關 ​

代碼說明建議
PERM_001權限不足以更高權限重新登錄
PERM_002操作被禁止檢查座席權限配置
PERM_003資源無權訪問確認資源所有權

WebRTC 連接邏輯 ​

連接流程 ​

SDK 初始化
    ↓
WebSocket 連接建立
    ↓
login() 認證
    ↓
Janus Gateway 連接
    ↓
通話建立時協商 WebRTC
    ↓
RTCPeerConnection 建立
    ↓
媒體流開始流動
    ↓
通話結束
    ↓
媒體流停止
    ↓
RTCPeerConnection 關閉

ICE 候選收集 ​

javascript
// SDK 內部自動處理，開發者無需干預
// 候選收集會在 WebRTC 連接建立時自動進行

sdk.on('webrtcConnecting', (event) => {
  console.log('WebRTC 連接建立中...');
});

sdk.on('webrtcConnected', (event) => {
  console.log('WebRTC 連接已建立');
  console.log('本地 IP:', event.localIP);
  console.log('遠程 IP:', event.remoteIP);
});

sdk.on('webrtcFailed', (event) => {
  console.error('WebRTC 連接失敗:', event.reason);
});

STUN/TURN 服務器配置 ​

AICC 系統會自動使用 Janus Gateway 配置的 STUN/TURN 服務器。

典型配置：

STUN 服務器: stun.aicc.example.com:3478
TURN 服務器: turn.aicc.example.com:3478
用戶名: aicc_user
密碼: aicc_password

媒體協商 ​

通話建立時，SDK 自動進行以下協商：

  1. 編碼協商：確定可用的音視頻編碼
  2. 比特率協商：根據帶寬選擇合適的比特率
  3. 媒體類型協商：決定是音頻、視頻還是音視頻
javascript
// 座席可查詢協商結果
sdk.on('callStateChanged', (event) => {
  if (event.state === 'CONNECTED') {
    const stats = sdk.getCallStats(event.callId);
    console.log('音頻編碼:', stats.audioCodec);
    console.log('視頻編碼:', stats.videoCodec);
    console.log('當前比特率:', stats.bitrate, 'kbps');
  }
});

網絡質量監測 ​

實時統計 ​

javascript
// 定期取得通話統計信息
setInterval(() => {
  const stats = sdk.getCallStats(currentCallId);
  if (stats) {
    console.log('包丟失率:', stats.packetLoss, '%');
    console.log('往返延遲:', stats.rtt, 'ms');
    console.log('音頻比特率:', stats.audioBitrate, 'kbps');
    console.log('視頻比特率:', stats.videoBitrate, 'kbps');
  }
}, 1000);

統計信息結構 ​

javascript
{
  callId: "call_20260323_001",
  state: "CONNECTED",

  // 音頻統計
  audioCodec: "opus",
  audioBitrate: 128,          // kbps
  audioPacketsSent: 15000,
  audioPacketsLost: 50,
  audioPacketLoss: 0.33,      // %
  audioJitter: 20,            // ms

  // 視頻統計
  videoCodec: "vp8",
  videoBitrate: 500,          // kbps
  videoFrameRate: 30,         // fps
  videoResolution: "640x480",
  videoPacketsSent: 3000,
  videoPacketsLost: 10,
  videoPacketLoss: 0.33,      // %

  // 網絡統計
  rtt: 50,                    // ms (Round Trip Time)
  jitter: 15,                 // ms
  availableBandwidth: 2500,   // kbps

  // 通話統計
  duration: 300,              // s
  totalBitrate: 700,          // kbps
  connectionQuality: "good"   // good/fair/poor
}

常見場景的狀態轉移 ​

入站通話接聽 ​

READY
  ↓ (incomingCall 事件)
READY (收到來電通知，播放鈴音)
  ↓ (answerCall())
TALKING
  ↓ (callEnded 事件)
READY

出站通話撥號 ​

READY
  ↓ (makeCall())
TALKING (DIALING → CONNECTING → CONNECTED)
  ↓ (holdCall())
HOLDING
  ↓ (resumeCall())
TALKING
  ↓ (hangupCall())
READY

轉接流程 ​

TALKING (與客戶)
  ↓ (transferCall())
TRANSFER (等待轉接目標接聽)
  ↓ (轉接成功或失敗)
READY (通話已轉移)
  或
TALKING (轉接失敗，重新連接)

諮詢流程 ​

TALKING (與客戶)
  ↓ (consultCall())
CONSULT (客戶被保持，諮詢進行中)
  ↓ (完成諮詢，掛斷諮詢通話)
TALKING (回到客戶通話)
  或
TRANSFER (轉接給諮詢對象)

第三方集成指南 ​

CRM 集成 ​

javascript
// 通話開始時自動查詢 CRM 客戶信息
sdk.on('incomingCall', async (event) => {
  // 調用 CRM API 取得客戶信息
  const customerInfo = await fetchFromCRM(event.from);

  // 在 UI 中顯示客戶信息
  displayCustomerInfo(customerInfo);
});

// 通話結束時保存備註
sdk.on('callEnded', async (event) => {
  const notes = document.getElementById('callNotes').value;
  await saveToCRM({
    phone: event.from,
    duration: event.duration,
    notes: notes,
    timestamp: new Date()
  });
});

IVR 集成 ​

javascript
// 來電通過 IVR 時的處理
sdk.on('incomingCall', (event) => {
  if (event.ivrPath) {
    console.log('IVR 路徑:', event.ivrPath);
    // 根據 IVR 路徑自動路由
    routeByIVRPath(event.ivrPath);
  }
});

質量監控系統集成 ​

javascript
// 定期上傳統計數據到質量監控系統
setInterval(async () => {
  const status = sdk.getStatus();
  if (status && status.status === 'TALKING') {
    const stats = sdk.getCallStats(currentCallId);

    // 上傳到監控系統
    await reportQualityMetrics({
      agentId: status.agentId,
      callId: currentCallId,
      packetLoss: stats.audioPacketLoss,
      jitter: stats.jitter,
      rtt: stats.rtt,
      timestamp: Date.now()
    });
  }
}, 10000); // 每 10 秒上傳一次

性能優化建議 ​

  1. 減少事件監聽數量：只監聽必要的事件
  2. 批量操作：避免頻繁的 API 調用
  3. 媒體流管理：及時停止未使用的媒體流
  4. 內存管理：定期清理過期的通話記錄
  5. 邏輯優化：避免在事件回調中進行複雜計算

常見問題解決 ​

無法建立 WebRTC 連接 ​

症狀：通話建立後無聲音或視頻。

排查步驟：

  1. 檢查瀏覽器控制台是否有 WebRTC 相關錯誤
  2. 確認 Janus Gateway 伺服器是否在線
  3. 檢查防火牆是否阻止了 UDP 端口
  4. 驗證 STUN/TURN 服務器配置
  5. 檢查本地麥克風和揚聲器權限

通話延遲高 ​

症狀：通話時存在明顯的音視頻延遲。

優化方案：

  1. 檢查網絡延遲 (ping 時間)
  2. 減少後臺應用占用的帶寬
  3. 檢查 ISP 是否有 QoS 限制
  4. 考慮使用有線連接而非 WiFi
  5. 調整比特率設置

頻繁掉線 ​

症狀：通話或 SDK 連接頻繁中斷。

排查步驟：

  1. 檢查網絡穩定性
  2. 查看伺服器日誌是否有異常
  3. 檢查防火牆規則
  4. 驗證 Token 有效期
  5. 增加重連重試次數

相關資源 ​

操作畫面參考 ​

Appendix - 操作畫面 1

Appendix - 操作畫面 2

Appendix - 操作畫面 3

Appendix - 操作畫面 4

Appendix - 操作畫面 5

Appendix - 操作畫面 6

Appendix - 操作畫面 7

Appendix - 操作畫面 8

承暉資訊資源中心

Copyright © 2026 承暉資訊