通話の転送

[アーティクル]
07/02/2024

アクティブな通話の途中で、別の人、番号、ボイスメールにその通話を転送したい場合があります。その方法について見ていきましょう。

前提条件

アクティブなサブスクリプションが含まれる Azure アカウント。無料でアカウントを作成できます。
デプロイ済みの Communication Services リソース。 Communication Services リソースを作成します。
通話クライアントを有効にするためのユーザーアクセストークン。詳細については、アクセストークンの作成と管理に関する記事を参照してください。
省略可能: クイックスタートを完了して、アプリケーションに音声通話を追加します

SDK のインストール

npm install コマンドを使用して、JavaScript 用の Azure Communication Services の Common SDK と Calling 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 には、次の 2 つの状態があります。

接続済み - 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 の拡張機能です。まず、Calling SDK から呼び出し機能をインポートする必要があります。

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

その後、呼び出しインスタンスから転送機能 API オブジェクトを取得することができます。

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

通話転送には、次の 3 者が関与します。

"転送者": 転送要求を開始するユーザー。
"転送元": 転送されるユーザー。
"転送先": 転送先のユーザー。

参加者への転送:

"転送者" と "転送元" の間に接続済みの通話が既に存在します。 "転送者" が、"転送元" から "転送先" への通話の転送を決定します。
"転送者" は transfer API を呼び出します。
"転送先" は "転送元" が転送要求を受け入れる場合にのみ着信通話を受信します。

現在の通話を転送するには、transfer API を使用します。 transfer は、disableForwardingAndUnanswered フラグを設定できる省略可能な transferCallOptions を受け取ります。

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 ユーザー ID は既知です。
"転送者" は、ターゲット参加者の 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();
   }
});

次の方法で共有