使用「辨識」動作收集使用者輸入

發行項
09/26/2024

本指南會協助您開始透過 Azure 通訊服務通話自動化 SDK 來辨識參與者所提供的 DTMF 輸入。

必要條件

包含使用中訂用帳戶的 Azure 帳戶。如需詳細資料，請參閱建立免費帳戶。
Azure 通訊服務資源。請參閱建立 Azure 通訊服務資源。請注意此資源的連接字串。
使用呼叫自動化 SDK 來建立新的 Web 服務應用程式。
您作業系統適用的最新 .NET 程式庫。
最新的 NuGet 封裝。

針對 AI 功能

建立 Azure AI 服務並將其連線至您的 Azure 通訊服務資源。
為您的 Azure AI 服務資源建立自訂子網域。

技術規格

下列參數可用來自訂 Recognize 函式：

參數	類型	預設值 (如果未指定)	描述	必要或選用
`Prompt` (如需詳細資料，請參閱使用「播放」動作自訂使用者語音提示(英文))	FileSource、TextSource	未設定	在辨識輸入之前播放的訊息。	選擇性
`InterToneTimeout`	TimeSpan	2 秒最小值：1 秒最大值：60 秒	Azure 通訊服務等候來電者按下另一個數字的秒數限制 (數字間逾時)。	選擇性
`InitialSegmentationSilenceTimeoutInSeconds`	整數	0.5 秒	辨識動作將輸入視為逾時之前等待輸入的時間長度。請參閱如何辨識語音 (英文)。	選擇性
`RecognizeInputsType`	列舉	dtmf	辨識的輸入類型。選項為 `dtmf`、`choices`、`speech` 和 `speechordtmf`。	必要
`InitialSilenceTimeout`	TimeSpan	5 秒鐘最小值：0 秒最大值：300 秒 (DTMF) 最大值：20 秒 (Choices) 最大值：20 秒 (Speech)	初始無聲逾時會調整在辨識嘗試結束於「無相符項」結果之前，在片語之前允許多少非語音音訊。請參閱如何辨識語音 (英文)。	選擇性
`MaxTonesToCollect`	整數	無預設值最小值1	開發人員預期參與者輸入的數字數目。	必要
`StopTones`	IEnumeration<DtmfTone>	未設定	參與者可以按下以逸出批次 DTMF 事件的數字。	選擇性
`InterruptPrompt`	Bool	True	如果參與者按下數字，就能夠中斷 playMessage。	選擇性
`InterruptCallMediaOperation`	Bool	True	如果設定此旗標，則會中斷目前的通話媒體作業。例如，如果正在播放任何音訊，則會中斷該作業並起始辨識。	選擇性
`OperationContext`	String	未設定	開發人員可以傳遞中間動作的字串，適合讓開發人員儲存他們所接收事件的相關內容。	選擇性
`Phrases`	String	未設定	與標籤相關聯片語的清單。聽到上述任何片語即表示成功辨識。	必要
`Tone`	String	未設定	使用者決定按數字而不是使用語音時所辨識的音調。	選擇性
`Label`	String	未設定	辨識的關鍵值。	必要
`Language`	String	En-us	用於辨識語音的語言。	選擇性
`EndSilenceTimeout`	TimeSpan	0.5 秒	說話者的最後暫停，用來偵測產生為語音的最終結果。	選擇性

注意

在 DTMF 和語音皆位於 recognizeInputsType 的情況下，辨識動作會作用於所收到的第一個輸入類型。例如，如果使用者先按下鍵盤號碼，則辨識動作會將其視為 DTMF 事件，並繼續接聽 DTMF 音調。如果使用者先說話，則辨識動作會將其視為語音辨識事件，並接聽語音輸入。

建立新的 C# 應用程式

在作業系統的主控台視窗中，使用 dotnet 命令建立新的 Web 應用程式。

dotnet new web -n MyApplication

安裝 NuGet 封裝

從 NuGet 資源庫 | Azure.Communication.CallAutomation (英文) 取得 NuGet 套件。請遵循下列指示來安裝套件。

建立通話

此時，您應該熟悉啟動通話。如需撥打電話的詳細資訊，請參閱快速入門：撥打電話和撥出通話 (英文)。您也可以使用這裡提供的程式碼片段來了解如何接聽來電。

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

var answerCallOptions = new AnswerCallOptions("<Incoming call context once call is connected>", new Uri("<https://sample-callback-uri>"))  
{  
    CallIntelligenceOptions = new CallIntelligenceOptions() { CognitiveServicesEndpoint = new Uri("<Azure Cognitive Services Endpoint>") } 
};  

var answerCallResult = await callAutomationClient.AnswerCallAsync(answerCallOptions);

呼叫辨識動作

當應用程式接聽來電時，您可以提供有關辨識參與者輸入和播放提示的資訊。

DTMF

var maxTonesToCollect = 3;
String textToPlay = "Welcome to Contoso, please enter 3 DTMF.";
var playSource = new TextSource(textToPlay, "en-US-ElizabethNeural");
var recognizeOptions = new CallMediaRecognizeDtmfOptions(targetParticipant, maxTonesToCollect) {
  InitialSilenceTimeout = TimeSpan.FromSeconds(30),
    Prompt = playSource,
    InterToneTimeout = TimeSpan.FromSeconds(5),
    InterruptPrompt = true,
    StopTones = new DtmfTone[] {
      DtmfTone.Pound
    },
};
var recognizeResult = await callAutomationClient.GetCallConnection(callConnectionId)
  .GetCallMedia()
  .StartRecognizingAsync(recognizeOptions);

對於語音轉換文字流程，通話自動化辨識動作也支援使用自訂語音模型 (英文)。當您建置的應用程式需要接聽預設語音轉換文字模型可能無法理解的複雜文字時，自訂語音模型之類的功能就會很有用。其中一個範例是當您建置遠端醫療產業的應用程式，而您的虛擬助理必須能夠辨識醫療詞彙。您可以在建立自訂語音專案 (英文) 中深入了解。

