Erfassen von Benutzereingaben mit der Erkennungsaktion

Diese Anleitung unterstützt Sie beim Einstieg in die Erkennung von DTMF-Eingaben, die von Teilnehmern mithilfe des Azure Communication Services Call Automation SDK bereitgestellt werden.

Voraussetzungen

• Ein Azure-Konto mit einem aktiven Abonnement. Details finden Sie im Artikel zum Erstellen eines kostenlosen Azure-Kontos.
• Azure Communication Services-Ressource. Siehe Schnellstart: Erstellen und Verwalten einer Communication Services-Ressource. Notieren Sie die Verbindungszeichenfolge für diese Ressource.
• Erstellen einer neuen Webdienstanwendung mithilfe des Call Automation SDK
• Die aktuelle .NET-Bibliothek für Ihr Betriebssystem
• Rufen Sie das neueste NuGet-Paket ab.

Für KI-Features

• Erstellen Sie eine Azure KI Services-Instanz für Ihre Azure Communications Services-Ressource, und stellen Sie eine Verbindung mit ihr her.
• Erstellen Sie eine benutzerdefinierte Subdomäne für Ihre Azure KI Services-Ressource.

Technische Spezifikationen

Die folgenden Parameter stehen zum Anpassen der Erkennungsfunktion zur Verfügung:

Parameter	type	Standard (falls nicht angegeben)	Beschreibung	Erforderlich oder optional
Prompt (Ausführliche Details zur Wiedergabeaktion finden Sie in dieser Schrittanleitung)	FileSource, TextSource	Nicht festgelegt	Dies ist die Nachricht, die Sie vor der Erkennung von Eingaben wiedergeben möchten.	Optional
InterToneTimeout	TimeSpan	2 Sekunden Min: 1 Sekunde Max: 60 Sekunden	Grenzwert in Sekunden, den Azure Communication Services wartet, dass der Anrufer oder die Aufruferin eine weitere Ziffer eingibt (Timeoutwert zwischen Ziffern).	Optional
InitialSegmentationSilenceTimeoutInSeconds	Integer	0,5 Sekunden	Zeitraum, den eine Erkennungsaktion auf Eingaben wartet, bevor sie die Wartezeit als Timeout betrachtet. Weitere Informationen finden Sie hier.	Optional
RecognizeInputsType	Enum	dtmf	Typ der erkannten Eingabedaten. Zur Auswahl stehen „dtmf“, „choices“, „speech“ und „speechordtmf“.	Erforderlich
InitialSilenceTimeout	TimeSpan	5 Sekunden Min: 0 Sekunden Max: 300 Sekunden (DTMF) Max: 20 Sekunden (Auswahl) Max: 20 Sekunden (Sprache)	Initial silence timeout (Anfangsstille-Timeout) passt an, wie viel sprachfremdes Audio vor einem Ausdruck zulässig ist, bevor der Erkennungsversuch mit dem Ergebnis „keine Übereinstimmung“ endet. Weitere Informationen finden Sie hier.	Optional
MaxTonesToCollect	Integer	Kein Standardwert Min: 1	Anzahl der Ziffern, die ein Entwickler als Eingabe vom Teilnehmer erwartet.	Erforderlich
StopTones	IEnumeration<DtmfTone>	Nicht festgelegt	Die Ziffer, die Teilnehmer drücken können, um aus einem Batch-DTMF-Ereignis freizukommen.	Optional
InterruptPrompt	Bool	True	Falls der Teilnehmer die Möglichkeit hat, die playMessage durch Drücken einer Ziffer zu unterbrechen.	Optional
InterruptCallMediaOperation	Bool	True	Wenn dieses Flag festgelegt ist, wird der aktuelle Anrufmedienvorgang unterbrochen. Beispielsweise wird der Vorgang während einer laufenden Wiedergabe unterbrochen und die Erkennung eingeleitet.	Optional
OperationContext	String	Nicht festgelegt	Zeichenfolge, die Entwickler während einer Aktion übergeben können. Damit können Entwickler Kontext zu den empfangenen Ereignissen speichern.	Optional
Ausdrücke	String	Nicht festgelegt	Liste der Ausdrücke, die der Bezeichnung zugeordnet sind. Falls einige davon gehört werden, wird dies als erfolgreiche Erkennung betrachtet.	Erforderlich
Ton	String	Nicht festgelegt	Der Ton, der erkannt werden soll, wenn der Benutzer oder die Benutzerin entscheidet, eine Zahl einzugeben, anstatt die Spracheingabe zu verwenden.	Optional
Label	String	Nicht festgelegt	Der Schlüsselwert für die Erkennung.	Erforderlich
Sprache	String	en-US	Die Sprache, die für die Spracherkennung verwendet wird.	Optional
EndSilenceTimeout	TimeSpan	0,5 Sekunden	Die letzte Pause des Sprechers/der Sprecherin, die zum Erkennen des Endergebnisses verwendet wird, das als Sprache generiert wird.	Optional

