附錄

SDK 狀態類型完整列表

座席狀態 (AgentStatus)

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

狀態值	代碼	說明	可轉移到
OFFLINE	0	未登錄或已登出	LOGGEDIN
LOGGEDIN	1	已登錄，未設置就緒	READY, NOT_READY
READY	2	就緒，可接收來電	NOT_READY, TALKING
NOT_READY	3	非就緒，不接收來電	READY, TALKING
TALKING	4	通話中	HOLDING, TRANSFER, CONSULT, CONFERENCE, READY, NOT_READY
HOLDING	5	通話保持中	TALKING, TRANSFER, CONSULT
TRANSFER	6	轉接中	READY, NOT_READY
CONSULT	7	諮詢中	TRANSFER, READY, NOT_READY
CONFERENCE	8	會議中	READY, NOT_READY

通話狀態 (CallState)

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

狀態值	代碼	說明	觸發條件
INIT	0	初始狀態	通話剛建立
DIALING	1	正在撥號	發起 makeCall()
CONNECTING	2	連接中 (振鈴)	對方正在響鈴
CONNECTED	3	已連接 (通話中)	對方已接聽
HOLDING	4	保持中	執行 holdCall()
TRANSFER	5	轉接中	執行 transferCall()
CONSULT	6	諮詢中	執行 consultCall()
CONFERENCE	7	會議中	執行 conferenceCall()

連接狀態 (ConnectionState)

SDK 與伺服器的連接狀態。

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

錯誤代碼參考

認證相關

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

連接相關

代碼	說明	建議
CONN_001	連接超時	檢查網絡連接和伺服器狀態
CONN_002	連接被拒絕	檢查伺服器是否在線
CONN_003	WebSocket 錯誤	檢查瀏覽器控制台錯誤
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 候選收集

// 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. 媒體類型協商：決定是音頻、視頻還是音視頻

// 座席可查詢協商結果
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');
  }
});

網絡質量監測

實時統計

// 定期取得通話統計信息
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);

統計信息結構

{
  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 集成

// 通話開始時自動查詢 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 集成

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

質量監控系統集成

// 定期上傳統計數據到質量監控系統
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. 增加重連重試次數

相關資源

• AICC 技術文檔
• Janus Gateway 文檔
• WebRTC 規範
• RFC 3389 (RTP Comfort Noise)

操作畫面參考