語音轉換文字選項

var choices = new List < RecognitionChoice > {
  new RecognitionChoice("Confirm", new List < string > {
    "Confirm",
    "First",
    "One"
  }) {
    Tone = DtmfTone.One
  },
  new RecognitionChoice("Cancel", new List < string > {
    "Cancel",
    "Second",
    "Two"
  }) {
    Tone = DtmfTone.Two
  }
};
String textToPlay = "Hello, This is a reminder for your appointment at 2 PM, Say Confirm to confirm your appointment or Cancel to cancel the appointment. Thank you!";

var playSource = new TextSource(textToPlay, "en-US-ElizabethNeural");
var recognizeOptions = new CallMediaRecognizeChoiceOptions(targetParticipant, choices) {
  InterruptPrompt = true,
    InitialSilenceTimeout = TimeSpan.FromSeconds(30),
    Prompt = playSource,
    OperationContext = "AppointmentReminderMenu",
    //Only add the SpeechModelEndpointId if you have a custom speech model you would like to use
    SpeechModelEndpointId = "YourCustomSpeechModelEndpointId"
};
var recognizeResult = await callAutomationClient.GetCallConnection(callConnectionId)
  .GetCallMedia()
  .StartRecognizingAsync(recognizeOptions);

語音轉換文字

String textToPlay = "Hi, how can I help you today?";
var playSource = new TextSource(textToPlay, "en-US-ElizabethNeural");
var recognizeOptions = new CallMediaRecognizeSpeechOptions(targetParticipant) {
  Prompt = playSource,
    EndSilenceTimeout = TimeSpan.FromMilliseconds(1000),
    OperationContext = "OpenQuestionSpeech",
    //Only add the SpeechModelEndpointId if you have a custom speech model you would like to use
    SpeechModelEndpointId = "YourCustomSpeechModelEndpointId"
};
var recognizeResult = await callAutomationClient.GetCallConnection(callConnectionId)
  .GetCallMedia()
  .StartRecognizingAsync(recognizeOptions);

語音轉換文字或 DTMF

var maxTonesToCollect = 1; 
String textToPlay = "Hi, how can I help you today, you can press 0 to speak to an agent?"; 
var playSource = new TextSource(textToPlay, "en-US-ElizabethNeural"); 
var recognizeOptions = new CallMediaRecognizeSpeechOrDtmfOptions(targetParticipant, maxTonesToCollect) 
{ 
    Prompt = playSource, 
    EndSilenceTimeout = TimeSpan.FromMilliseconds(1000), 
    InitialSilenceTimeout = TimeSpan.FromSeconds(30), 
    InterruptPrompt = true, 
    OperationContext = "OpenQuestionSpeechOrDtmf",
    //Only add the SpeechModelEndpointId if you have a custom speech model you would like to use
    SpeechModelEndpointId = "YourCustomSpeechModelEndpointId" 
}; 
var recognizeResult = await callAutomationClient.GetCallConnection(callConnectionId) 
    .GetCallMedia() 
    .StartRecognizingAsync(recognizeOptions);

注意

若未設定參數，則會在可行時套用預設值。

接收辨識事件更新

開發人員可以在已註冊的 Webhook 回呼上訂閱 RecognizeCompleted 和 RecognizeFailed 事件。使用此回呼可與應用程式中的商務邏輯搭配使用，以判斷其中一個事件發生時的後續步驟。

如何還原序列化 RecognizeCompleted 事件的範例：

if (acsEvent is RecognizeCompleted recognizeCompleted) 
{ 
    switch (recognizeCompleted.RecognizeResult) 
    { 
        case DtmfResult dtmfResult: 
            //Take action for Recognition through DTMF 
            var tones = dtmfResult.Tones; 
            logger.LogInformation("Recognize completed succesfully, tones={tones}", tones); 
            break; 
        case ChoiceResult choiceResult: 
            // Take action for Recognition through Choices 
            var labelDetected = choiceResult.Label; 
            var phraseDetected = choiceResult.RecognizedPhrase; 
            // If choice is detected by phrase, choiceResult.RecognizedPhrase will have the phrase detected, 
            // If choice is detected using dtmf tone, phrase will be null 
            logger.LogInformation("Recognize completed succesfully, labelDetected={labelDetected}, phraseDetected={phraseDetected}", labelDetected, phraseDetected);
            break; 
        case SpeechResult speechResult: 
            // Take action for Recognition through Choices 
            var text = speechResult.Speech; 
            logger.LogInformation("Recognize completed succesfully, text={text}", text); 
            break; 
        default: 
            logger.LogInformation("Recognize completed succesfully, recognizeResult={recognizeResult}", recognizeCompleted.RecognizeResult); 
            break; 
    } 
}

如何還原序列化 RecognizeFailed 事件的範例：

if (acsEvent is RecognizeFailed recognizeFailed) 
{ 
    if (MediaEventReasonCode.RecognizeInitialSilenceTimedOut.Equals(recognizeFailed.ReasonCode)) 
    { 
        // Take action for time out 
        logger.LogInformation("Recognition failed: initial silencev time out"); 
    } 
    else if (MediaEventReasonCode.RecognizeSpeechOptionNotMatched.Equals(recognizeFailed.ReasonCode)) 
    { 
        // Take action for option not matched 
        logger.LogInformation("Recognition failed: speech option not matched"); 
    } 
    else if (MediaEventReasonCode.RecognizeIncorrectToneDetected.Equals(recognizeFailed.ReasonCode)) 
    { 
        // Take action for incorrect tone 
        logger.LogInformation("Recognition failed: incorrect tone detected"); 
    } 
    else 
    { 
        logger.LogInformation("Recognition failed, result={result}, context={context}", recognizeFailed.ResultInformation?.Message, recognizeFailed.OperationContext); 
    } 
}