Hinweis

In Situationen, in denen sich sowohl DTMF als auch Sprache im recognizeInputsType enthalten sind, verarbeitet die Erkennungsaktion den ersten empfangenen Eingabetyp, d. h., wenn der Benutzer oder die Benutzerin zuerst eine Wähltastaturnummer drückt, betrachtet die Erkennungsaktion die Eingabe als DTMF-Ereignis und lauscht auf weitere DTMF-Töne. Wenn der Benutzer oder die Benutzerin zuerst spricht, wertet die Erkennungsaktion dies als Spracherkennung und lauscht auf Spracheingaben.

Erstellen einer neuen C#-Anwendung

Verwenden Sie im Konsolenfenster Ihres Betriebssystems den Befehl dotnet, um eine neue Webanwendung zu erstellen.

dotnet new web -n MyApplication

Installieren des NuGet-Pakets

Das NuGet-Paket kann hier abgerufen werden, sofern noch nicht geschehen.

Einrichten eines Anrufs

An diesem Punkt sollten Sie mit dem Starten von Anrufen vertraut sein. Wenn Sie weitere Informationen zum Tätigen eines Anrufs benötigen, befolgen Sie unseren Schnellstart. Sie können auch den folgenden Codeschnipsel verwenden, um zu verstehen, wie auf einen Anruf reagiert wird.

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); 

Aufrufen der Erkennungsaktion

Wenn Ihre Anwendung den Anruf annimmt, können Sie Informationen zur Erkennung von Teilnehmereingaben und zur Wiedergabe einer Äußerung bereitstellen.

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);

Bei Spracherkennungsflows unterstützt die Erkennungsaktion der Anrufautomatisierung auch die Verwendung von benutzerdefinierten Sprachmodellen. Features wie benutzerdefinierte Sprachmodelle können nützlich sein, wenn Sie eine Anwendung erstellen, die auf komplexe Wörter lauschen soll, die die Standardmodelle zur Spracherkennung möglicherweise nicht verstehen. Ein gutes Beispiel hierfür ist, wenn Sie eine Anwendung für die Telemedizinbranche erstellen und Ihr virtueller Agent medizinische Begriffe erkennen muss. Weitere Informationen zum Erstellen und Bereitstellen benutzerdefinierter Sprachmodelle finden Sie hier.

Auswahlmöglichkeiten bei der Spracherkennung

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);

Spracherkennung

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);

Sprache-in-Text oder 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); 

Hinweis

Wenn keine Parameter festgelegt sind, werden nach Möglichkeit die Standardwerte angewandt.

Empfangen von Updates zu Erkennungsereignissen

Entwickler und Entwicklerinnen können die Ereignisse RecognizeCompleted und RecognizeFailed im Webhook-Rückruf abonnieren, die sie für den Aufruf registriert haben, um Geschäftslogik in ihrer Anwendung zu erstellen, mit der die nächsten Schritte bestimmt werden, wenn eines der oben genannten Ereignisse eintritt.

Beispiel zur Deserialisierung des RecognizeCompleted-Ereignisses:

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; 
    } 
} 

Beispiel zur Deserialisierung des RecognizeFailed-Ereignisses:

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); 
    } 
} 

Beispiel zur Deserialisierung des RecognizeCanceled-Ereignisses:

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);
        }

Voraussetzungen

• Ein Azure-Konto mit einem aktiven Abonnement. Details finden Sie im Artikel zum Erstellen eines kostenlosen Azure-Kontos.
• Azure Communication Services-Ressource. Siehe Schnellstart: Erstellen und Verwalten einer Communication Services-Ressource.
• Erstellen einer neuen Webdienstanwendung mithilfe des Call Automation SDK
• Java Development Kit, Version 8 oder höher
• Apache Maven.

Für KI-Features

• Erstellen Sie eine Azure KI Services-Instanz für Ihre Azure Communications Services-Ressource, und stellen Sie eine Verbindung mit ihr her.
• Erstellen Sie eine benutzerdefinierte Subdomäne für Ihre Azure KI Services-Ressource.

Technische Spezifikationen

Die folgenden Parameter stehen zum Anpassen der Erkennungsfunktion zur Verfügung:

Parameter	type	Standard (falls nicht angegeben)	Beschreibung	Erforderlich oder optional
Prompt (Ausführliche Details zur Wiedergabeaktion finden Sie in dieser Schrittanleitung)	FileSource, TextSource	Nicht festgelegt	Dies ist die Nachricht, die Sie vor der Erkennung von Eingaben wiedergeben möchten.	Optional
InterToneTimeout	TimeSpan	2 Sekunden Min: 1 Sekunde Max: 60 Sekunden	Grenzwert in Sekunden, den Azure Communication Services wartet, dass der Anrufer oder die Aufruferin eine weitere Ziffer eingibt (Timeoutwert zwischen Ziffern).	Optional
InitialSegmentationSilenceTimeoutInSeconds	Integer	0,5 Sekunden	Zeitraum, den eine Erkennungsaktion auf Eingaben wartet, bevor sie die Wartezeit als Timeout betrachtet. Weitere Informationen finden Sie hier.	Optional
RecognizeInputsType	Enum	dtmf	Typ der erkannten Eingabedaten. Zur Auswahl stehen „dtmf“, „choices“, „speech“ und „speechordtmf“.	Erforderlich
InitialSilenceTimeout	TimeSpan	5 Sekunden Min: 0 Sekunden Max: 300 Sekunden (DTMF) Max: 20 Sekunden (Auswahl) Max: 20 Sekunden (Sprache)	Initial silence timeout (Anfangsstille-Timeout) passt an, wie viel sprachfremdes Audio vor einem Ausdruck zulässig ist, bevor der Erkennungsversuch mit dem Ergebnis „keine Übereinstimmung“ endet. Weitere Informationen finden Sie hier.	Optional
MaxTonesToCollect	Integer	Kein Standardwert Min: 1	Anzahl der Ziffern, die ein Entwickler als Eingabe vom Teilnehmer erwartet.	Erforderlich
StopTones	IEnumeration<DtmfTone>	Nicht festgelegt	Die Ziffer, die Teilnehmer drücken können, um aus einem Batch-DTMF-Ereignis freizukommen.	Optional
InterruptPrompt	Bool	True	Falls der Teilnehmer die Möglichkeit hat, die playMessage durch Drücken einer Ziffer zu unterbrechen.	Optional
InterruptCallMediaOperation	Bool	True	Wenn dieses Flag festgelegt ist, wird der aktuelle Anrufmedienvorgang unterbrochen. Beispielsweise wird der Vorgang während einer laufenden Wiedergabe unterbrochen und die Erkennung eingeleitet.	Optional
OperationContext	String	Nicht festgelegt	Zeichenfolge, die Entwickler während einer Aktion übergeben können. Damit können Entwickler Kontext zu den empfangenen Ereignissen speichern.	Optional
Ausdrücke	String	Nicht festgelegt	Liste der Ausdrücke, die der Bezeichnung zugeordnet sind. Falls einige davon gehört werden, wird dies als erfolgreiche Erkennung betrachtet.	Erforderlich
Ton	String	Nicht festgelegt	Der Ton, der erkannt werden soll, wenn der Benutzer oder die Benutzerin entscheidet, eine Zahl einzugeben, anstatt die Spracheingabe zu verwenden.	Optional
Label	String	Nicht festgelegt	Der Schlüsselwert für die Erkennung.	Erforderlich
Sprache	String	en-US	Die Sprache, die für die Spracherkennung verwendet wird.	Optional
EndSilenceTimeout	TimeSpan	0,5 Sekunden	Die letzte Pause des Sprechers/der Sprecherin, die zum Erkennen des Endergebnisses verwendet wird, das als Sprache generiert wird.	Optional

Hinweis

In Situationen, in denen sich sowohl DTMF als auch Sprache im recognizeInputsType enthalten sind, verarbeitet die Erkennungsaktion den ersten empfangenen Eingabetyp, d. h., wenn der Benutzer oder die Benutzerin zuerst eine Wähltastaturnummer drückt, betrachtet die Erkennungsaktion die Eingabe als DTMF-Ereignis und lauscht auf weitere DTMF-Töne. Wenn der Benutzer oder die Benutzerin zuerst spricht, wertet die Erkennungsaktion dies als Spracherkennung und lauscht auf Spracheingaben.

Erstellen einer neuen Java-Anwendung

Navigieren Sie in Ihrem Terminal- oder Befehlsfenster zu dem Verzeichnis, in dem Sie Ihre Java-Anwendung erstellen möchten. Führen Sie den Befehl mvn aus, um das Java-Projekt aus der Vorlage „maven-archetype-quickstart“ zu generieren.

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

Der oben angegebene Befehl mvn erstellt ein Verzeichnis mit demselben Namen wie das artifactId-Argument. In diesem Verzeichnis enthält das Verzeichnis src/main/java den Projektquellcode, und das Verzeichnis src/test/java enthält die Testquelle.

