SDK 事件

概述

SDK 透過事件機制向應用發送各類通知，包括座席生命週期、通話狀態、連接狀態等。應用通過監聽這些事件，能夠實時獲取系統狀態變化。

座席生命週期事件

loginSuccess - 登錄成功

座席成功登錄。

javascript

sdk.on('loginSuccess', (event) => {
  console.log('登錄成功', event.agentId, event.agentName);
});

事件參數：

參數名	型別	說明
`agentId`	string	座席 ID
`agentName`	string	座席姓名
`loginType`	number	登錄類型 (1:座席, 2:監督者, 3:管理員)
`workType`	number	工作類型 (1:入站, 2:出站, 3:混合)
`timestamp`	string	事件時間戳

loginFailed - 登錄失敗

座席登錄失敗。

javascript

sdk.on('loginFailed', (event) => {
  console.error('登錄失敗:', event.reason);
});

事件參數：

參數名	型別	說明
`reason`	string	失敗原因
`errorCode`	string	錯誤代碼
`message`	string	詳細訊息

logoutSuccess - 登出成功

座席成功登出。

javascript

sdk.on('logoutSuccess', (event) => {
  console.log('已安全登出');
});

statusChanged - 狀態變更

座席狀態發生變更。

javascript

sdk.on('statusChanged', (event) => {
  console.log('座席狀態:', event.status, '原因:', event.reason);
});

事件參數：

參數名	型別	說明
`status`	string	新狀態 (OFFLINE, LOGGEDIN, READY, NOT_READY, TALKING, HOLDING, TRANSFER, CONSULT, CONFERENCE)
`previousStatus`	string	前一個狀態
`reason`	string	狀態變更原因
`timestamp`	string	事件時間戳

readyStatusChanged - 就緒狀態變更

座席就緒狀態變更。

javascript

sdk.on('readyStatusChanged', (event) => {
  if (event.ready) {
    console.log('座席已就緒');
  } else {
    console.log('座席非就緒:', event.reason);
  }
});

事件參數：

參數名	型別	說明
`ready`	boolean	是否就緒
`reason`	string	原因 (如果非就緒)

通話狀態事件

incomingCall - 來電通知

座席收到來電。

javascript

sdk.on('incomingCall', (event) => {
  console.log('來自', event.from, '的來電');
  console.log('顯示名稱:', event.displayName);
});

事件參數：

參數名	型別	說明
`callId`	string	通話 ID
`from`	string	來電號碼
`displayName`	string	顯示名稱
`queueName`	string	隊列名稱
`ivrPath`	string	IVR 路徑 (若通過 IVR)
`timestamp`	string	來電時間

callStateChanged - 通話狀態變更

通話狀態發生變更。

javascript

sdk.on('callStateChanged', (event) => {
  console.log('通話', event.callId, '狀態變更為:', event.state);
  updateCallUI(event);
});

事件參數：

參數名	型別	說明
`callId`	string	通話 ID
`state`	string	新狀態 (INIT, DIALING, CONNECTING, CONNECTED, HOLDING, TRANSFER, CONSULT, CONFERENCE)
`previousState`	string	前一個狀態
`timestamp`	string	事件時間戳
`duration`	number	通話時長 (秒)

callEnded - 通話結束

通話已結束。

javascript

sdk.on('callEnded', (event) => {
  console.log('通話結束，時長:', event.duration, '秒');
  console.log('掛機代碼:', event.hangupCode, '原因:', event.hangupReason);
});

事件參數：

參數名	型別	說明
`callId`	string	通話 ID
`duration`	number	通話時長 (秒)
`talkDuration`	number	實際通話時長 (秒)
`hangupCode`	number	掛機代碼 (0-15)
`hangupReason`	string	掛機原因
`endTime`	string	結束時間

muteStateChanged - 靜音狀態變更

靜音狀態發生變更。

javascript

sdk.on('muteStateChanged', (event) => {
  if (event.muted) {
    console.log('已靜音');
  } else {
    console.log('已取消靜音');
  }
});

事件參數：

參數名	型別	說明
`callId`	string	通話 ID
`muted`	boolean	是否靜音
`timestamp`	string	事件時間戳

holdStateChanged - 保持狀態變更

保持狀態發生變更。

javascript

sdk.on('holdStateChanged', (event) => {
  if (event.onHold) {
    console.log('通話已保持');
  } else {
    console.log('通話已恢復');
  }
});

事件參數：

參數名	型別	說明
`callId`	string	通話 ID
`onHold`	boolean	是否保持中
`timestamp`	string	事件時間戳