如何還原序列化 RecognizeCanceled 事件的範例：

if (acsEvent is RecognizeCanceled { OperationContext: "AppointmentReminderMenu" })
        {
            logger.LogInformation($"RecognizeCanceled event received for call connection id: {@event.CallConnectionId}");
            //Take action on recognize canceled operation
           await callConnection.HangUpAsync(forEveryone: true);
        }

必要條件

包含使用中訂用帳戶的 Azure 帳戶。如需詳細資料，請參閱建立免費帳戶。
Azure 通訊服務資源。請參閱建立 Azure 通訊服務資源
使用通話自動化 SDK 來建立新的 Web 服務應用程式。
JAVA 開發套件第 8 版或更新版本。
Apache Maven。

針對 AI 功能

建立 Azure AI 服務並將其連線至您的 Azure 通訊服務資源。
為您的 Azure AI 服務資源建立自訂子網域。

技術規格

下列參數可用來自訂 Recognize 函式：

參數	類型	預設值 (如果未指定)	描述	必要或選用
`Prompt` (如需詳細資料，請參閱使用「播放」動作自訂使用者語音提示(英文))	FileSource、TextSource	未設定	在辨識輸入之前播放的訊息。	選擇性
`InterToneTimeout`	TimeSpan	2 秒最小值：1 秒最大值：60 秒	Azure 通訊服務等候來電者按下另一個數字的秒數限制 (數字間逾時)。	選擇性
`InitialSegmentationSilenceTimeoutInSeconds`	整數	0.5 秒	辨識動作將輸入視為逾時之前等待輸入的時間長度。請參閱如何辨識語音 (英文)。	選擇性
`RecognizeInputsType`	列舉	dtmf	辨識的輸入類型。選項為 `dtmf`、`choices`、`speech` 和 `speechordtmf`。	必要
`InitialSilenceTimeout`	TimeSpan	5 秒鐘最小值：0 秒最大值：300 秒 (DTMF) 最大值：20 秒 (Choices) 最大值：20 秒 (Speech)	初始無聲逾時會調整在辨識嘗試結束於「無相符項」結果之前，在片語之前允許多少非語音音訊。請參閱如何辨識語音 (英文)。	選擇性
`MaxTonesToCollect`	整數	無預設值最小值1	開發人員預期參與者輸入的數字數目。	必要
`StopTones`	IEnumeration<DtmfTone>	未設定	參與者可以按下以逸出批次 DTMF 事件的數字。	選擇性
`InterruptPrompt`	Bool	True	如果參與者按下數字，就能夠中斷 playMessage。	選擇性
`InterruptCallMediaOperation`	Bool	True	如果設定此旗標，則會中斷目前的通話媒體作業。例如，如果正在播放任何音訊，則會中斷該作業並起始辨識。	選擇性
`OperationContext`	String	未設定	開發人員可以傳遞中間動作的字串，適合讓開發人員儲存他們所接收事件的相關內容。	選擇性
`Phrases`	String	未設定	與標籤相關聯片語的清單。聽到上述任何片語即表示成功辨識。	必要
`Tone`	String	未設定	使用者決定按數字而不是使用語音時所辨識的音調。	選擇性
`Label`	String	未設定	辨識的關鍵值。	必要
`Language`	String	En-us	用於辨識語音的語言。	選擇性
`EndSilenceTimeout`	TimeSpan	0.5 秒	說話者的最後暫停，用來偵測產生為語音的最終結果。	選擇性

注意

建立新的 Java 應用程式

在您的終端機或命令視窗中，瀏覽至您想要在其中建立 JAVA 應用程式的目錄。執行 mvn 命令以從 maven-archetype-quickstart 範本產生 Java 專案。

mvn archetype:generate -DgroupId=com.communication.quickstart -DartifactId=communication-quickstart -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false

mvn 命令會建立與 artifactId 引數相同名稱的目錄。 src/main/java 目錄包含專案原始程式碼。 src/test/java 目錄包含測試測試。

請注意，generate 步驟建立了與 artifactId 相同名稱的目錄。 src/main/java 目錄包含原始程式碼。 src/test/java 目錄包含測試。 pom.xml 檔案是專案的專案物件模型 (POM)。

將應用程式的 POM 檔案更新為使用 JAVA 8 或更高版本。

<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.source>1.8</maven.compiler.source>
    <maven.compiler.target>1.8</maven.compiler.target>
</properties>

新增套件參考

在您的 POM 檔案中，針對專案新增下列參考：

azure-communication-callautomation

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-communication-callautomation</artifactId>
  <version>1.0.0</version>
</dependency>

建立通話

CallIntelligenceOptions callIntelligenceOptions = new CallIntelligenceOptions().setCognitiveServicesEndpoint("https://sample-cognitive-service-resource.cognitiveservices.azure.com/"); 
answerCallOptions = new AnswerCallOptions("<Incoming call context>", "<https://sample-callback-uri>").setCallIntelligenceOptions(callIntelligenceOptions); 
Response < AnswerCallResult > answerCallResult = callAutomationClient
  .answerCallWithResponse(answerCallOptions)
  .block();

呼叫辨識動作

當應用程式接聽來電時，您可以提供有關辨識參與者輸入和播放提示的資訊。

DTMF

var maxTonesToCollect = 3;
String textToPlay = "Welcome to Contoso, please enter 3 DTMF.";
var playSource = new TextSource() 
    .setText(textToPlay) 
    .setVoiceName("en-US-ElizabethNeural");

var recognizeOptions = new CallMediaRecognizeDtmfOptions(targetParticipant, maxTonesToCollect) 
    .setInitialSilenceTimeout(Duration.ofSeconds(30)) 
    .setPlayPrompt(playSource) 
    .setInterToneTimeout(Duration.ofSeconds(5)) 
    .setInterruptPrompt(true) 
    .setStopTones(Arrays.asList(DtmfTone.POUND));

