資源中心
承暉資訊官網

通話接口 ​

概述 ​

通話接口提供完整的通話控制功能，包括撥號、接聽、靜音、保持、轉接、諮詢、會議和掛斷。座席通過這些接口管理整個通話生命週期。

makeCall() - 撥號 ​

座席主動撥號給客戶。

語法 ​

javascript
sdk.makeCall(options);

參數 ​

參數名類型必填說明
tostring是撥號目標 (電話號碼或分機號)
displayNamestring否目標顯示名稱
taskIdstring否外撥任務 ID (用於外撥任務)
contactIdstring否聯絡人 ID (用於外撥任務)
dialTimeoutnumber否撥號超時時間 (秒)，預設為 60

回傳值 ​

返回 Promise，成功時回傳通話對象：

javascript
{
  callId: "call_20260323_001",
  from: "agent_001",
  to: "0912345678",
  state: "DIALING",
  timestamp: "2026-03-23T14:30:00Z"
}

範例 ​

javascript
// 撥號給客戶
sdk.makeCall({
  to: '0912345678',
  displayName: '李美香'
})
.then((call) => {
  console.log('撥號中...', call.to);
})
.catch((error) => {
  console.error('撥號失敗:', error.message);
});

// 外撥任務撥號
sdk.makeCall({
  to: '0912345678',
  taskId: 'task_001',
  contactId: 'contact_001'
})
.then(() => {
  console.log('任務聯絡人撥號中');
});

answerCall() - 接聽 ​

接聽來電或正在撥號的呼叫。

語法 ​

javascript
sdk.answerCall(callId);

參數 ​

參數名類型必填說明
callIdstring否通話 ID；若省略則接聽最新的來電

回傳值 ​

返回 Promise，成功時回傳：

javascript
{
  callId: "call_20260323_001",
  state: "CONNECTING",
  timestamp: "2026-03-23T14:30:05Z"
}

範例 ​

javascript
// 監聽來電並自動接聽
sdk.on('incomingCall', async (event) => {
  console.log('來自', event.from, '的來電');
  try {
    await sdk.answerCall(event.callId);
    console.log('已接聽');
  } catch (error) {
    console.error('接聽失敗:', error);
  }
});

// 或手動接聽
button.onclick = async () => {
  await sdk.answerCall();
};

muteCall() - 靜音 ​

對當前通話進行靜音。

語法 ​

javascript
sdk.muteCall(callId);

參數 ​

參數名類型必填說明
callIdstring否通話 ID；若省略則靜音當前通話

回傳值 ​

返回 Promise，成功時回傳：

javascript
{
  callId: "call_20260323_001",
  muted: true,
  timestamp: "2026-03-23T14:30:30Z"
}

範例 ​

javascript
// 靜音當前通話
muteButton.onclick = async () => {
  try {
    await sdk.muteCall();
    muteButton.classList.add('active');
    console.log('已靜音');
  } catch (error) {
    console.error('靜音失敗:', error);
  }
};

unmuteCall() - 取消靜音 ​

取消當前通話的靜音。

語法 ​

javascript
sdk.unmuteCall(callId);

參數 ​

參數名類型必填說明
callIdstring否通話 ID；若省略則取消靜音當前通話

回傳值 ​

返回 Promise，成功時回傳：

javascript
{
  callId: "call_20260323_001",
  muted: false,
  timestamp: "2026-03-23T14:30:35Z"
}

範例 ​

javascript
// 取消靜音
unmuteButton.onclick = async () => {
  try {
    await sdk.unmuteCall();
    muteButton.classList.remove('active');
    console.log('已取消靜音');
  } catch (error) {
    console.error('取消靜音失敗:', error);
  }
};

holdCall() - 保持 ​

暫停當前通話，客戶端會聽到保持音樂。

語法 ​

javascript
sdk.holdCall(callId);

參數 ​

參數名類型必填說明
callIdstring否通話 ID；若省略則保持當前通話

回傳值 ​

返回 Promise，成功時回傳：

javascript
{
  callId: "call_20260323_001",
  state: "HOLDING",
  timestamp: "2026-03-23T14:31:00Z"
}

範例 ​

javascript
// 保持通話
holdButton.onclick = async () => {
  try {
    await sdk.holdCall();
    holdButton.classList.add('active');
    console.log('通話已保持');
  } catch (error) {
    console.error('保持失敗:', error);
  }
};

resumeCall() - 恢復 ​

恢復被保持的通話。

語法 ​

javascript
sdk.resumeCall(callId);

參數 ​

參數名類型必填說明
callIdstring否通話 ID；若省略則恢復當前通話

回傳值 ​

