次の方法で共有

Call Automation による通話中メディア アクションをコントロールする方法についての攻略ガイド

  • [アーティクル]

Call Automation は、REST API インターフェイスを使用してアクションの要求を受信し、要求が正常に送信されたかどうかを通知する応答を提供するものです。 通話の非同期性のため、ほとんどのアクションには、アクションが正常に完了または失敗したときにトリガーされる、対応するイベントがあります。 このガイドでは、DTMF 送信や継続的 DTMF 認識など、開発者が通話中に使用できるアクションについて説明します。 アクションには、そのアクションを呼び出す方法を示すサンプル コードが付属しています。

Call Automation では、このガイドに含まれていない通話と記録を管理するための他のさまざまなアクションがサポートされています。

Note

現在、Call Automation と Microsoft Teams の相互運用はできません。 Teams ユーザーに対する、Call Automation を使用した発信、リダイレクト、オーディオの再生などのアクションはサポートされていません。

このガイドを最大限に活用するには、前提条件として次の記事を参照することをお勧めします。

  1. Call Automation の概念ガイドでは、アクション イベント プログラミング モデルとイベント コールバックについて説明しています。
  2. このガイドで使用している CommunicationUserIdentifier や PhoneNumberIdentifier などのユーザー識別子についての説明。
  3. Call Automation を使用して通話を制御および操作する方法の詳細について説明します。ここでは、通話を処理する際の基本の扱いについて説明しています。

すべてのコード サンプルについて、client は示されている方法で作成できる CallAutomationClient オブジェクトであり、callConnection は、Answer または CreateCall 応答から取得される CallConnection オブジェクトです。 アプリケーションで受信するコールバック イベントから取得することもできます。

var callAutomationClient = new CallAutomationClient("<Azure Communication Services connection string>");

DTMF 送信

DTMF トーンを外部参加者に送信できます。これが便利なのは、すでに通話の準備ができていて、内線番号または IVR メニューを持つ別の参加者を招待して移動する必要がある場合です。

Note

これがサポートされているのは外部の PSTN 参加者のみであり、一度に最大で 18 トーンの送信がサポートされます。

SendDtmfAsync メソッド

DTMF トーンの一覧を外部参加者に送信します。

var tones = new DtmfTone[] { DtmfTone.One, DtmfTone.Two, DtmfTone.Three, DtmfTone.Pound }; 
var sendDtmfTonesOptions = new SendDtmfTonesOptions(tones, new PhoneNumberIdentifier(calleePhonenumber))
{ 
	OperationContext = "dtmfs-to-ivr" 
}; 

var sendDtmfAsyncResult = await callAutomationClient.GetCallConnection(callConnectionId) 
	.GetCallMedia() 
        .SendDtmfTonesAsync(sendDtmfTonesOptions);

アプリケーションがこれらの DTMF トーンを送信すると、イベント更新が届きます。 SendDtmfTonesCompleted および SendDtmfTonesFailed のイベントを使用してビジネス ロジックをアプリケーション内に作成して、次のステップを決めることができます。

SendDtmfTonesCompleted イベントの例

if (acsEvent is SendDtmfTonesCompleted sendDtmfCompleted) 
{ 
    logger.LogInformation("Send DTMF succeeded, context={context}", sendDtmfCompleted.OperationContext); 
}

SendDtmfTonesFailed イベントの例

if (acsEvent is SendDtmfTonesFailed sendDtmfFailed) 
{ 
    logger.LogInformation("Send dtmf failed: result={result}, context={context}", 
        sendDtmfFailed.ResultInformation?.Message, sendDtmfFailed.OperationContext); 
}

継続的 DTMF 認識

継続的 DTMF トーンを通話全体で受け取るためのサブスクライブができます。 対象となる参加者がキーパッドのキーを押すと、アプリケーションが DTMF トーンを受信します。 これらのトーンは、参加者がキーを押していると、アプリケーションにひとつずつ送信されます。

StartContinuousDtmfRecognitionAsync メソッド

参加者によって送信された DTMF トーンの検出を開始します。

await callAutomationClient.GetCallConnection(callConnectionId) 
    .GetCallMedia() 
    .StartContinuousDtmfRecognitionAsync(new PhoneNumberIdentifier(c2Target), "dtmf-reco-on-c2");

アプリケーションで参加者から DTMF トーンをこれ以上受信したくない場合は、StopContinuousDtmfRecognitionAsync メソッドを使用して Azure Communication Services に DTMF トーンの検出を停止するよう知らせることができます。

StopContinuousDtmfRecognitionAsync

参加者によって送信された DTMF トーンの検出を停止します。

var continuousDtmfRecognitionOptions = new ContinuousDtmfRecognitionOptions(new PhoneNumberIdentifier(callerPhonenumber)) 
{ 
    OperationContext = "dtmf-reco-on-c2" 
}; 

var startContinuousDtmfRecognitionAsyncResult = await callAutomationClient.GetCallConnection(callConnectionId) 
    .GetCallMedia() 
    .StartContinuousDtmfRecognitionAsync(continuousDtmfRecognitionOptions);

アプリケーションがイベント更新を受信するのは、これらのアクションが成功したか失敗したときです。 これらのイベントを使用してカスタム ビジネス ロジックを構築して、これらのイベント更新を受け取ったときアプリケーションがとるべき次のステップ を構成できます。

