通話の転送

2025-06-27

アクティブな通話中に、通話を別のユーザー、番号、ボイスメールに転送することができます。その方法について見ていきましょう。

前提条件

アクティブなサブスクリプションが含まれる 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 インスタンスでは、CallAgent を呼び出すことで createCallAgent インスタンスを作成できます。このメソッドでは、非同期的に CallAgent インスタンスオブジェクトが返されます。

createCallAgent メソッドでは、CommunicationTokenCredential が引数として使用されます。これは、ユーザーアクセストークンを受け取ります。

getDeviceManager インスタンスで CallClient メソッドを使用して、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 つの状態があります。

接続済み - Call Agent の Connected connectionStatue 値は、クライアント SDK が接続されており、Microsoft インフラストラクチャから通知を受信できることを意味します。

切断済み - Call Agent の Disconnected connectionStatue 値は、SDK の正常な接続を妨げる問題があることを示します。 Call Agent を再作成する必要があります。

invalidToken: トークンが有効期限切れであるか、無効な場合、Call Agent インスタンスがこのエラーで切断されます。
connectionIssue: クライアントが Microsoft インフラストラクチャに接続する際に問題が発生した場合、多数の再試行ののちに Call Agent に connectionIssue エラーが表示されます。

Call Agent プロパティの現在の値を調べて、ローカル connectionState が 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操作を呼び出します。
転送先は着信呼び出しを受信します。

現在の呼び出しを転送するには、 transfer 操作を使用できます。 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操作を呼び出します。
転送先は着信呼び出しを受信します。

現在の通話を転送するには、 transferを使用します。

// 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 Aobject を使用すると、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を呼び出します。
"転送元" は、転送要求を受け取ります。

現在の通話を転送するには、 transferを使用できます。

// 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操作を使用すると、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();
   }
});

最初の呼び出し元と転送元の情報

参加者が通話を転送または転送すると、 transferInfo には以前の通話状態に関する情報が入力されます。この情報には、最初の呼び出し元とtransferorInfoについて説明するcallerInfoが含まれます。この情報は、呼び出しを転送または転送するエンティティを記述します。

たとえば、Azure Communication Services ユーザーが Teams 通話キューに通話を発信し、その通話を Microsoft 365 ユーザーに配布する場合、 callerInfo は Azure Communication Services ユーザーを指定し、 transferorInfo は Teams 通話キューを指定します。呼び出し元と転送元には、 displayNameを更新する機能があります。その場合、変更によって callerInfoChanged または transferorInfoChanged イベントがトリガーされます。

変更イベントの詳細については、「イベント: callerInfoChanged 」および「イベント: transferorInfoChanged」を参照してください。変更イベントは、すべての呼び出しに適用され、BRING YOUR OWN IDENTITY (BYOI) や Microsoft 365 を含む任意の ID に適用されます。

const incomingCallHandler = async (args: { incomingCall: IncomingCall }) => {
    const incomingCall = args.incomingCall;
    // Get information about initial caller
    const callerInfo = incomingCall.callerInfo
    // Get information about initial caller
    const transferorInfo = incomingCall.transferorInfo
};