返回 Promise，成功時回傳：

javascript
{
  callId: "call_20260323_001",
  state: "CONNECTED",
  timestamp: "2026-03-23T14:31:10Z"
}

範例 ​

javascript
// 恢復通話
resumeButton.onclick = async () => {
  try {
    await sdk.resumeCall();
    holdButton.classList.remove('active');
    console.log('通話已恢復');
  } catch (error) {
    console.error('恢復失敗:', error);
  }
};

transferCall() - 轉接 ​

將當前通話轉接給另一個座席或部門。

語法 ​

javascript
sdk.transferCall(options);

參數 ​

參數名類型必填說明
tostring是轉接目標 (座席 ID 或分機號)
blindboolean否是否盲轉接 (不等待對方接聽)，預設為 false
callIdstring否通話 ID；若省略則轉接當前通話

回傳值 ​

返回 Promise，成功時回傳：

javascript
{
  callId: "call_20260323_001",
  state: "TRANSFER",
  transferTo: "agent_002",
  timestamp: "2026-03-23T14:31:30Z"
}

範例 ​

javascript
// 咨詢式轉接 (監聽對方接聽)
async function consultTransfer() {
  try {
    await sdk.transferCall({
      to: 'agent_002',
      blind: false
    });
    console.log('轉接中...');
  } catch (error) {
    console.error('轉接失敗:', error);
  }
}

// 盲轉接 (不等待對方接聽)
async function blindTransfer() {
  try {
    await sdk.transferCall({
      to: 'ext_123',
      blind: true
    });
    console.log('已發起盲轉接');
  } catch (error) {
    console.error('轉接失敗:', error);
  }
}

consultCall() - 諮詢 ​

與另一個座席進行諮詢通話，客戶會被保持。

語法 ​

javascript
sdk.consultCall(options);

參數 ​

參數名類型必填說明
tostring是諮詢目標 (座席 ID 或分機號)
callIdstring否原通話 ID；若省略則諮詢當前通話

回傳值 ​

返回 Promise，成功時回傳：

javascript
{
  callId: "call_20260323_002",
  state: "CONNECTING",
  consultWith: "agent_002",
  originalCallId: "call_20260323_001",
  timestamp: "2026-03-23T14:31:40Z"
}

範例 ​

javascript
// 發起諮詢
consultButton.onclick = async () => {
  const targetAgent = document.getElementById('targetAgent').value;
  try {
    const consultCall = await sdk.consultCall({
      to: targetAgent
    });
    console.log('諮詢通話已建立:', consultCall.callId);
    showConsultUI(consultCall);
  } catch (error) {
    console.error('諮詢失敗:', error);
  }
};

// 結束諮詢並轉接
async function endConsultAndTransfer() {
  try {
    // 先掛斷諮詢通話
    await sdk.hangupCall(consultCallId);
    // 原通話會自動轉接給諮詢對象
    console.log('已轉接');
  } catch (error) {
    console.error('操作失敗:', error);
  }
}

conferenceCall() - 多方會議 ​

將多個通話合併為會議通話。

語法 ​

javascript
sdk.conferenceCall(options);

參數 ​

參數名類型必填說明
callIdsarray是通話 ID 陣列，至少 2 個
conferenceModestring否會議模式 (normal/recording)，預設為 normal

回傳值 ​

返回 Promise，成功時回傳：

javascript
{
  conferenceId: "conf_20260323_001",
  callCount: 3,
  state: "CONFERENCING",
  recordingEnabled: false,
  timestamp: "2026-03-23T14:32:00Z"
}

範例 ​

javascript
// 發起多方會議
async function startConference() {
  const callIds = ['call_001', 'call_002', 'call_003'];
  try {
    const conf = await sdk.conferenceCall({
      callIds: callIds,
      conferenceMode: 'recording'
    });
    console.log('會議已開始:', conf.conferenceId);
    updateConferenceUI(conf);
  } catch (error) {
    console.error('會議建立失敗:', error);
  }
}

hangupCall() - 掛斷 ​

掛斷通話。

語法 ​

javascript
sdk.hangupCall(callId);

參數 ​

參數名類型必填說明
callIdstring否通話 ID；若省略則掛斷當前通話

回傳值 ​

返回 Promise，成功時回傳：

javascript
{
  callId: "call_20260323_001",
  state: "ENDED",
  duration: 180,
  timestamp: "2026-03-23T14:32:30Z"
}

範例 ​

javascript
// 掛斷當前通話
hangupButton.onclick = async () => {
  try {
    const result = await sdk.hangupCall();
    console.log('通話已掛斷，時長:', result.duration, '秒');
  } catch (error) {
    console.error('掛斷失敗:', error);
  }
};

