如何透過通話自動化控制通話中媒體動作

  • 發行項

通話自動化會使用 REST API 介面來接收動作要求，並提供回應以通知是否有成功提交要求。 由於通話的非同步本質，大部分動作都會在動作順利完成或失敗時觸發對應的事件。 本指南涵蓋開發人員可在通話期間使用的動作，例如傳送 DTMF 和連續 DTMF 辨識。 動作隨附如何叫用所述動作的範例程式碼。

通話自動化還支援其他各種動作，這些動作可用來管理本指南未包含的通話和錄音。

注意

通話自動化目前無法與 Microsoft Teams 交互操作。 不支援使用通話自動化與 Teams 使用者通話、將通話重新導向他們，或對他們播放音訊等動作。

作為必要條件，建議您閱讀下列文章，以充分利用本指南：

  1. 通話自動化概念指南，會說明動作事件程式設計模型和事件回呼。
  2. 了解本指南中使用的使用者識別碼，例如 CommunicationUserIdentifier 和 PhoneNumberIdentifier。
  3. 深入了解如何使用通話自動化來控制和引導通話，這會教導您如何處理通話的基本概念。

在所有程式碼範例中，client 是 CallAutomationClient 物件，可以如所示加以建立，callConnection 則是從 Answer 或 CreateCall 回應取得的 CallConnection 物件。 您也可以從應用程式收到的回呼事件來取得。

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

傳送 DTMF

您可以將 DTMF 音調傳送給外部參與者，這在您已在通話時很有用，而且需要邀請另一位有分機號碼或有 IVR 功能表可瀏覽的參與者。

注意

這僅支援外部 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 通訊服務知道停止偵測 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 通訊服務提供 SequenceId 作為 ContinuousDtmfRecognitionToneReceived 事件的一部分，您的應用程式可用來重新建構參與者輸入 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); 
}