var recognizeResponse = callAutomationClient.getCallConnectionAsync(callConnectionId) 
    .getCallMediaAsync() 
    .startRecognizingWithResponse(recognizeOptions) 
    .block(); 

log.info("Start recognizing result: " + recognizeResponse.getStatusCode());

語音轉換文字選項

var choices = Arrays.asList(
  new RecognitionChoice()
  .setLabel("Confirm")
  .setPhrases(Arrays.asList("Confirm", "First", "One"))
  .setTone(DtmfTone.ONE),
  new RecognitionChoice()
  .setLabel("Cancel")
  .setPhrases(Arrays.asList("Cancel", "Second", "Two"))
  .setTone(DtmfTone.TWO)
);

String textToPlay = "Hello, This is a reminder for your appointment at 2 PM, Say Confirm to confirm your appointment or Cancel to cancel the appointment. Thank you!";
var playSource = new TextSource()
  .setText(textToPlay)
  .setVoiceName("en-US-ElizabethNeural");
var recognizeOptions = new CallMediaRecognizeChoiceOptions(targetParticipant, choices)
  .setInterruptPrompt(true)
  .setInitialSilenceTimeout(Duration.ofSeconds(30))
  .setPlayPrompt(playSource)
  .setOperationContext("AppointmentReminderMenu")
  //Only add the SpeechRecognitionModelEndpointId if you have a custom speech model you would like to use
  .setSpeechRecognitionModelEndpointId("YourCustomSpeechModelEndpointID"); 
var recognizeResponse = callAutomationClient.getCallConnectionAsync(callConnectionId)
  .getCallMediaAsync()
  .startRecognizingWithResponse(recognizeOptions)
  .block();

語音轉換文字

String textToPlay = "Hi, how can I help you today?"; 
var playSource = new TextSource() 
    .setText(textToPlay) 
    .setVoiceName("en-US-ElizabethNeural"); 
var recognizeOptions = new CallMediaRecognizeSpeechOptions(targetParticipant, Duration.ofMillis(1000)) 
    .setPlayPrompt(playSource) 
    .setOperationContext("OpenQuestionSpeech")
    //Only add the SpeechRecognitionModelEndpointId if you have a custom speech model you would like to use
    .setSpeechRecognitionModelEndpointId("YourCustomSpeechModelEndpointID");  
var recognizeResponse = callAutomationClient.getCallConnectionAsync(callConnectionId) 
    .getCallMediaAsync() 
    .startRecognizingWithResponse(recognizeOptions) 
    .block();

語音轉換文字或 DTMF

var maxTonesToCollect = 1; 
String textToPlay = "Hi, how can I help you today, you can press 0 to speak to an agent?"; 
var playSource = new TextSource() 
    .setText(textToPlay) 
    .setVoiceName("en-US-ElizabethNeural"); 
var recognizeOptions = new CallMediaRecognizeSpeechOrDtmfOptions(targetParticipant, maxTonesToCollect, Duration.ofMillis(1000)) 
    .setPlayPrompt(playSource) 
    .setInitialSilenceTimeout(Duration.ofSeconds(30)) 
    .setInterruptPrompt(true) 
    .setOperationContext("OpenQuestionSpeechOrDtmf")
    //Only add the SpeechRecognitionModelEndpointId if you have a custom speech model you would like to use
    .setSpeechRecognitionModelEndpointId("YourCustomSpeechModelEndpointID");  
var recognizeResponse = callAutomationClient.getCallConnectionAsync(callConnectionId) 
    .getCallMediaAsync() 
    .startRecognizingWithResponse(recognizeOptions) 
    .block();

注意

若未設定參數，則會在可行時套用預設值。

接收辨識事件更新

如何還原序列化 RecognizeCompleted 事件的範例：

if (acsEvent instanceof RecognizeCompleted) { 
    RecognizeCompleted event = (RecognizeCompleted) acsEvent; 
    RecognizeResult recognizeResult = event.getRecognizeResult().get(); 
    if (recognizeResult instanceof DtmfResult) { 
        // Take action on collect tones 
        DtmfResult dtmfResult = (DtmfResult) recognizeResult; 
        List<DtmfTone> tones = dtmfResult.getTones(); 
        log.info("Recognition completed, tones=" + tones + ", context=" + event.getOperationContext()); 
    } else if (recognizeResult instanceof ChoiceResult) { 
        ChoiceResult collectChoiceResult = (ChoiceResult) recognizeResult; 
        String labelDetected = collectChoiceResult.getLabel(); 
        String phraseDetected = collectChoiceResult.getRecognizedPhrase(); 
        log.info("Recognition completed, labelDetected=" + labelDetected + ", phraseDetected=" + phraseDetected + ", context=" + event.getOperationContext()); 
    } else if (recognizeResult instanceof SpeechResult) { 
        SpeechResult speechResult = (SpeechResult) recognizeResult; 
        String text = speechResult.getSpeech(); 
        log.info("Recognition completed, text=" + text + ", context=" + event.getOperationContext()); 
    } else { 
        log.info("Recognition completed, result=" + recognizeResult + ", context=" + event.getOperationContext()); 
    } 
}

如何還原序列化 RecognizeFailed 事件的範例：

if (acsEvent instanceof RecognizeFailed) { 
    RecognizeFailed event = (RecognizeFailed) acsEvent; 
    if (ReasonCode.Recognize.INITIAL_SILENCE_TIMEOUT.equals(event.getReasonCode())) { 
        // Take action for time out 
        log.info("Recognition failed: initial silence time out"); 
    } else if (ReasonCode.Recognize.SPEECH_OPTION_NOT_MATCHED.equals(event.getReasonCode())) { 
        // Take action for option not matched 
        log.info("Recognition failed: speech option not matched"); 
    } else if (ReasonCode.Recognize.DMTF_OPTION_MATCHED.equals(event.getReasonCode())) { 
        // Take action for incorrect tone 
        log.info("Recognition failed: incorrect tone detected"); 
    } else { 
        log.info("Recognition failed, result=" + event.getResultInformation().getMessage() + ", context=" + event.getOperationContext()); 
    } 
}