// 掛斷特定通話
async function endSpecificCall(callId) {
  try {
    await sdk.hangupCall(callId);
    console.log('已掛斷通話:', callId);
  } catch (error) {
    console.error('掛斷失敗:', error);
  }
}

getCallInfo() - 獲取通話信息 ​

獲取通話的詳細信息。

語法 ​

javascript
const callInfo = sdk.getCallInfo(callId);

參數 ​

參數名類型必填說明
callIdstring否通話 ID；若省略則獲取當前通話信息

回傳值 ​

返回通話信息對象：

javascript
{
  callId: "call_20260323_001",
  from: "agent_001",
  to: "0912345678",
  displayName: "李美香",
  state: "CONNECTED",
  startTime: "2026-03-23T14:30:00Z",
  duration: 180,
  muted: false,
  onHold: false,
  recordingEnabled: true,
  taskId: "task_001",
  contactId: "contact_001"
}

範例 ​

javascript
// 監聽通話狀態變更並更新 UI
sdk.on('callStateChanged', (event) => {
  const callInfo = sdk.getCallInfo(event.callId);
  document.getElementById('callDuration').textContent = callInfo.duration;
  document.getElementById('callState').textContent = callInfo.state;
});

// 定期更新通話時長
setInterval(() => {
  const callInfo = sdk.getCallInfo();
  if (callInfo && callInfo.state === 'CONNECTED') {
    document.getElementById('duration').textContent =
      formatTime(callInfo.duration);
  }
}, 1000);

通話事件 ​

通話發生時觸發的事件：

事件名回調參數說明
incomingCall{ callId, from, displayName, timestamp }來電通知
callStateChanged{ callId, state, timestamp }通話狀態變更
callEnded{ callId, duration, hangupCode, timestamp }通話結束
muteStateChanged{ callId, muted }靜音狀態變更
holdStateChanged{ callId, onHold }保持狀態變更
recordingStateChanged{ callId, recording }錄音狀態變更

範例 ​

javascript
// 監聽來電
sdk.on('incomingCall', (event) => {
  console.log('來自', event.from, '的來電');
  showIncomingCallUI(event);
});

// 監聽通話狀態
sdk.on('callStateChanged', (event) => {
  console.log('通話狀態:', event.state);
  updateCallStateUI(event.state);
});

// 監聽通話結束
sdk.on('callEnded', (event) => {
  console.log('通話已結束，時長:', event.duration, '秒');
  showCallSummary(event);
});

完整使用示例 ​

場景：完整的入站通話流程 ​

javascript
// 1. 初始化並登錄
const sdk = uni4cc.init({...});
await sdk.login('password');
await sdk.setReady();

// 2. 監聽來電
sdk.on('incomingCall', async (event) => {
  showIncomingCallNotification({
    from: event.from,
    displayName: event.displayName
  });
});

// 3. 接聽通話
async function answerIncomingCall() {
  try {
    await sdk.answerCall();
    showCallUI();
  } catch (error) {
    console.error('接聽失敗:', error);
  }
}

// 4. 監聽通話狀態
sdk.on('callStateChanged', (event) => {
  const callInfo = sdk.getCallInfo();
  updateCallUI(callInfo);
});

// 5. 通話控制
muteButton.onclick = () => sdk.muteCall();
holdButton.onclick = () => sdk.holdCall();
resumeButton.onclick = () => sdk.resumeCall();

// 6. 轉接通話
transferButton.onclick = async () => {
  const targetAgent = prompt('輸入座席 ID:');
  await sdk.transferCall({ to: targetAgent });
};

// 7. 掛斷通話
hangupButton.onclick = async () => {
  const result = await sdk.hangupCall();
  console.log('通話結束，時長:', result.duration);
};

常見錯誤 ​

錯誤碼說明解決方案
NO_ACTIVE_CALL沒有活躍通話先建立或接聽通話
INVALID_CALL_STATE無效的通話狀態檢查當前通話狀態是否允許此操作
TRANSFER_FAILED轉接失敗確認轉接目標是否存在
CONSULT_FAILED諮詢失敗檢查網絡連接
HANGUP_FAILED掛斷失敗重試或聯絡技術支援

注意事項 ​

  1. 同時通話：座席通常只能同時有一個活躍通話
  2. 狀態檢查：在執行操作前檢查通話狀態
  3. 異步操作：所有通話操作都是異步的，應使用 await 或 .then()
  4. 錄音合規：啟用錄音前應符合當地法律要求
  5. 媒體權限：需獲得瀏覽器麥克風和揚聲器權限

承暉資訊資源中心

Copyright © 2026 承暉資訊