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

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

先決條件

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

針對 AI 功能

• 建立並連結 Foundry 工具與您的 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	對	如果參與者按下數字，就能夠中斷 playMessage。	選用
InterruptCallMediaOperation	Bool	對	如果設定此旗標，則會中斷目前的通話媒體作業。 例如，如果正在播放任何音訊，則會中斷該作業並起始辨識。	選用
OperationContext	繩子	未設定	開發人員可以傳遞中間動作的字串，適合讓開發人員儲存他們所接收事件的相關內容。	選用
Phrases	繩子	未設定	與標籤相關聯片語的清單。 聽到上述任何片語即表示成功辨識。	必要
Tone	繩子	未設定	使用者決定按數字而不是使用語音時所辨識的音調。	選用
Label	繩子	未設定	辨識的關鍵值。	必要
Language	繩子	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",
    SpeechLanguages = new List<string> { "en-US", "hi-IN", "fr-FR" },
    //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",
    SpeechLanguages = new List<string> { "en-US", "hi-IN", "fr-FR" },
    //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: new PhoneNumberIdentifier(targetParticipant))
{
    Prompt = playSource,
    InterruptCallMediaOperation = false,
    InterruptPrompt = false,
    InitialSilenceTimeout = TimeSpan.FromSeconds(10),
    OperationContext = "OpenQuestionSpeech",
    // Enable Language Identification
    SpeechLanguages = new List<string> { "en-US", "hi-IN", "fr-FR" },
    // 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);

附註

語言支援限制

使用 Recognize API 搭配語音作為輸入類型時：

• 您可使用 來指定setSpeechLanguages(...)。
• 請注意，由於額外的處理，使用更多語言可能會使其接收 事件所需的RecognizeCompleted。

使用 Recognize API 搭配選擇時：

• 最多僅支援 4 種語言。
• 在選擇模式中指定 4 種以上的語言可能會導致錯誤或效能降低。

情感分析 (預覽)

辨識 API 支援使用語音輸入時的情緒分析。 即時追蹤交談的情緒語調，以支援客戶和專員的互動，並在必要時讓主管能夠介入。 它對於路由、個人化或分析也很有用。

string textToPlay = "Hi, how can I help you today?";
var playSource = new TextSource(textToPlay, "en-US-ElizabethNeural");
var recognizeOptions = new CallMediaRecognizeSpeechOptions(targetParticipant: new PhoneNumberIdentifier(targetParticipant))
{
    Prompt = playSource,
    InterruptCallMediaOperation = false,
    InterruptPrompt = false,
    InitialSilenceTimeout = TimeSpan.FromSeconds(10),
    OperationContext = "OpenQuestionSpeech",
    // Enable Sentiment Analysis
    IsSentimentAnalysisEnabled = true
};
var recognizeResult = await callAutomationClient.GetCallConnection(callConnectionId)
    .GetCallMedia()
    .StartRecognizingAsync(recognizeOptions);

接收辨識事件更新

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

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

if (parsedEvent is RecognizeCompleted recognizeCompleted)
{
    logger.LogInformation($"Received call event: {recognizeCompleted.GetType()}");

    callConnectionId = recognizeCompleted.CallConnectionId;

    switch (recognizeCompleted.RecognizeResult)
    {
        case DtmfResult dtmfResult:
            var tones = dtmfResult.Tones;
            logger.LogInformation("Recognize completed successfully, tones={tones}", tones);
            break;

        case ChoiceResult choiceResult:
            var labelDetected = choiceResult.Label;
            var phraseDetected = choiceResult.RecognizedPhrase;
            var sentimentAnalysis = choiceResult.SentimentAnalysisResult;

            logger.LogInformation("Recognize completed successfully, labelDetected={labelDetected}, phraseDetected={phraseDetected}", labelDetected, phraseDetected);
            logger.LogInformation("Language Identified: {language}", choiceResult.LanguageIdentified);

            if (sentimentAnalysis != null)
            {
                logger.LogInformation("Sentiment: {sentiment}", sentimentAnalysis.Sentiment);
            }
            break;

        case SpeechResult speechResult:
            var text = speechResult.Speech;
            var speechSentiment = speechResult.SentimentAnalysisResult;

            logger.LogInformation("Recognize completed successfully, text={text}", text);
            logger.LogInformation("Language Identified: {language}", speechResult.LanguageIdentified);

            if (speechSentiment != null)
            {
                logger.LogInformation("Sentiment: {sentiment}", speechSentiment.Sentiment);
            }
            break;

        default:
            logger.LogInformation("Recognize completed successfully, 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 silence 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 功能

• 建立並連結 Foundry 工具與您的 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	對	如果參與者按下數字，就能夠中斷 playMessage。	選用
InterruptCallMediaOperation	Bool	對	如果設定此旗標，則會中斷目前的通話媒體作業。 例如，如果正在播放任何音訊，則會中斷該作業並起始辨識。	選用
OperationContext	繩子	未設定	開發人員可以傳遞中間動作的字串，適合讓開發人員儲存他們所接收事件的相關內容。	選用
Phrases	繩子	未設定	與標籤相關聯片語的清單。 聽到上述任何片語即表示成功辨識。	必要
Tone	繩子	未設定	使用者決定按數字而不是使用語音時所辨識的音調。	選用
Label	繩子	未設定	辨識的關鍵值。	必要
Language	繩子	En-us	用於辨識語音的語言。	選用
EndSilenceTimeout	TimeSpan	0.5 秒	說話者的最後暫停，用來偵測產生為語音的最終結果。	選用

附註

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

建立新的 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)
  .setSpeechLanguages("en-US", "es-ES", "hi-IN")
  .setSentimentAnalysisEnabled(true)
  .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(); 

附註

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

即時語言識別 (預覽)

透過即時語言識別的附加功能，開發人員可以自動偵測口語語言以實現自然、類似人類的通訊，讓終端使用者免除手動選取語言。

String textToPlay = "Hi, how can I help you today?";
var playSource = new TextSource()
    .setText(textToPlay)
    .setVoiceName("en-US-ElizabethNeural");

var recognizeOptions = new CallMediaRecognizeSpeechOptions(participant, Duration.ofSeconds(15))
    .setPlayPrompt(playSource)
    .setInterruptPrompt(false)
    .setInitialSilenceTimeout(Duration.ofSeconds(15))
    .setSentimentAnalysisEnabled(true)
    .setSpeechLanguages("en-US", "es-ES", "hi-IN")
    .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();

附註

語言支援限制

使用 Recognize API 搭配語音作為輸入類型時：

• 您可使用 來指定setSpeechLanguages(...)。
• 請注意，由於額外的處理，使用更多語言可能會使其接收 事件所需的RecognizeCompleted。

使用 Recognize API 搭配選擇時：

• 最多僅支援 4 種語言。
• 在選擇模式中指定 4 種以上的語言可能會導致錯誤或效能降低。

情感分析 (預覽)

辨識 API 支援使用語音輸入時的情緒分析。 即時追蹤交談的情緒語調，以支援客戶和專員的互動，並在必要時讓主管能夠介入。 它對於路由、個人化或分析也很有用。

String textToPlay = "Hi, how can I help you today?";
var playSource = new TextSource()
    .setText(textToPlay)
    .setVoiceName("en-US-ElizabethNeural");

var recognizeOptions = new CallMediaRecognizeSpeechOptions(participant, Duration.ofSeconds(15))
    .setPlayPrompt(playSource)
    .setInterruptPrompt(false)
    .setInitialSilenceTimeout(Duration.ofSeconds(15))
    .setSentimentAnalysisEnabled(true)
    .setSpeechLanguages("en-US", "es-ES", "hi-IN")
    .setOperationContext("SpeechContext");

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

接收辨識事件更新

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

如何還原序列化 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();
        String languageIdentified = collectChoiceResult.getLanguageIdentified();
        log.info("Recognition completed, labelDetected=" + labelDetected + ", phraseDetected=" + phraseDetected + ", context=" + event.getOperationContext());
        log.info("Language Identified: " + languageIdentified);
        if (choiceResult.getSentimentAnalysisResult() != null) {
            log.info("Sentiment: " + choiceResult.getSentimentAnalysisResult().getSentiment());
        }
    } else if (recognizeResult instanceof SpeechResult) { 
        SpeechResult speechResult = (SpeechResult) recognizeResult; 
        String text = speechResult.getSpeech();
        String languageIdentified = speechResult.getLanguageIdentified();
        log.info("Recognition completed, text=" + text + ", context=" + event.getOperationContext());
        log.info("Language Identified: " + languageIdentified);
        if (speechResult.getSentimentAnalysisResult() != null) {
            log.info("Sentiment: " + speechResult.getSentimentAnalysisResult().getSentiment());
        }
    } 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 功能

• 建立並連結 Foundry 工具與您的 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	對	如果參與者按下數字，就能夠中斷 playMessage。	選用
InterruptCallMediaOperation	Bool	對	如果設定此旗標，則會中斷目前的通話媒體作業。 例如，如果正在播放任何音訊，則會中斷該作業並起始辨識。	選用
OperationContext	繩子	未設定	開發人員可以傳遞中間動作的字串，適合讓開發人員儲存他們所接收事件的相關內容。	選用
Phrases	繩子	未設定	與標籤相關聯片語的清單。 聽到上述任何片語即表示成功辨識。	必要
Tone	繩子	未設定	使用者決定按數字而不是使用語音時所辨識的音調。	選用
Label	繩子	未設定	辨識的關鍵值。	必要
Language	繩子	En-us	用於辨識語音的語言。	選用
EndSilenceTimeout	TimeSpan	0.5 秒	說話者的最後暫停，用來偵測產生為語音的最終結果。	選用

附註

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

建立新的 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); 

附註

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

即時語言識別 (預覽)

透過即時語言識別的附加功能，開發人員可以自動偵測口語語言以實現自然、類似人類的通訊，讓終端使用者免除手動選取語言。

const textToPlay = "Hi, how can I help you today?";
const playSource: TextSource = {
  text: textToPlay,
  voiceName: "en-US-ElizabethNeural",
  kind: "textSource"
};
const recognizeOptions: CallMediaRecognizeSpeechOptions = {
  endSilenceTimeoutInSeconds: 30,
  playPrompt: playSource,
  operationContext: "speechContext",
  kind: "callMediaRecognizeSpeechOptions",
  // Enable Language Identification
  speechLanguages: ["en-US", "hi-IN", "fr-FR"],
  // 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);

附註

語言支援限制

使用 Recognize API 搭配語音作為輸入類型時：

• 您可使用 來指定setSpeechLanguages(...)。
• 請注意，由於額外的處理，使用更多語言可能會使其接收 事件所需的RecognizeCompleted。

使用 Recognize API 搭配選擇時：

• 最多僅支援 4 種語言。
• 在選擇模式中指定 4 種以上的語言可能會導致錯誤或效能降低。

情感分析 (預覽)

辨識 API 支援使用語音輸入時的情緒分析。 即時追蹤交談的情緒語調，以支援客戶和專員的互動，並在必要時讓主管能夠介入。 它對於路由、個人化或分析也很有用。

const textToPlay = "Hi, how can I help you today?";
const playSource: TextSource = {
  text: textToPlay,
  voiceName: "en-US-ElizabethNeural",
  kind: "textSource"
};

const recognizeOptions: CallMediaRecognizeSpeechOptions = {
  endSilenceTimeoutInSeconds: 30,
  playPrompt: playSource,
  operationContext: "speechContext",
  kind: "callMediaRecognizeSpeechOptions",

  // Enable Sentiment Analysis
  enableSentimentAnalysis: true
};

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

接收辨識事件更新

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

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

if (event.type === "Microsoft.Communication.RecognizeCompleted") {
  console.log("Received RecognizeCompleted event");

  const callConnectionId = eventData.callConnectionId;

  if (eventData.recognitionType === "choices") {
    const labelDetected = eventData.choiceResult.label;
    console.log(`Detected label: ${labelDetected}`);
    console.log("Choice Result:", JSON.stringify(eventData.choiceResult, null, 2));
    console.log(`Language Identified: ${eventData.choiceResult.languageIdentified}`);

    if (eventData.choiceResult?.sentimentAnalysisResult !== undefined) {
      console.log(`Sentiment: ${eventData.choiceResult.sentimentAnalysisResult.sentiment}`);
    }
  }

  if (eventData.recognitionType === "dtmf") {
    const tones = eventData.dtmfResult.tones;
    console.log(`DTMF Tones: ${tones}`);
    console.log(`Current Context: ${eventData.operationContext}`);
  }

  if (eventData.recognitionType === "speech") {
    const text = eventData.speechResult.speech;
    console.log(`Recognition completed, text: ${text}, context: ${eventData.operationContext}`);
    console.log(`Language Identified: ${eventData.speechResult.languageIdentified}`);

    if (eventData.speechResult?.sentimentAnalysisResult !== undefined) {
      console.log(`Sentiment: ${eventData.speechResult.sentimentAnalysisResult.sentiment}`);
    }
  }
}

如何還原序列化 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 功能

• 建立並連結 Foundry 工具與您的 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	對	如果參與者按下數字，就能夠中斷 playMessage。	選用
InterruptCallMediaOperation	Bool	對	如果設定此旗標，則會中斷目前的通話媒體作業。 例如，如果正在播放任何音訊，則會中斷該作業並起始辨識。	選用
OperationContext	繩子	未設定	開發人員可以傳遞中間動作的字串，適合讓開發人員儲存他們所接收事件的相關內容。	選用
Phrases	繩子	未設定	與標籤相關聯片語的清單。 聽到上述任何片語即表示成功辨識。	必要
Tone	繩子	未設定	使用者決定按數字而不是使用語音時所辨識的音調。	選用
Label	繩子	未設定	辨識的關鍵值。	必要
Language	繩子	En-us	用於辨識語音的語言。	選用
EndSilenceTimeout	TimeSpan	0.5 秒	說話者的最後暫停，用來偵測產生為語音的最終結果。	選用

附註

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

建立新的 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") 

附註

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

即時語言識別 (預覽)

透過即時語言識別的附加功能，開發人員可以自動偵測口語語言以實現自然、類似人類的通訊，讓終端使用者免除手動選取語言。

text_to_play = "Hi, how can I help you today?"
play_source = TextSource(text=text_to_play, voice_name="en-US-ElizabethNeural")

connection_client = call_automation_client.get_call_connection(call_connection_id)

recognize_result = await connection_client.start_recognizing_media(
    input_type=RecognizeInputType.SPEECH,
    target_participant=PhoneNumberIdentifier(caller_id),
    end_silence_timeout=15,
    play_prompt=play_source,
    operation_context="OpenQuestionSpeech",

    # Enable language identification
    speech_language=["en-US", "es-ES", "hi-IN"],

    # 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"
)

附註

語言支援限制

使用 Recognize API 搭配語音作為輸入類型時：

• 您可使用 來指定setSpeechLanguages(...)。
• 請注意，由於額外的處理，使用更多語言可能會使其接收 事件所需的RecognizeCompleted。

使用 Recognize API 搭配選擇時：

• 最多僅支援 4 種語言。
• 在選擇模式中指定 4 種以上的語言可能會導致錯誤或效能降低。

情感分析 (預覽)

辨識 API 支援使用語音輸入時的情緒分析。 即時追蹤交談的情緒語調，以支援客戶和專員的互動，並在必要時讓主管能夠介入。 它對於路由、個人化或分析也很有用。

text_to_play = "Hi, how can I help you today?"
play_source = TextSource(text=text_to_play, voice_name="en-US-ElizabethNeural")

connection_client = call_automation_client.get_call_connection(call_connection_id)

recognize_result = await connection_client.start_recognizing_media(
    input_type=RecognizeInputType.SPEECH,
    target_participant=PhoneNumberIdentifier(caller_id),
    end_silence_timeout=15,
    play_prompt=play_source,
    operation_context="OpenQuestionSpeech",
    
    # Enable sentiment analysis
    IsSentimentAnalysisEnabled = true,

    # 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"
)

接收辨識事件更新

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

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

if event.type == "Microsoft.Communication.RecognizeCompleted":
    print(f"Received RecognizeCompleted event for connection id: {call_connection_id}")

    recognition_type = event.data.get("recognitionType")

    if recognition_type == "dtmf":
        tones = event.data["dtmfResult"]["tones"]
        context = event.data["operationContext"]
        print(f"Recognition completed, tones={tones}, context={context}")

    elif recognition_type == "choices":
        choice_result = event.data["choiceResult"]
        label_detected = choice_result["label"]
        phrase_detected = choice_result["recognizedPhrase"]
        language_identified = choice_result.get("languageIdentified")
        sentiment = choice_result.get("sentimentAnalysisResult", {}).get("sentiment")

        print(f"Recognition completed, labelDetected={label_detected}, phraseDetected={phrase_detected}, context={event.data['operationContext']}")
        print(f"Language Identified: {language_identified}")
        print(f"Sentiment: {sentiment}")

    elif recognition_type == "speech":
        speech_result = event.data["speechResult"]
        text = speech_result["speech"]
        language_identified = speech_result.get("languageIdentified")
        sentiment = speech_result.get("sentimentAnalysisResult", {}).get("sentiment")

        print(f"Recognition completed, text={text}, context={event.data['operationContext']}")
        print(f"Language Identified: {language_identified}")
        print(f"Sentiment: {sentiment}")

    else:
        print(f"Recognition completed: data={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

事件代碼

狀態	Code	子代碼	訊息
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。
• 文字轉換語音提示最多支援 4,000 個字元。 如果您的提示超過此限制，建議您針對文字轉換語音型的動作使用 SSML。
• 錄製的語音輸入會擷取 1：1 通話，但在啟用錄製時不會記錄在群組通話中。
• 如果您超過配額限制，則可以要求提高語音服務配額。 請遵循 此處 所述的步驟來要求增加。

清除資源

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

後續步驟

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