如何還原序列化 RecognizeCanceled 事件的範例：

if (acsEvent instanceof RecognizeCanceled) { 
    RecognizeCanceled event = (RecognizeCanceled) acsEvent; 
    log.info("Recognition canceled, context=" + event.getOperationContext()); 
}

必要條件

包含使用中訂用帳戶的 Azure 帳戶。如需詳細資料，請參閱建立免費帳戶。
Azure 通訊服務資源。請參閱建立 Azure 通訊服務資源。請注意此資源的連接字串。
使用通話自動化 SDK 來建立新的 Web 服務應用程式。
安裝 Node.js 後，您可以從官方網站進行安裝。

針對 AI 功能

建立 Azure AI 服務並將其連線至您的 Azure 通訊服務資源。
為您的 Azure AI 服務資源建立自訂子網域。

技術規格

下列參數可用來自訂 Recognize 函式：

參數	類型	預設值 (如果未指定)	描述	必要或選用
`Prompt` (如需詳細資料，請參閱使用「播放」動作自訂使用者語音提示(英文))	FileSource、TextSource	未設定	在辨識輸入之前播放的訊息。	選擇性
`InterToneTimeout`	TimeSpan	2 秒最小值：1 秒最大值：60 秒	Azure 通訊服務等候來電者按下另一個數字的秒數限制 (數字間逾時)。	選擇性
`InitialSegmentationSilenceTimeoutInSeconds`	整數	0.5 秒	辨識動作將輸入視為逾時之前等待輸入的時間長度。請參閱如何辨識語音 (英文)。	選擇性
`RecognizeInputsType`	列舉	dtmf	辨識的輸入類型。選項為 `dtmf`、`choices`、`speech` 和 `speechordtmf`。	必要
`InitialSilenceTimeout`	TimeSpan	5 秒鐘最小值：0 秒最大值：300 秒 (DTMF) 最大值：20 秒 (Choices) 最大值：20 秒 (Speech)	初始無聲逾時會調整在辨識嘗試結束於「無相符項」結果之前，在片語之前允許多少非語音音訊。請參閱如何辨識語音 (英文)。	選擇性
`MaxTonesToCollect`	整數	無預設值最小值1	開發人員預期參與者輸入的數字數目。	必要
`StopTones`	IEnumeration<DtmfTone>	未設定	參與者可以按下以逸出批次 DTMF 事件的數字。	選擇性
`InterruptPrompt`	Bool	True	如果參與者按下數字，就能夠中斷 playMessage。	選擇性
`InterruptCallMediaOperation`	Bool	True	如果設定此旗標，則會中斷目前的通話媒體作業。例如，如果正在播放任何音訊，則會中斷該作業並起始辨識。	選擇性
`OperationContext`	String	未設定	開發人員可以傳遞中間動作的字串，適合讓開發人員儲存他們所接收事件的相關內容。	選擇性
`Phrases`	String	未設定	與標籤相關聯片語的清單。聽到上述任何片語即表示成功辨識。	必要
`Tone`	String	未設定	使用者決定按數字而不是使用語音時所辨識的音調。	選擇性
`Label`	String	未設定	辨識的關鍵值。	必要
`Language`	String	En-us	用於辨識語音的語言。	選擇性
`EndSilenceTimeout`	TimeSpan	0.5 秒	說話者的最後暫停，用來偵測產生為語音的最終結果。	選擇性

注意

建立新的 JavaScript 應用程式

在您的專案目錄中建立新的 JavaScript 應用程式。使用下列命令初始化新的 Node.js 專案。這會為您的專案建立 package.json 檔案，可管理專案的相依性。

npm init -y

安裝 Azure 通訊服務通話自動化套件

npm install @azure/communication-call-automation

例如，在您的專案目錄中建立新的 JavaScript 檔案，將其命名為 app.js。在此檔案中撰寫 JavaScript 程式碼。

搭配使用 Node.js 與下列命令執行您的應用程式。

node app.js

建立通話

此時，您應該熟悉啟動通話。如需撥打電話的詳細資訊，請參閱快速入門：撥打電話和撥出通話 (英文)。

呼叫辨識動作

當應用程式接聽來電時，您可以提供有關辨識參與者輸入和播放提示的資訊。

DTMF

const maxTonesToCollect = 3; 
const textToPlay = "Welcome to Contoso, please enter 3 DTMF."; 
const playSource: TextSource = { text: textToPlay, voiceName: "en-US-ElizabethNeural", kind: "textSource" }; 
const recognizeOptions: CallMediaRecognizeDtmfOptions = { 
    maxTonesToCollect: maxTonesToCollect, 
    initialSilenceTimeoutInSeconds: 30, 
    playPrompt: playSource, 
    interToneTimeoutInSeconds: 5, 
    interruptPrompt: true, 
    stopDtmfTones: [ DtmfTone.Pound ], 
    kind: "callMediaRecognizeDtmfOptions" 
}; 

await callAutomationClient.getCallConnection(callConnectionId) 
    .getCallMedia() 
    .startRecognizing(targetParticipant, recognizeOptions);

語音轉換文字選項

const choices = [ 
    {  
        label: "Confirm", 
        phrases: [ "Confirm", "First", "One" ], 
        tone: DtmfTone.One 
    }, 
    { 
        label: "Cancel", 
        phrases: [ "Cancel", "Second", "Two" ], 
        tone: DtmfTone.Two 
    } 
]; 

