來電轉接

發行項
12/18/2024

在通話當中，您可能想要將通話轉接給另一個人、號碼或語音信箱。讓我們來了解如何進行。

必要條件

具有有效訂用帳戶的 Azure 帳戶。免費建立帳戶。
已部署通訊服務資源。建立通訊服務資源。
用來啟用呼叫用戶端的使用者存取權杖。如需詳細資訊，請參閱建立和管理存取權杖。
選擇性：完成快速入門以將語音通話新增至您的應用程式

安裝 SDK

使用 npm install 命令，安裝適用於 JavaScript 的 Azure 通訊服務通用和通話 SDK：

npm install @azure/communication-common --save
npm install @azure/communication-calling --save

初始化必要的物件

大部分通話作業都需要 CallClient 執行個體。當您建立新的 CallClient 執行個體時，您可以使用自訂選項加以設定，如同 Logger 執行個體一樣。

使用 CallClient 執行個體，您可以藉由呼叫 createCallAgent 來建立 CallAgent 執行個體。此方法會以非同步的方式傳回 CallAgent 執行個體物件。

createCallAgent 方法會使用 CommunicationTokenCredential 作為引數。其接受使用者存取權杖。

您可以使用 CallClient 執行個體上的 getDeviceManager 方法來存取 deviceManager。

const { CallClient } = require('@azure/communication-calling');
const { AzureCommunicationTokenCredential} = require('@azure/communication-common');
const { AzureLogger, setLogLevel } = require("@azure/logger");

// Set the logger's log level
setLogLevel('verbose');

// Redirect log output to console, file, buffer, REST API, or whatever location you want
AzureLogger.log = (...args) => {
    console.log(...args); // Redirect log output to console
};

const userToken = '<USER_TOKEN>';
callClient = new CallClient(options);
const tokenCredential = new AzureCommunicationTokenCredential(userToken);
const callAgent = await callClient.createCallAgent(tokenCredential, {displayName: 'optional Azure Communication Services user name'});
const deviceManager = await callClient.getDeviceManager()

如何最好地管理與 Microsoft 基礎結構的 SDK 連線

Call Agent 執行個體可協助您管理通話 (加入或啟動通話)。若要運作，您的通話 SDK 必須連線到 Microsoft 基礎結構以取得來電通知，並協調其他通話詳細資料。您的 Call Agent 有兩種可能的狀態：

已連線 - Connected 的 Call Agent connectionStatue 值表示用戶端 SDK 已連線且能夠接收來自 Microsoft 基礎結構的通知。

已中斷連線 - Disconnected 狀態的 Call Agent connectionStatue 值指出有問題導致 SDK 無法正確連線。 Call Agent 應該重新建立。

invalidToken：如果權杖已過期或無效，Call Agent 執行個體會中斷連線，並出現此錯誤。
connectionIssue：如果用戶端連線到 Microsoft 基礎結構時發生問題，在多次重試之後，Call Agent 會公開 connectionIssue 錯誤。

您可以藉由檢查 connectionState 屬性的目前值，檢查本機 Call Agent 是否已連線到 Microsoft 基礎結構。在作用中通話期間，您可以接聽 connectionStateChanged 事件，以判斷 Call Agent 是否從已連線變更為已中斷連線狀態。

const connectionState = callAgentInstance.connectionState;
console.log(connectionState); // it may return either of 'Connected' | 'Disconnected'

const connectionStateCallback = (args) => {
    console.log(args); // it will return an object with oldState and newState, each of having a value of either of 'Connected' | 'Disconnected'
    // it will also return reason, either of 'invalidToken' | 'connectionIssue'
}
callAgentInstance.on('connectionStateChanged', connectionStateCallback);

通話轉接是核心 Call API 的擴充功能。您必須先從通話 SDK 匯入通話功能：

import { Features} from "@azure/communication-calling";

然後，您可以從通話執行個體取得轉接功能 API 物件：

const callTransferApi = call.feature(Features.Transfer);

通話轉接涉及三方：

轉接者：起始轉接要求的人。
被轉接者：被轉接的人。
轉接目標：轉接給此人。