連接狀態事件

connectionLost - 連接丟失

與伺服器的 WebSocket 連接中斷。

javascript

sdk.on('connectionLost', (event) => {
  console.warn('連接已丟失:', event.reason);
  showAlert('網絡連接已中斷，正在重新連接...');
});

事件參數：

參數名	型別	說明
`reason`	string	中斷原因
`willReconnect`	boolean	是否會自動重連
`retryCount`	number	重連次數

connectionRestored - 連接恢復

與伺服器的連接已恢復。

javascript

sdk.on('connectionRestored', (event) => {
  console.log('連接已恢復');
  hideAlert();
});

事件參數：

參數名	型別	說明
`reconnectAttempts`	number	重連嘗試次數
`totalDowntime`	number	宕機時長 (秒)

通話詳細事件

recordingStateChanged - 錄音狀態變更

錄音狀態發生變更。

javascript

sdk.on('recordingStateChanged', (event) => {
  if (event.recording) {
    console.log('錄音已開始');
  } else {
    console.log('錄音已停止');
  }
});

事件參數：

參數名	型別	說明
`callId`	string	通話 ID
`recording`	boolean	是否錄音中
`recordingUrl`	string	錄音文件 URL (錄音結束時)

speechRecognized - 語音識別結果

實時語音識別結果。

javascript

sdk.on('speechRecognized', (event) => {
  console.log('識別文本:', event.text);
  console.log('置信度:', event.confidence);
  updateTranscript(event.text);
});

事件參數：

參數名	型別	說明
`callId`	string	通話 ID
`text`	string	識別結果文本
`confidence`	number	置信度 (0-1)
`isFinal`	boolean	是否是最終結果
`speaker`	string	說話者 (agent/customer)
`timestamp`	string	事件時間戳

transferInitiated - 轉接開始

通話轉接已開始。

javascript

sdk.on('transferInitiated', (event) => {
  console.log('轉接給:', event.transferTo);
});

事件參數：

參數名	型別	說明
`callId`	string	通話 ID
`transferTo`	string	轉接目標 (座席 ID 或分機)
`blind`	boolean	是否盲轉接

transferCompleted - 轉接完成

通話轉接已完成。

javascript

sdk.on('transferCompleted', (event) => {
  console.log('轉接成功');
});

consultInitiated - 諮詢開始

與另一座席的諮詢已開始。

javascript

sdk.on('consultInitiated', (event) => {
  console.log('諮詢通話 ID:', event.consultCallId);
});

事件參數：

參數名	型別	說明
`originalCallId`	string	原通話 ID
`consultCallId`	string	諮詢通話 ID
`consultWith`	string	諮詢對象

監督者事件

monitorStarted - 監聽開始

監督者開始監聽座席的通話。

javascript

sdk.on('monitorStarted', (event) => {
  console.log('監督者開始監聽:', event.supervisorId);
});

bargeStarted - 強制插話開始

監督者開始強制插話。

javascript

sdk.on('bargeStarted', (event) => {
  console.log('監督者已插話');
  notifyAgent('監督者已加入通話');
});

whisperStarted - 耳語開始

監督者開始對座席進行耳語。

javascript

sdk.on('whisperStarted', (event) => {
  console.log('正在接收監督指導');
});

agentStatusChanged - 座席狀態變更 (監督者視角)

監督者監控的座席狀態發生變更。

javascript

sdk.on('agentStatusChanged', (event) => {
  console.log(event.agentId, '狀態:', event.newStatus);
  updateAgentStatusUI(event.agentId, event.newStatus);
});

錯誤事件

error - 錯誤事件

SDK 發生錯誤。

javascript

sdk.on('error', (event) => {
  console.error('SDK 錯誤:', event.errorCode, event.message);
  handleError(event);
});

事件參數：

參數名	型別	說明
`errorCode`	string	錯誤代碼
`message`	string	錯誤訊息
`context`	object	錯誤上下文信息

完整事件監聽示例

javascript

// 初始化 SDK
const sdk = uni4cc.init({...});

// 座席生命週期
sdk.on('loginSuccess', handleLoginSuccess);
sdk.on('loginFailed', handleLoginFailed);
sdk.on('statusChanged', handleStatusChange);

// 通話事件
sdk.on('incomingCall', handleIncomingCall);
sdk.on('callStateChanged', handleCallStateChange);
sdk.on('callEnded', handleCallEnd);

// 通話控制
sdk.on('muteStateChanged', updateMuteUI);
sdk.on('holdStateChanged', updateHoldUI);