const textToPlay = "Hello, This is a reminder for your appointment at 2 PM, Say Confirm to confirm your appointment or Cancel to cancel the appointment. Thank you!"; 
const playSource: TextSource = { text: textToPlay, voiceName: "en-US-ElizabethNeural", kind: "textSource" }; 
const recognizeOptions: CallMediaRecognizeChoiceOptions = { 
    choices: choices, 
    interruptPrompt: true, 
    initialSilenceTimeoutInSeconds: 30, 
    playPrompt: playSource, 
    operationContext: "AppointmentReminderMenu", 
    kind: "callMediaRecognizeChoiceOptions",
    //Only add the speechRecognitionModelEndpointId if you have a custom speech model you would like to use
    speechRecognitionModelEndpointId: "YourCustomSpeechEndpointId"
}; 

await callAutomationClient.getCallConnection(callConnectionId) 
    .getCallMedia() 
    .startRecognizing(targetParticipant, recognizeOptions);

語音轉換文字

const textToPlay = "Hi, how can I help you today?"; 
const playSource: TextSource = { text: textToPlay, voiceName: "en-US-ElizabethNeural", kind: "textSource" }; 
const recognizeOptions: CallMediaRecognizeSpeechOptions = { 
    endSilenceTimeoutInSeconds: 1, 
    playPrompt: playSource, 
    operationContext: "OpenQuestionSpeech", 
    kind: "callMediaRecognizeSpeechOptions",
    //Only add the speechRecognitionModelEndpointId if you have a custom speech model you would like to use
    speechRecognitionModelEndpointId: "YourCustomSpeechEndpointId"
}; 

await callAutomationClient.getCallConnection(callConnectionId) 
    .getCallMedia() 
    .startRecognizing(targetParticipant, recognizeOptions);

語音轉換文字或 DTMF

const maxTonesToCollect = 1; 
const textToPlay = "Hi, how can I help you today, you can press 0 to speak to an agent?"; 
const playSource: TextSource = { text: textToPlay, voiceName: "en-US-ElizabethNeural", kind: "textSource" }; 
const recognizeOptions: CallMediaRecognizeSpeechOrDtmfOptions = { 
    maxTonesToCollect: maxTonesToCollect, 
    endSilenceTimeoutInSeconds: 1, 
    playPrompt: playSource, 
    initialSilenceTimeoutInSeconds: 30, 
    interruptPrompt: true, 
    operationContext: "OpenQuestionSpeechOrDtmf", 
    kind: "callMediaRecognizeSpeechOrDtmfOptions",
    //Only add the speechRecognitionModelEndpointId if you have a custom speech model you would like to use
    speechRecognitionModelEndpointId: "YourCustomSpeechEndpointId"
}; 

await callAutomationClient.getCallConnection(callConnectionId) 
    .getCallMedia() 
    .startRecognizing(targetParticipant, recognizeOptions);

注意

若未設定參數，則會在可行時套用預設值。

接收辨識事件更新

如何還原序列化 RecognizeCompleted 事件的範例：

if (event.type === "Microsoft.Communication.RecognizeCompleted") { 
    if (eventData.recognitionType === "dtmf") { 
        const tones = eventData.dtmfResult.tones; 
        console.log("Recognition completed, tones=%s, context=%s", tones, eventData.operationContext); 
    } else if (eventData.recognitionType === "choices") { 
        const labelDetected = eventData.choiceResult.label; 
        const phraseDetected = eventData.choiceResult.recognizedPhrase; 
        console.log("Recognition completed, labelDetected=%s, phraseDetected=%s, context=%s", labelDetected, phraseDetected, eventData.operationContext); 
    } else if (eventData.recognitionType === "speech") { 
        const text = eventData.speechResult.speech; 
        console.log("Recognition completed, text=%s, context=%s", text, eventData.operationContext); 
    } else { 
        console.log("Recognition completed: data=%s", JSON.stringify(eventData, null, 2)); 
    } 
}

如何還原序列化 RecognizeFailed 事件的範例：

if (event.type === "Microsoft.Communication.RecognizeFailed") {
    console.log("Recognize failed: data=%s", JSON.stringify(eventData, null, 2));
}

如何還原序列化 RecognizeCanceled 事件的範例：

if (event.type === "Microsoft.Communication.RecognizeCanceled") {
    console.log("Recognize canceled, context=%s", eventData.operationContext);
}

必要條件

包含使用中訂用帳戶的 Azure 帳戶。如需詳細資料，請參閱建立免費帳戶。
Azure 通訊服務資源。請參閱建立 Azure 通訊服務資源。請注意此資源的連接字串。
使用通話自動化 SDK 來建立新的 Web 服務應用程式。
從 Python.org 安裝 Python。

針對 AI 功能

建立 Azure AI 服務並將其連線至您的 Azure 通訊服務資源。
為您的 Azure AI 服務資源建立自訂子網域。

技術規格

下列參數可用來自訂 Recognize 函式：