Sie sehen, dass über den Schritt „generate“ ein Verzeichnis mit dem gleichen Namen wie für „artifactId“ erstellt wurde. In diesem Verzeichnis enthält der Ordner src/main/java den Quellcode, src/test/java enthält die Tests, und die Datei pom.xml repräsentiert das Projektobjektmodell (POM).

Aktualisieren Sie die POM-Datei Ihrer Anwendung für die Verwendung von Java 8 oder höher:

<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>

Hinzufügen von Paketverweisen

Fügen Sie in Ihrer POM-Datei den folgenden Verweis für das Projekt hinzu

azure-communication-callautomation

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

Einrichten eines Anrufs

An diesem Punkt sollten Sie mit dem Starten von Anrufen vertraut sein. Wenn Sie weitere Informationen zum Tätigen eines Anrufs benötigen, befolgen Sie unseren Schnellstart. Sie können auch den folgenden Codeschnipsel verwenden, um zu verstehen, wie auf einen Anruf reagiert wird.

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();

Aufrufen der Erkennungsaktion

Wenn Ihre Anwendung den Anruf annimmt, können Sie Informationen zur Erkennung von Teilnehmereingaben und zur Wiedergabe einer Äußerung bereitstellen.

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()); 

Bei Spracherkennungsflows unterstützt die Erkennungsaktion der Anrufautomatisierung auch die Verwendung von benutzerdefinierten Sprachmodellen. Features wie benutzerdefinierte Sprachmodelle können nützlich sein, wenn Sie eine Anwendung erstellen, die auf komplexe Wörter lauschen soll, die die Standardmodelle zur Spracherkennung möglicherweise nicht verstehen. Ein gutes Beispiel hierfür ist, wenn Sie eine Anwendung für die Telemedizinbranche erstellen und Ihr virtueller Agent medizinische Begriffe erkennen muss. Weitere Informationen zum Erstellen und Bereitstellen benutzerdefinierter Sprachmodelle finden Sie hier.

Auswahlmöglichkeiten bei der Spracherkennung

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();

Spracherkennung

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(); 

Sprache-in-Text oder 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(); 

Hinweis

Wenn keine Parameter festgelegt sind, werden nach Möglichkeit die Standardwerte angewandt.

Empfangen von Updates zu Erkennungsereignissen

Entwickler und Entwicklerinnen können die Ereignisse RecognizeCompleted und RecognizeFailed für den registrierten Webhook-Rückruf abonnieren. Dieser Rückruf kann mit Geschäftslogik in Ihrer Anwendung verwendet werden, um die nächsten Schritte zu bestimmen, wenn eines der Ereignisse eintritt.

Beispiel zur Deserialisierung des RecognizeCompleted-Ereignisses:

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()); 
    } 
} 

Beispiel zur Deserialisierung des RecognizeFailed-Ereignisses:

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()); 
    } 
} 

Beispiel zur Deserialisierung des RecognizeCanceled-Ereignisses:

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

Voraussetzungen

• Ein Azure-Konto mit einem aktiven Abonnement. Details finden Sie im Artikel zum Erstellen eines kostenlosen Azure-Kontos.
• Azure Communication Services-Ressource. Siehe Schnellstart: Erstellen und Verwalten einer Communication Services-Ressource. Notieren Sie die Verbindungszeichenfolge für diese Ressource.
• Erstellen einer neuen Webdienstanwendung mithilfe des Call Automation SDK
• Installieren Sie Node.js, das Sie auf der offiziellen Website erhalten.

Für KI-Features

• Erstellen Sie eine Azure KI Services-Instanz für Ihre Azure Communications Services-Ressource, und stellen Sie eine Verbindung mit ihr her.
• Erstellen Sie eine benutzerdefinierte Subdomäne für Ihre Azure KI Services-Ressource.

Technische Spezifikationen

Die folgenden Parameter stehen zum Anpassen der Erkennungsfunktion zur Verfügung:

Parameter	type	Standard (falls nicht angegeben)	Beschreibung	Erforderlich oder optional
Prompt (Ausführliche Details zur Wiedergabeaktion finden Sie in dieser Schrittanleitung)	FileSource, TextSource	Nicht festgelegt	Dies ist die Nachricht, die Sie vor der Erkennung von Eingaben wiedergeben möchten.	Optional
InterToneTimeout	TimeSpan	2 Sekunden Min: 1 Sekunde Max: 60 Sekunden	Grenzwert in Sekunden, den Azure Communication Services wartet, dass der Anrufer oder die Aufruferin eine weitere Ziffer eingibt (Timeoutwert zwischen Ziffern).	Optional
InitialSegmentationSilenceTimeoutInSeconds	Integer	0,5 Sekunden	Zeitraum, den eine Erkennungsaktion auf Eingaben wartet, bevor sie die Wartezeit als Timeout betrachtet. Weitere Informationen finden Sie hier.	Optional
RecognizeInputsType	Enum	dtmf	Typ der erkannten Eingabedaten. Zur Auswahl stehen „dtmf“, „choices“, „speech“ und „speechordtmf“.	Erforderlich
InitialSilenceTimeout	TimeSpan	5 Sekunden Min: 0 Sekunden Max: 300 Sekunden (DTMF) Max: 20 Sekunden (Auswahl) Max: 20 Sekunden (Sprache)	Initial silence timeout (Anfangsstille-Timeout) passt an, wie viel sprachfremdes Audio vor einem Ausdruck zulässig ist, bevor der Erkennungsversuch mit dem Ergebnis „keine Übereinstimmung“ endet. Weitere Informationen finden Sie hier.	Optional
MaxTonesToCollect	Integer	Kein Standardwert Min: 1	Anzahl der Ziffern, die ein Entwickler als Eingabe vom Teilnehmer erwartet.	Erforderlich
StopTones	IEnumeration<DtmfTone>	Nicht festgelegt	Die Ziffer, die Teilnehmer drücken können, um aus einem Batch-DTMF-Ereignis freizukommen.	Optional
InterruptPrompt	Bool	True	Falls der Teilnehmer die Möglichkeit hat, die playMessage durch Drücken einer Ziffer zu unterbrechen.	Optional
InterruptCallMediaOperation	Bool	True	Wenn dieses Flag festgelegt ist, wird der aktuelle Anrufmedienvorgang unterbrochen. Beispielsweise wird der Vorgang während einer laufenden Wiedergabe unterbrochen und die Erkennung eingeleitet.	Optional
OperationContext	String	Nicht festgelegt	Zeichenfolge, die Entwickler während einer Aktion übergeben können. Damit können Entwickler Kontext zu den empfangenen Ereignissen speichern.	Optional
Ausdrücke	String	Nicht festgelegt	Liste der Ausdrücke, die der Bezeichnung zugeordnet sind. Falls einige davon gehört werden, wird dies als erfolgreiche Erkennung betrachtet.	Erforderlich
Ton	String	Nicht festgelegt	Der Ton, der erkannt werden soll, wenn der Benutzer oder die Benutzerin entscheidet, eine Zahl einzugeben, anstatt die Spracheingabe zu verwenden.	Optional
Label	String	Nicht festgelegt	Der Schlüsselwert für die Erkennung.	Erforderlich
Sprache	String	en-US	Die Sprache, die für die Spracherkennung verwendet wird.	Optional
EndSilenceTimeout	TimeSpan	0,5 Sekunden	Die letzte Pause des Sprechers/der Sprecherin, die zum Erkennen des Endergebnisses verwendet wird, das als Sprache generiert wird.	Optional

Hinweis

In Situationen, in denen sich sowohl DTMF als auch Sprache im recognizeInputsType enthalten sind, verarbeitet die Erkennungsaktion den ersten empfangenen Eingabetyp, d. h., wenn der Benutzer oder die Benutzerin zuerst eine Wähltastaturnummer drückt, betrachtet die Erkennungsaktion die Eingabe als DTMF-Ereignis und lauscht auf weitere DTMF-Töne. Wenn der Benutzer oder die Benutzerin zuerst spricht, wertet die Erkennungsaktion dies als Spracherkennung und lauscht auf Spracheingaben.

Erstellen einer neuen JavaScript-Anwendung

Erstellen Sie eine neue JavaScript-Anwendung in Ihrem Projektverzeichnis. Initialisieren Sie mit dem folgenden Befehl ein Node.js-Projekt. Damit wird eine Datei „package.json“ für Ihr Projekt erstellt, die zum Verwalten der Abhängigkeiten Ihres Projekts verwendet wird.

npm init -y

Installieren der Anrufautomatisierungs-API von Azure Communication Services

npm install @azure/communication-call-automation

Erstellen Sie eine neue JavaScript-Datei in Ihrem Projektverzeichnis, und benennen Sie sie z. B. mit „app.js“. Sie schreiben Ihren JavaScript-Code in dieser Datei. Führen Sie Ihre Anwendung mit Node.js und dem folgenden Befehl aus. Dadurch wird der von Ihnen geschriebene JavaScript-Code ausgeführt.

node app.js

Einrichten eines Anrufs

An diesem Punkt sollten Sie mit dem Starten von Anrufen vertraut sein. Wenn Sie weitere Informationen zum Tätigen eines Anrufs benötigen, befolgen Sie unseren Schnellstart. In diesem Schnellstart erstellen Sie einen ausgehenden Anruf.