// 連接狀態
sdk.on('connectionLost', showConnectionError);
sdk.on('connectionRestored', hideConnectionError);

// 高級功能
sdk.on('speechRecognized', updateTranscript);
sdk.on('recordingStateChanged', updateRecordingUI);

// 監督功能 (監督者)
sdk.on('agentStatusChanged', updateTeamDashboard);
sdk.on('monitorStarted', handleMonitorStart);

// 錯誤處理
sdk.on('error', handleError);

// 事件處理函數
function handleLoginSuccess(event) {
  console.log('歡迎,', event.agentName);
  document.getElementById('agentName').textContent = event.agentName;
}

function handleIncomingCall(event) {
  playIncomingCallAlert();
  showIncomingCallUI({
    from: event.from,
    displayName: event.displayName
  });
}

function handleCallEnd(event) {
  console.log('通話結束');
  console.log('時長:', event.duration, '秒');
  console.log('掛機原因:', event.hangupReason);
  logCall(event);
}

function handleError(event) {
  console.error('Error:', event.errorCode, event.message);
  showErrorAlert(event.message);
}

事件監聽最佳實踐

及時監聽：在 SDK 初始化後立即設置事件監聽
錯誤處理：為所有可能出錯的事件設置錯誤處理
UI 更新：使用事件更新 UI 而非輪詢
性能考慮：避免在事件處理中進行耗時操作
日誌記錄：記錄重要事件用於除錯和分析

常見事件組合

典型入站通話流程

loginSuccess
  ↓
statusChanged (READY)
  ↓
incomingCall
  ↓
callStateChanged (CONNECTING)
  ↓
callStateChanged (CONNECTED)
  ↓
speechRecognized (多次)
  ↓
callStateChanged (HOLDING/TRANSFER)
  ↓
callEnded

典型出站通話流程

callStateChanged (DIALING)
  ↓
callStateChanged (CONNECTING)
  ↓
callStateChanged (CONNECTED)
  ↓
speechRecognized (多次)
  ↓
muteStateChanged
  ↓
callStateChanged (HOLDING)
  ↓
recordingStateChanged
  ↓
callEnded

SDK 事件 ​

概述 ​

座席生命週期事件 ​

loginSuccess - 登錄成功 ​

loginFailed - 登錄失敗 ​

logoutSuccess - 登出成功 ​

statusChanged - 狀態變更 ​

readyStatusChanged - 就緒狀態變更 ​

通話狀態事件 ​

incomingCall - 來電通知 ​

callStateChanged - 通話狀態變更 ​

callEnded - 通話結束 ​

muteStateChanged - 靜音狀態變更 ​

holdStateChanged - 保持狀態變更 ​

連接狀態事件 ​

connectionLost - 連接丟失 ​

connectionRestored - 連接恢復 ​

通話詳細事件 ​

recordingStateChanged - 錄音狀態變更 ​

speechRecognized - 語音識別結果 ​

transferInitiated - 轉接開始 ​

transferCompleted - 轉接完成 ​

consultInitiated - 諮詢開始 ​

監督者事件 ​

monitorStarted - 監聽開始 ​

bargeStarted - 強制插話開始 ​

whisperStarted - 耳語開始 ​

agentStatusChanged - 座席狀態變更 (監督者視角) ​

錯誤事件 ​

error - 錯誤事件 ​

完整事件監聽示例 ​

事件監聽最佳實踐 ​

常見事件組合 ​

典型入站通話流程 ​

典型出站通話流程 ​

SDK 事件

概述

座席生命週期事件

loginSuccess - 登錄成功

loginFailed - 登錄失敗

logoutSuccess - 登出成功

statusChanged - 狀態變更

readyStatusChanged - 就緒狀態變更

通話狀態事件

incomingCall - 來電通知

callStateChanged - 通話狀態變更

callEnded - 通話結束

muteStateChanged - 靜音狀態變更

holdStateChanged - 保持狀態變更

連接狀態事件

connectionLost - 連接丟失

connectionRestored - 連接恢復

通話詳細事件

recordingStateChanged - 錄音狀態變更

speechRecognized - 語音識別結果

transferInitiated - 轉接開始

transferCompleted - 轉接完成

consultInitiated - 諮詢開始

監督者事件

monitorStarted - 監聽開始

bargeStarted - 強制插話開始

whisperStarted - 耳語開始

agentStatusChanged - 座席狀態變更 (監督者視角)

錯誤事件

error - 錯誤事件

完整事件監聽示例

事件監聽最佳實踐

常見事件組合

典型入站通話流程

典型出站通話流程