參數	類型	預設值 (如果未指定)	描述	必要或選用
`Prompt` (如需詳細資料，請參閱使用「播放」動作自訂使用者語音提示(英文))	FileSource、TextSource	未設定	在辨識輸入之前播放的訊息。	選擇性
`InterToneTimeout`	TimeSpan	2 秒最小值：1 秒最大值：60 秒	Azure 通訊服務等候來電者按下另一個數字的秒數限制 (數字間逾時)。	選擇性
`InitialSegmentationSilenceTimeoutInSeconds`	整數	0.5 秒	辨識動作將輸入視為逾時之前等待輸入的時間長度。請參閱如何辨識語音 (英文)。	選擇性
`RecognizeInputsType`	列舉	dtmf	辨識的輸入類型。選項為 `dtmf`、`choices`、`speech` 和 `speechordtmf`。	必要
`InitialSilenceTimeout`	TimeSpan	5 秒鐘最小值：0 秒最大值：300 秒 (DTMF) 最大值：20 秒 (Choices) 最大值：20 秒 (Speech)	初始無聲逾時會調整在辨識嘗試結束於「無相符項」結果之前，在片語之前允許多少非語音音訊。請參閱如何辨識語音 (英文)。	選擇性
`MaxTonesToCollect`	整數	無預設值最小值1	開發人員預期參與者輸入的數字數目。	必要
`StopTones`	IEnumeration<DtmfTone>	未設定	參與者可以按下以逸出批次 DTMF 事件的數字。	選擇性
`InterruptPrompt`	Bool	True	如果參與者按下數字，就能夠中斷 playMessage。	選擇性
`InterruptCallMediaOperation`	Bool	True	如果設定此旗標，則會中斷目前的通話媒體作業。例如，如果正在播放任何音訊，則會中斷該作業並起始辨識。	選擇性
`OperationContext`	String	未設定	開發人員可以傳遞中間動作的字串，適合讓開發人員儲存他們所接收事件的相關內容。	選擇性
`Phrases`	String	未設定	與標籤相關聯片語的清單。聽到上述任何片語即表示成功辨識。	必要
`Tone`	String	未設定	使用者決定按數字而不是使用語音時所辨識的音調。	選擇性
`Label`	String	未設定	辨識的關鍵值。	必要
`Language`	String	En-us	用於辨識語音的語言。	選擇性
`EndSilenceTimeout`	TimeSpan	0.5 秒	說話者的最後暫停，用來偵測產生為語音的最終結果。	選擇性

注意

建立新的 Python 應用程式

為您的專案設定 Python 虛擬環境

python -m venv play-audio-app

啟動虛擬環境

在 Windows 上，請使用下列命令：

.\ play-audio-quickstart \Scripts\activate

在 Unix 上，請使用下列命令：

source play-audio-quickstart /bin/activate

安裝 Azure 通訊服務通話自動化套件

pip install azure-communication-callautomation

例如，在您的專案目錄中建立應用程式檔案，將其命名為 app.py。在此檔案中撰寫 Python 程式碼。

搭配使用 Python 與下列命令執行您的應用程式。

python app.py

建立通話

此時，您應該熟悉啟動通話。如需撥打電話的詳細資訊，請參閱快速入門：撥打電話和撥出通話 (英文)。

呼叫辨識動作

當應用程式接聽來電時，您可以提供有關辨識參與者輸入和播放提示的資訊。

DTMF

max_tones_to_collect = 3 
text_to_play = "Welcome to Contoso, please enter 3 DTMF." 
play_source = TextSource(text=text_to_play, voice_name="en-US-ElizabethNeural") 
call_automation_client.get_call_connection(call_connection_id).start_recognizing_media( 
    dtmf_max_tones_to_collect=max_tones_to_collect, 
    input_type=RecognizeInputType.DTMF, 
    target_participant=target_participant, 
    initial_silence_timeout=30, 
    play_prompt=play_source, 
    dtmf_inter_tone_timeout=5, 
    interrupt_prompt=True, 
    dtmf_stop_tones=[ DtmfTone.Pound ])

語音轉換文字選項

choices = [ 
    RecognitionChoice( 
        label="Confirm", 
        phrases=[ "Confirm", "First", "One" ], 
        tone=DtmfTone.ONE 
    ), 
    RecognitionChoice( 
        label="Cancel", 
        phrases=[ "Cancel", "Second", "Two" ], 
        tone=DtmfTone.TWO 
    ) 
] 
text_to_play = "Hello, This is a reminder for your appointment at 2 PM, Say Confirm to confirm your appointment or Cancel to cancel the appointment. Thank you!" 
play_source = TextSource(text=text_to_play, voice_name="en-US-ElizabethNeural") 
call_automation_client.get_call_connection(call_connection_id).start_recognizing_media( 
    input_type=RecognizeInputType.CHOICES, 
    target_participant=target_participant, 
    choices=choices, 
    interrupt_prompt=True, 
    initial_silence_timeout=30, 
    play_prompt=play_source, 
    operation_context="AppointmentReminderMenu",
    # Only add the speech_recognition_model_endpoint_id if you have a custom speech model you would like to use
    speech_recognition_model_endpoint_id="YourCustomSpeechModelEndpointId")

語音轉換文字

text_to_play = "Hi, how can I help you today?" 
play_source = TextSource(text=text_to_play, voice_name="en-US-ElizabethNeural") 
call_automation_client.get_call_connection(call_connection_id).start_recognizing_media( 
    input_type=RecognizeInputType.SPEECH, 
    target_participant=target_participant, 
    end_silence_timeout=1, 
    play_prompt=play_source, 
    operation_context="OpenQuestionSpeech",
    # Only add the speech_recognition_model_endpoint_id if you have a custom speech model you would like to use
    speech_recognition_model_endpoint_id="YourCustomSpeechModelEndpointId")

語音轉換文字或 DTMF

max_tones_to_collect = 1 
text_to_play = "Hi, how can I help you today, you can also press 0 to speak to an agent." 
play_source = TextSource(text=text_to_play, voice_name="en-US-ElizabethNeural") 
call_automation_client.get_call_connection(call_connection_id).start_recognizing_media( 
    dtmf_max_tones_to_collect=max_tones_to_collect, 
    input_type=RecognizeInputType.SPEECH_OR_DTMF, 
    target_participant=target_participant, 
    end_silence_timeout=1, 
    play_prompt=play_source, 
    initial_silence_timeout=30, 
    interrupt_prompt=True, 
    operation_context="OpenQuestionSpeechOrDtmf",
    # Only add the speech_recognition_model_endpoint_id if you have a custom speech model you would like to use
    speech_recognition_model_endpoint_id="YourCustomSpeechModelEndpointId")  
app.logger.info("Start recognizing")

注意

若未設定參數，則會在可行時套用預設值。

接收辨識事件更新

如何還原序列化 RecognizeCompleted 事件的範例：