Aufrufen der Erkennungsaktion

Wenn Ihre Anwendung den Anruf annimmt, können Sie Informationen zur Erkennung von Teilnehmereingaben und zur Wiedergabe einer Äußerung bereitstellen.

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); 

Bei Spracherkennungsflows unterstützt die Erkennungsaktion der Anrufautomatisierung auch die Verwendung von benutzerdefinierten Sprachmodellen. Features wie benutzerdefinierte Sprachmodelle können nützlich sein, wenn Sie eine Anwendung erstellen, die auf komplexe Wörter lauschen soll, die die Standardmodelle zur Spracherkennung möglicherweise nicht verstehen. Ein gutes Beispiel hierfür ist, wenn Sie eine Anwendung für die Telemedizinbranche erstellen und Ihr virtueller Agent medizinische Begriffe erkennen muss. Weitere Informationen zum Erstellen und Bereitstellen benutzerdefinierter Sprachmodelle finden Sie hier.

Auswahlmöglichkeiten bei der Spracherkennung

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); 

Spracherkennung

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); 

Sprache-in-Text oder 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); 

Hinweis

Wenn keine Parameter festgelegt sind, werden nach Möglichkeit die Standardwerte angewandt.

Empfangen von Updates zu Erkennungsereignissen

Entwickler und Entwicklerinnen können die Ereignisse RecognizeCompleted und RecognizeFailed im Webhook-Rückruf abonnieren, die sie für den Aufruf registriert haben, um Geschäftslogik in ihrer Anwendung zu erstellen, mit der die nächsten Schritte bestimmt werden, wenn eines der oben genannten Ereignisse eintritt.

Beispiel zur Deserialisierung des RecognizeCompleted-Ereignisses:

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)); 
    } 
} 

Beispiel zur Deserialisierung des RecognizeFailed-Ereignisses:

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

Beispiel zur Deserialisierung des RecognizeCanceled-Ereignisses:

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

Voraussetzungen

• Ein Azure-Konto mit einem aktiven Abonnement. Details finden Sie im Artikel zum Erstellen eines kostenlosen Azure-Kontos.
• Azure Communication Services-Ressource. Siehe Schnellstart: Erstellen und Verwalten einer Communication Services-Ressource. Notieren Sie die Verbindungszeichenfolge für diese Ressource.
• Erstellen einer neuen Webdienstanwendung mithilfe des Call Automation SDK
• Installieren Sie Python, das Sie auf der offiziellen Website erhalten.

Für KI-Features

• Erstellen Sie eine Azure KI Services-Instanz für Ihre Azure Communications Services-Ressource, und stellen Sie eine Verbindung mit ihr her.
• Erstellen Sie eine benutzerdefinierte Subdomäne für Ihre Azure KI Services-Ressource.

Technische Spezifikationen

Die folgenden Parameter stehen zum Anpassen der Erkennungsfunktion zur Verfügung:

Parameter	type	Standard (falls nicht angegeben)	Beschreibung	Erforderlich oder optional
Prompt (Ausführliche Details zur Wiedergabeaktion finden Sie in dieser Schrittanleitung)	FileSource, TextSource	Nicht festgelegt	Dies ist die Nachricht, die Sie vor der Erkennung von Eingaben wiedergeben möchten.	Optional
InterToneTimeout	TimeSpan	2 Sekunden Min: 1 Sekunde Max: 60 Sekunden	Grenzwert in Sekunden, den Azure Communication Services wartet, dass der Anrufer oder die Aufruferin eine weitere Ziffer eingibt (Timeoutwert zwischen Ziffern).	Optional
InitialSegmentationSilenceTimeoutInSeconds	Integer	0,5 Sekunden	Zeitraum, den eine Erkennungsaktion auf Eingaben wartet, bevor sie die Wartezeit als Timeout betrachtet. Weitere Informationen finden Sie hier.	Optional
RecognizeInputsType	Enum	dtmf	Typ der erkannten Eingabedaten. Zur Auswahl stehen „dtmf“, „choices“, „speech“ und „speechordtmf“.	Erforderlich
InitialSilenceTimeout	TimeSpan	5 Sekunden Min: 0 Sekunden Max: 300 Sekunden (DTMF) Max: 20 Sekunden (Auswahl) Max: 20 Sekunden (Sprache)	Initial silence timeout (Anfangsstille-Timeout) passt an, wie viel sprachfremdes Audio vor einem Ausdruck zulässig ist, bevor der Erkennungsversuch mit dem Ergebnis „keine Übereinstimmung“ endet. Weitere Informationen finden Sie hier.	Optional
MaxTonesToCollect	Integer	Kein Standardwert Min: 1	Anzahl der Ziffern, die ein Entwickler als Eingabe vom Teilnehmer erwartet.	Erforderlich
StopTones	IEnumeration<DtmfTone>	Nicht festgelegt	Die Ziffer, die Teilnehmer drücken können, um aus einem Batch-DTMF-Ereignis freizukommen.	Optional
InterruptPrompt	Bool	True	Falls der Teilnehmer die Möglichkeit hat, die playMessage durch Drücken einer Ziffer zu unterbrechen.	Optional
InterruptCallMediaOperation	Bool	True	Wenn dieses Flag festgelegt ist, wird der aktuelle Anrufmedienvorgang unterbrochen. Beispielsweise wird der Vorgang während einer laufenden Wiedergabe unterbrochen und die Erkennung eingeleitet.	Optional
OperationContext	String	Nicht festgelegt	Zeichenfolge, die Entwickler während einer Aktion übergeben können. Damit können Entwickler Kontext zu den empfangenen Ereignissen speichern.	Optional
Ausdrücke	String	Nicht festgelegt	Liste der Ausdrücke, die der Bezeichnung zugeordnet sind. Falls einige davon gehört werden, wird dies als erfolgreiche Erkennung betrachtet.	Erforderlich
Ton	String	Nicht festgelegt	Der Ton, der erkannt werden soll, wenn der Benutzer oder die Benutzerin entscheidet, eine Zahl einzugeben, anstatt die Spracheingabe zu verwenden.	Optional
Label	String	Nicht festgelegt	Der Schlüsselwert für die Erkennung.	Erforderlich
Sprache	String	en-US	Die Sprache, die für die Spracherkennung verwendet wird.	Optional
EndSilenceTimeout	TimeSpan	0,5 Sekunden	Die letzte Pause des Sprechers/der Sprecherin, die zum Erkennen des Endergebnisses verwendet wird, das als Sprache generiert wird.	Optional

Hinweis

In Situationen, in denen sich sowohl DTMF als auch Sprache im recognizeInputsType enthalten sind, verarbeitet die Erkennungsaktion den ersten empfangenen Eingabetyp, d. h., wenn der Benutzer oder die Benutzerin zuerst eine Wähltastaturnummer drückt, betrachtet die Erkennungsaktion die Eingabe als DTMF-Ereignis und lauscht auf weitere DTMF-Töne. Wenn der Benutzer oder die Benutzerin zuerst spricht, wertet die Erkennungsaktion dies als Spracherkennung und lauscht auf Spracheingaben.

Erstellen einer neuen Python-Anwendung

Einrichten einer virtuellen Python-Umgebung für Ihr Projekt

python -m venv play-audio-app

Aktivieren der virtuellen Umgebung

Verwenden Sie unter Windows den folgenden Befehl:

.\ play-audio-quickstart \Scripts\activate

Verwenden Sie unter Unix den folgenden Befehl:

source play-audio-quickstart /bin/activate

Installieren der Anrufautomatisierungs-API von Azure Communication Services

pip install azure-communication-callautomation

Erstellen Sie Ihre Anwendungsdatei in Ihrem Projektverzeichnis, und benennen Sie sie z. B. mit „app.py“. Sie schreiben Ihren Python-Code in dieser Datei.

Führen Sie Ihre Anwendung mit Python und dem folgenden Befehl aus. Dadurch wird der von Ihnen geschriebene Python-Code ausgeführt.

python app.py

Einrichten eines Anrufs

An diesem Punkt sollten Sie mit dem Starten von Anrufen vertraut sein. Wenn Sie weitere Informationen zum Tätigen eines Anrufs benötigen, befolgen Sie unseren Schnellstart. In diesem Schnellstart erstellen Sie einen ausgehenden Anruf.

Aufrufen der Erkennungsaktion

Wenn Ihre Anwendung den Anruf annimmt, können Sie Informationen zur Erkennung von Teilnehmereingaben und zur Wiedergabe einer Äußerung bereitstellen.

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 ]) 

Bei Spracherkennungsflows unterstützt die Erkennungsaktion der Anrufautomatisierung auch die Verwendung von benutzerdefinierten Sprachmodellen. Features wie benutzerdefinierte Sprachmodelle können nützlich sein, wenn Sie eine Anwendung erstellen, die auf komplexe Wörter lauschen soll, die die Standardmodelle zur Spracherkennung möglicherweise nicht verstehen. Ein gutes Beispiel hierfür ist, wenn Sie eine Anwendung für die Telemedizinbranche erstellen und Ihr virtueller Agent medizinische Begriffe erkennen muss. Weitere Informationen zum Erstellen und Bereitstellen benutzerdefinierter Sprachmodelle finden Sie hier.