ContinuousDtmfRecognitionToneReceived イベント

正常に検出された DTMF トーンをどう処理するかの例。

if (acsEvent is ContinuousDtmfRecognitionToneReceived continuousDtmfRecognitionToneReceived) 
{ 
	logger.LogInformation("Tone detected: sequenceId={sequenceId}, tone={tone}", 
	continuousDtmfRecognitionToneReceived.SequenceId, 
        continuousDtmfRecognitionToneReceived.Tone); 
}

Azure Communication Services から ContinuousDtmfRecognitionToneReceived イベントの一部として SequenceId が提供され、アプリケーションはこれを使用して参加者が DTMF トーンを入力した順序を再構築できます。

ContinuousDtmfRecognitionFailed イベント

DTMF トーン検出が失敗したときどのように処理するかの例。

if (acsEvent is ContinuousDtmfRecognitionToneFailed continuousDtmfRecognitionToneFailed) 
{ 
    logger.LogInformation("Start continuous DTMF recognition failed, result={result}, context={context}", 
        continuousDtmfRecognitionToneFailed.ResultInformation?.Message, 
        continuousDtmfRecognitionToneFailed.OperationContext); 
}

ContinuousDtmfRecogntionStopped イベント

継続的 DTMF 認識が停止したときどう処理するかの例。停止の理由は、アプリケーションが StopContinuousDtmfRecognitionAsync イベントを呼び出したか、あるいは呼び出しが終了したことが考えられます。

if (acsEvent is ContinuousDtmfRecognitionStopped continuousDtmfRecognitionStopped) 
{ 
    logger.LogInformation("Continuous DTMF recognition stopped, context={context}", continuousDtmfRecognitionStopped.OperationContext); 
}

Hold

保留アクションを使用すると、開発者は参加者とシステムまたはエージェント間の会話を一時停止できます。 これは、参加者を別のエージェントまたは部署に転送する必要があるシナリオで、またはエージェントが会話を続ける前にバックグラウンドでスーパーバイザーと相談する必要がある場合に役立ちます。 この間、保留中の参加者に音声が聞こえるようにすることを選択できます。

// Option 1: Hold without additional options
await callAutomationClient.GetCallConnection(callConnectionId)
    .GetCallMedia().HoldAsync(c2Target);

/*
// Option 2: Hold with play source
PlaySource playSource = /* initialize playSource */;
await callAutomationClient.GetCallConnection(callConnectionId)
    .GetCallMedia().HoldAsync(c2Target, playSource);

// Option 3: Hold with options
var holdOptions = new HoldOptions(target) 
{ 
    OperationCallbackUri = new Uri(""),
    OperationContext = "holdcontext"
};
await callMedia.HoldAsync(holdOptions);
*/

保留解除

保留アクションを使用すると、開発者は以前に一時停止した、参加者とシステムまたはエージェント間の会話を再開できます。 参加者の保留が解除されると、システムまたはエージェントの音声が再び聞こえるようになります。

var unHoldOptions = new UnholdOptions(target) 
{ 
    OperationContext = "UnHoldPstnParticipant" 
}; 

// Option 1
var UnHoldParticipant = await callMedia.UnholdAsync(unHoldOptions);

/* 
// Option 2
var UnHoldParticipant = await callMedia.UnholdAsync(target);
*/

オーディオ ストリーミング (パブリック プレビュー)

オーディオ ストリーミングを使用すると、進行中の通話からリアルタイムのオーディオ ストリームをサブスクライブできます。 オーディオ ストリーミングの使用を開始する方法の詳細なガイダンスと、オーディオ ストリーミング コールバック イベントに関する情報については、このページを参照してください。

リアルタイム文字起こし (パブリック プレビュー)

リアルタイム文字起こしを使用すると、進行中の通話の音声のライブ文字起こしにアクセスできます。 リアルタイム文字起こしの使用を開始する方法の詳細なガイダンスと、リアルタイム文字起こしコールバック イベントに関する情報については、このページを参照してください。

メディア アクションの互換性テーブル

次の表は、直前の操作がまだ実行中またはキューに入っている場合に実行/キューに入れることが許可されているメディア アクションを示しています。

既存の操作 通話レッグ 許可 不許可
PlayToAll メイン PlayToAll、Recognize(Non-Group Call)、PlayTo、Recognize(Group Call)、SendDTMF、StartContinuousDtmfRecognition なし
Recognize(Non-Group Call) メイン PlayToAll、Recognize(Non-Group Call)、PlayTo、Recognize(Group Call)、SendDTMF、StartContinuousDtmfRecognition なし
PlayTo Sub PlayToAll、Recognize(Non-Group Call) PlayTo、Recognize(Group Call)、SendDTMF、StartContinuousDtmfRecognition
Recognize(Group Call) Sub PlayToAll、Recognize(Non-Group Call) PlayTo、Recognize(Group Call)、SendDTMF、StartContinuousDtmfRecognition
SendDTMF Sub PlayToAll、Recognize(Non-Group Call) PlayTo、Recognize(Group Call)、SendDTMF、StartContinuousDtmfRecognition
StartContinuousDtmfRecognition Sub PlayToAll、Recognize(Non-Group Call)、PlayTo、Recognize(Group Call)、SendDTMF、StartContinuousDtmfRecognition なし