轉接給參與者：

「轉接者」與「被轉接者」之間已接通電話。「轉接者」決定將通話從「被轉接者」轉接給「轉接目標」。
「轉接者」呼叫 transfer API。
傳輸目標會收到來電。

若要轉接目前的通話，您可以使用 transfer API。 transfer 接受選用的 transferCallOptions，這可讓您設定 disableForwardingAndUnanswered 旗標：

disableForwardingAndUnanswered = false：如果「轉接目標」未接聽轉接通話，則轉接會遵循「轉接目標」的轉接和未接聽設定。
disableForwardingAndUnanswered = true：如果「轉接目標」未接聽轉接通話，則轉接嘗試會結束。

// transfer target can be an Azure Communication Services user
const id = { communicationUserId: <ACS_USER_ID> };

// call transfer API
const transfer = callTransferApi.transfer({targetParticipant: id});

轉接到通話：

「轉接者」與「被轉接者」之間已接通電話。
「轉接者」與「轉接目標」之間已接通電話。
「轉接者」決定將與「被轉接者」的通話，轉接到與「轉接目標」的通話。
「轉接者」呼叫 transfer API。
傳輸目標會收到來電。

若要轉接目前的通話，您可以使用 transfer API。

// transfer to the target call specifying the call id
const id = { targetCallId: <CALL_ID> };

// call transfer API
const transfer = callTransferApi.transfer({ targetCallId: <CALL_ID> });

transfer API 可讓您訂閱 stateChanged。它也隨附傳輸 state 和 error 屬性

// transfer state
const transferState = transfer.state; // None | Transferring | Transferred | Failed

// to check the transfer failure reason
const transferError = transfer.error; // transfer error code that describes the failure if a transfer request failed

「被轉接者」可以接聽 transferAccepted 事件。此事件的接聽程式具有 TransferEventArgs，其中包含「被轉接者」與「轉接目標」之間的新轉接呼叫的呼叫物件。

// Transferee can subscribe to the transferAccepted event
callTransferApi.on('transferAccepted', args => {
    const newTransferCall =  args.targetCall;
});

「轉接者」可以訂閱事件，以獲悉轉接狀態的變化。如果「被轉接者」與「轉接目標」成功接通電話，則「轉接者」可以掛斷與「被轉接者」的原始通話。

transfer.on('stateChanged', () => {
   if (transfer.state === 'Transferred') {
       call.hangUp();
   }
});

傳送至語音信箱：

「轉接者」與「被轉接者」之間有已連線的通話。
已知目標參與者語音信箱的 Teams 使用者識別碼。
「轉接者」決定使用目標參與者的 Teams 使用者識別碼，將與「被轉接者」的通話轉移至「目標參與者的語音信箱」。
「轉接者」呼叫 transfer API。
被轉接者會收到轉接要求。

若要轉接目前的通話，您可以使用 transfer API。

// transfer to the target participant voicemail specified by their Teams User Identifier
const id: MicrosoftTeamsUserIdentifier = { microsoftTeamsUserId: userId}

// call transfer API
const transfer = callTransferApi.transfer({ targetParticipantVoicemail: id });

transfer API 可讓您訂閱 stateChanged。它也隨附傳輸 state 和 error 屬性

// transfer state
const transferState = transfer.state; // None | Transferring | Transferred | Failed

// to check the transfer failure reason
const transferError = transfer.error; // transfer error code that describes the failure if a transfer request failed

「被轉接者」可以接聽 transferAccepted 事件。此事件的接聽程式具有 TransferEventArgs，其中包含被轉接者與目標參與者語音信箱之間的新來電轉接的呼叫物件。

// Transferee can subscribe to the transferAccepted event
callTransferApi.on('transferAccepted', args => {
    const newTransferCall =  args.targetCall;
});

「轉接者」可以訂閱事件，以獲悉轉接狀態的變化。如果被轉接者與目標參與者語音信箱成功接通電話，則轉接者可以掛斷與被轉接者的原始通話。

transfer.on('stateChanged', () => {
   if (transfer.state === 'Transferred') {
       call.hangUp();
   }
});

共用方式為