Auswahlmöglichkeiten bei der Spracherkennung

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

Spracherkennung

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

Sprache-in-Text oder 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") 

Hinweis

Wenn keine Parameter festgelegt sind, werden nach Möglichkeit die Standardwerte angewandt.

Empfangen von Updates zu Erkennungsereignissen

Entwickler und Entwicklerinnen können die Ereignisse RecognizeCompleted und RecognizeFailed im Webhook-Rückruf abonnieren, die sie für den Aufruf registriert haben, um Geschäftslogik in ihrer Anwendung zu erstellen, mit der die nächsten Schritte bestimmt werden, wenn eines der oben genannten Ereignisse eintritt.

Beispiel zur Deserialisierung des RecognizeCompleted-Ereignisses:

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); 

Beispiel zur Deserialisierung des RecognizeFailed-Ereignisses:

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

Beispiel zur Deserialisierung des RecognizeCanceled-Ereignisses:

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

Ereigniscodes

Status	Code	Subcode	`Message`
RecognizeCompleted	200	8531	Aktion abgeschlossen, maximale Ziffern empfangen.
RecognizeCompleted	200	8514	Aktion abgeschlossen, da ein Stoppton erkannt wurde.
RecognizeCompleted	400	8508	Fehler bei der Aktion, der Vorgang wurde abgebrochen.
RecognizeCompleted	400	8532	Fehler bei der Aktion, das Timeout für Stille zwischen Zifferneingaben wurde erreicht.
RecognizeCanceled	400	8508	Fehler bei der Aktion, der Vorgang wurde abgebrochen.
RecognizeFailed	400	8510	Fehler bei der Aktion; das Timeout für anfängliche Stille wurde erreicht.
RecognizeFailed	500	8511	Fehler bei der Aktion, Fehler beim Wiedergeben der Äußerung.
RecognizeFailed	500	8512	Unbekannter interner Serverfehler.
RecognizeFailed	400	8510	Fehler bei der Aktion, das Timeout für anfängliche Stille wurde erreicht
RecognizeFailed	400	8532	Fehler bei der Aktion, das Timeout für Stille zwischen Zifferneingaben wurde erreicht.
RecognizeFailed	400	8565	Fehler bei der Aktion; ungültige Anforderung an Azure KI Services. Eingabeparameter prüfen.
Fehler erkannt	400	8565	Fehler bei der Aktion; ungültige Anforderung an Azure KI Services. Die bereitgestellten Nutzdaten konnten nicht verarbeitet werden, überprüfen Sie die Eingabe der Wiedergabequelle.
RecognizeFailed	401	8565	Fehler bei der Aktion; Azure KI Services-Authentifizierungsfehler.
RecognizeFailed	403	8565	Fehler bei der Aktion; unzulässige Anforderung an Azure KI Services, das bei der Anforderung verwendete kostenlose Abonnement weist kein Kontingent mehr auf.
RecognizeFailed	429	8565	Fehler bei der Aktion; Anzahl der zulässigen gleichzeitigen Anforderungen für das Azure KI Services-Abonnement wurde überschritten.
RecognizeFailed	408	8565	Fehler bei der Aktion; Timeout bei der Anforderung an Azure KI Services.
RecognizeFailed	500	8511	Fehler bei der Aktion, Fehler beim Wiedergeben der Äußerung.
RecognizeFailed	500	8512	Unbekannter interner Serverfehler.

Bekannte Einschränkungen

• In-Band-DTMF wird nicht unterstützt, verwenden Sie stattdessen RFC 2833 DTMF.
• Textprompts für die Sprachsynthese unterstützen maximal 400 Zeichen, wenn Ihr Prompt länger ist, wird die Verwendung von SSML für Wiedergabeaktionen zur Sprachsynthese empfohlen.
• Sie können für Szenarien, in denen Sie Ihre Kontingentgrenze für den Speech-Dienst überschreiten, eine Erhöhung dieses Grenzwerts anfordern, indem Sie die hier beschriebenen Schritte ausführen.

Bereinigen von Ressourcen

Wenn Sie ein Communication Services-Abonnement bereinigen und entfernen möchten, können Sie die Ressource oder die Ressourcengruppe löschen. Wenn Sie die Ressourcengruppe löschen, werden auch alle anderen Ressourcen gelöscht, die ihr zugeordnet sind. Weitere Informationen zum Bereinigen von Ressourcen finden Sie hier.

Nächste Schritte

• Informieren Sie sich ausführlicher über das Sammeln von Benutzereingaben.
• Weitere Informationen zum Wiedergeben von Audiodaten in einem Anruf finden Sie hier.
• Informieren Sie sich ausführlicher über die Anrufautomatisierung.