if event.type == "Microsoft.Communication.RecognizeCompleted": 
    app.logger.info("Recognize completed: data=%s", event.data) 
    if event.data['recognitionType'] == "dtmf": 
        tones = event.data['dtmfResult']['tones'] 
        app.logger.info("Recognition completed, tones=%s, context=%s", tones, event.data.get('operationContext')) 
    elif event.data['recognitionType'] == "choices": 
        labelDetected = event.data['choiceResult']['label']; 
        phraseDetected = event.data['choiceResult']['recognizedPhrase']; 
        app.logger.info("Recognition completed, labelDetected=%s, phraseDetected=%s, context=%s", labelDetected, phraseDetected, event.data.get('operationContext')); 
    elif event.data['recognitionType'] == "speech": 
        text = event.data['speechResult']['speech']; 
        app.logger.info("Recognition completed, text=%s, context=%s", text, event.data.get('operationContext')); 
    else: 
        app.logger.info("Recognition completed: data=%s", event.data);

如何還原序列化 RecognizeFailed 事件的範例：

if event.type == "Microsoft.Communication.RecognizeFailed": 
    app.logger.info("Recognize failed: data=%s", event.data);

如何還原序列化 RecognizeCanceled 事件的範例：

if event.type == "Microsoft.Communication.RecognizeCanceled":
    # Handle the RecognizeCanceled event according to your application logic

事件代碼

狀態	代碼	子代碼	訊息
`RecognizeCompleted`	200	8531	動作已完成，收到的位數上限。
`RecognizeCompleted`	200	8514	偵測到停止音調時完成的動作。
`RecognizeCompleted`	400	8508	動作失敗，作業已取消。
`RecognizeCompleted`	400	8532	動作失敗，已達到數字間無回應逾時。
`RecognizeCanceled`	400	8508	動作失敗，作業已取消。
`RecognizeFailed`	400	8510	動作失敗，已達到初始無聲逾時。
`RecognizeFailed`	500	8511	動作失敗，嘗試播放提示時發生失敗。
`RecognizeFailed`	500	8512	未知內部伺服器錯誤。
`RecognizeFailed`	400	8510	動作失敗，已達到初始無回應逾時
`RecognizeFailed`	400	8532	動作失敗，已達到數字間無回應逾時。
`RecognizeFailed`	400	8565	動作失敗，對 Azure AI 服務的要求不正確。檢查輸入參數。
`RecognizeFailed`	400	8565	動作失敗，對 Azure AI 服務的要求不正確。無法處理提供的承載，請檢查播放來源輸入。
`RecognizeFailed`	401	8565	動作失敗，Azure AI 服務驗證錯誤。
`RecognizeFailed`	403	8565	動作失敗，對 Azure AI 服務的要求遭禁止，要求所使用的免費訂用帳戶已用盡配額。
`RecognizeFailed`	429	8565	動作失敗，要求已超過 Azure AI 服務訂用帳戶允許的並行要求數目。
`RecognizeFailed`	408	8565	動作失敗，對 Azure AI 服務的要求已逾時。
`RecognizeFailed`	500	8511	動作失敗，嘗試播放提示時發生失敗。
`RecognizeFailed`	500	8512	未知內部伺服器錯誤。

已知的限制

不支援頻內 DTMF。請改用 RFC 2833 DTMF。
文字轉換語音的文字提示最多支援 400 個字元，如果您的提示超出此長度，建議對文字轉換語音型播放動作使用 SSML。
針對超過語音服務配額限制的案例，您可以遵循語音服務配額和限制 (英文) 中所述的步驟來要求提高此限制。

清除資源

如果您想要清除並移除通訊服務訂用帳戶，您可以刪除資源或資源群組。刪除資源群組也會刪除與其相關聯的任何其他資源。深入了解如何清除資源。

後續步驟

深入了解收集使用者輸入
深入了解在通話中播放音訊
深入了解通話自動化

共用方式為

使用「辨識」動作收集使用者輸入

必要條件

針對 AI 功能

技術規格

建立新的 C# 應用程式

安裝 NuGet 封裝

建立通話

呼叫辨識動作

DTMF

語音轉換文字選項

語音轉換文字

語音轉換文字或 DTMF

接收辨識事件更新

如何還原序列化 RecognizeCompleted 事件的範例：

如何還原序列化 RecognizeFailed 事件的範例：

如何還原序列化 RecognizeCanceled 事件的範例：

必要條件

針對 AI 功能

技術規格

建立新的 Java 應用程式

新增套件參考

建立通話

呼叫辨識動作

DTMF

語音轉換文字選項

語音轉換文字

語音轉換文字或 DTMF

接收辨識事件更新

如何還原序列化 RecognizeCompleted 事件的範例：

如何還原序列化 RecognizeFailed 事件的範例：

如何還原序列化 RecognizeCanceled 事件的範例：

必要條件

針對 AI 功能

技術規格

建立新的 JavaScript 應用程式

安裝 Azure 通訊服務通話自動化套件

建立通話

呼叫辨識動作

DTMF

語音轉換文字選項

語音轉換文字

語音轉換文字或 DTMF

接收辨識事件更新

如何還原序列化 RecognizeCompleted 事件的範例：

如何還原序列化 RecognizeFailed 事件的範例：

如何還原序列化 RecognizeCanceled 事件的範例：

必要條件

針對 AI 功能

技術規格

建立新的 Python 應用程式

為您的專案設定 Python 虛擬環境

啟動虛擬環境

安裝 Azure 通訊服務通話自動化套件

建立通話

呼叫辨識動作

DTMF

語音轉換文字選項

語音轉換文字

語音轉換文字或 DTMF

接收辨識事件更新

如何還原序列化 RecognizeCompleted 事件的範例：

如何還原序列化 RecognizeFailed 事件的範例：

如何還原序列化 RecognizeCanceled 事件的範例：

事件代碼

已知的限制

清除資源

後續步驟

意見反應

其他資源