Samla in användarindata med åtgärden Identifiera

  • Artikel

Den här guiden hjälper dig att komma igång med att känna igen DTMF-indata som tillhandahålls av deltagarna via Azure Communication Services Call Automation SDK.

Förutsättningar

För AI-funktioner

Tekniska specifikationer

Följande parametrar är tillgängliga för att anpassa funktionen Recognize:

Parameter Typ Standard (om det inte anges) beskrivning Obligatoriskt eller valfritt
Snabb

(Mer information om play-åtgärder finns i den här instruktionsguiden)		 FileSource, TextSource Anges inte Det här är det meddelande som du vill spela upp innan du känner igen indata. Valfritt
InterToneTimeout TimeSpan 2 sekunder

Min: 1 sekund
Max: 60 sekunder		 Begränsa i sekunder att Azure Communication Services väntar på att anroparen ska trycka på en annan siffra (tidsgräns mellan siffror). Valfritt
InitialSegmentationSilenceTimeoutInSeconds Integer 0,5 sekunder Hur länge åtgärden för att identifiera väntar på indata innan den överskrids. Läs mer här Valfritt
RecognizeInputsType Enum Dtmf Typ av indata som känns igen. Alternativen är dtmf, val, tal och speechordtmf. Obligatoriskt
InitialSilenceTimeout TimeSpan 5 sekunder

Min: 0 sekunder
Max: 300 sekunder (DTMF)
Max: 20 sekunder (val)
Max: 20 sekunder (tal)		 Den inledande tidsgränsen för tystnad justerar hur mycket ljud utan ljud som tillåts innan en fras innan igenkänningsförsöket slutar med ett resultat av typen "ingen matchning". Läs mer här Valfritt
MaxTonesToCollect Integer Inget standardvärde

Min: 1		 Antal siffror som en utvecklare förväntar sig som indata från deltagaren. Obligatoriskt
StopTones IEnumeration<DtmfTone> Anges inte Den siffra som deltagarna kan trycka på för att fly från en batch-DTMF-händelse. Valfritt
InterruptPrompt Bool Sant Om deltagaren har möjlighet att avbryta playMessage genom att trycka på en siffra. Valfritt
InterruptCallMediaOperation Bool Sant Om den här flaggan anges avbryter den aktuella anropsmedieåtgärden. Om ett ljud till exempel spelas upp avbryter det åtgärden och initierar igenkänningen. Valfritt
OperationContext String Anges inte Sträng som utvecklare kan skicka mitt i åtgärden, användbar för att tillåta utvecklare att lagra kontext om de händelser de får. Valfritt
Fraser String Anges inte Lista över fraser som associerar till etiketten, om någon av dessa hörs anses det vara en lyckad igenkänning. Obligatoriskt
Tonfall String Anges inte Tonen för att känna igen om användaren bestämmer sig för att trycka på ett tal i stället för att använda tal. Valfritt
Etikett String Anges inte Nyckelvärdet för igenkänning. Obligatoriskt
Språk String En-us Det språk som används för att känna igen tal. Valfritt
EndSilenceTimeout TimeSpan 0,5 sekunder Den sista pausen av talaren som används för att identifiera slutresultatet som genereras som tal. Valfritt

Kommentar

I situationer där både dtmf och tal finns i recognizeInputsType, kommer åtgärden recognize att fungera på den första indatatypen som tas emot, dvs. om användaren trycker på ett knappsatsnummer först kommer åtgärden att identifiera att betrakta det som en dtmf-händelse och fortsätta lyssna efter dtmf-toner. Om användaren talar först kommer identifieringsåtgärden att betrakta den som en taligenkänning och lyssna efter röstindata.

Skapa ett nytt C#-program

I konsolfönstret i operativsystemet använder du dotnet kommandot för att skapa ett nytt webbprogram.

dotnet new web -n MyApplication

Installera NuGet-paketet

NuGet-paketet kan hämtas härifrån, om du inte redan har gjort det.

Upprätta ett anrop

Vid det här laget bör du vara bekant med att starta samtal, om du behöver lära dig mer om att ringa ett samtal följer du vår snabbstart. Du kan också använda kodfragmentet här för att förstå hur du besvarar ett samtal.

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

Anropa åtgärden för att identifiera

När programmet svarar på samtalet kan du ange information om hur du känner igen deltagares indata och hur du spelar upp en fråga.

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

För tal-till-text-flöden stöder callautomatiseringsåtgärden även användning av anpassade talmodeller. Funktioner som anpassade talmodeller kan vara användbara när du skapar ett program som behöver lyssna efter komplexa ord som standardmodellerna för tal till text kanske inte kan förstå. Ett bra exempel på detta kan vara när du skapar ett program för den telemedicinska industrin och din virtuella agent måste kunna känna igen medicinska termer. Du kan lära dig mer om att skapa och distribuera anpassade talmodeller här.

Tal-till-text-alternativ

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

Tal till text

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

Tal till text eller 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);

Kommentar

Om parametrar inte anges tillämpas standardvärdena där det är möjligt.

Ta emot uppdateringar av identifiera händelser

Utvecklare kan prenumerera på RecognizeCompleted - och RecognizeFailed-händelserna på webhook-återanropet som de registrerade för anropet för att skapa affärslogik i sitt program för att fastställa nästa steg när en av de tidigare nämnda händelserna inträffar.

Exempel på hur du kan deserialisera händelsen RecognizeCompleted :

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

Exempel på hur du kan deserialisera RecognizeFailed-händelsen :

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

Exempel på hur du kan deserialisera händelsen 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);
        }

Förutsättningar

För AI-funktioner

Tekniska specifikationer

Följande parametrar är tillgängliga för att anpassa funktionen Recognize:

Parameter Typ Standard (om det inte anges) beskrivning Obligatoriskt eller valfritt
Snabb

(Mer information om play-åtgärder finns i den här instruktionsguiden)		 FileSource, TextSource Anges inte Det här är det meddelande som du vill spela upp innan du känner igen indata. Valfritt
InterToneTimeout TimeSpan 2 sekunder

Min: 1 sekund
Max: 60 sekunder		 Begränsa i sekunder att Azure Communication Services väntar på att anroparen ska trycka på en annan siffra (tidsgräns mellan siffror). Valfritt
InitialSegmentationSilenceTimeoutInSeconds Integer 0,5 sekunder Hur länge åtgärden för att identifiera väntar på indata innan den överskrids. Läs mer här Valfritt
RecognizeInputsType Enum Dtmf Typ av indata som känns igen. Alternativen är dtmf, val, tal och speechordtmf. Obligatoriskt
InitialSilenceTimeout TimeSpan 5 sekunder

Min: 0 sekunder
Max: 300 sekunder (DTMF)
Max: 20 sekunder (val)
Max: 20 sekunder (tal)		 Den inledande tidsgränsen för tystnad justerar hur mycket ljud utan ljud som tillåts innan en fras innan igenkänningsförsöket slutar med ett resultat av typen "ingen matchning". Läs mer här Valfritt
MaxTonesToCollect Integer Inget standardvärde

Min: 1		 Antal siffror som en utvecklare förväntar sig som indata från deltagaren. Obligatoriskt
StopTones IEnumeration<DtmfTone> Anges inte Den siffra som deltagarna kan trycka på för att fly från en batch-DTMF-händelse. Valfritt
InterruptPrompt Bool Sant Om deltagaren har möjlighet att avbryta playMessage genom att trycka på en siffra. Valfritt
InterruptCallMediaOperation Bool Sant Om den här flaggan anges avbryter den aktuella anropsmedieåtgärden. Om ett ljud till exempel spelas upp avbryter det åtgärden och initierar igenkänningen. Valfritt
OperationContext String Anges inte Sträng som utvecklare kan skicka mitt i åtgärden, användbar för att tillåta utvecklare att lagra kontext om de händelser de får. Valfritt
Fraser String Anges inte Lista över fraser som associerar till etiketten, om någon av dessa hörs anses det vara en lyckad igenkänning. Obligatoriskt
Tonfall String Anges inte Tonen för att känna igen om användaren bestämmer sig för att trycka på ett tal i stället för att använda tal. Valfritt
Etikett String Anges inte Nyckelvärdet för igenkänning. Obligatoriskt
Språk String En-us Det språk som används för att känna igen tal. Valfritt
EndSilenceTimeout TimeSpan 0,5 sekunder Den sista pausen av talaren som används för att identifiera slutresultatet som genereras som tal. Valfritt

Kommentar

I situationer där både dtmf och tal finns i recognizeInputsType, kommer åtgärden recognize att fungera på den första indatatypen som tas emot, dvs. om användaren trycker på ett knappsatsnummer först kommer åtgärden att identifiera att betrakta det som en dtmf-händelse och fortsätta lyssna efter dtmf-toner. Om användaren talar först kommer identifieringsåtgärden att betrakta den som en taligenkänning och lyssna efter röstindata.

Skapa ett nytt Java-program

I terminalen eller kommandofönstret navigerar du till den katalog där du vill skapa java-programmet. mvn Kör kommandot för att generera Java-projektet från mallen maven-archetype-quickstart.

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

Kommandot mvn skapar en katalog med samma namn som artifactId argumentet. Under den här katalogen src/main/java innehåller katalogen projektets källkod, src/test/java katalogen innehåller testkällan.

Du märker att steget "generera" skapade en katalog med samma namn som artifactId. Under den här katalogen src/main/java innehåller katalogen källkod, src/test/java katalogen innehåller tester och pom.xml filen är projektets projektobjektmodell eller POM.

Uppdatera pom-filen för dina program så att den använder Java 8 eller senare.

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

Lägga till paketreferenser

I POM-filen lägger du till följande referens för projektet

azure-communication-callautomation

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

Upprätta ett anrop

Vid det här laget bör du vara bekant med att starta samtal, om du behöver lära dig mer om att ringa ett samtal följer du vår snabbstart. Du kan också använda kodfragmentet här för att förstå hur du besvarar ett samtal.

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

Anropa åtgärden för att identifiera

När programmet svarar på samtalet kan du ange information om hur du känner igen deltagares indata och hur du spelar upp en fråga.

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

För tal-till-text-flöden stöder callautomatiseringsåtgärden även användning av anpassade talmodeller. Funktioner som anpassade talmodeller kan vara användbara när du skapar ett program som behöver lyssna efter komplexa ord som standardmodellerna för tal till text kanske inte kan förstå. Ett bra exempel på detta kan vara när du skapar ett program för den telemedicinska industrin och din virtuella agent måste kunna känna igen medicinska termer. Du kan lära dig mer om att skapa och distribuera anpassade talmodeller här.

Tal-till-text-alternativ

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

Tal till text

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

Tal till text eller 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();

Kommentar

Om parametrar inte anges tillämpas standardvärdena där det är möjligt.

Ta emot uppdateringar av identifiera händelser

Utvecklare kan prenumerera på RecognizeCompleted - och RecognizeFailed-händelser på det registrerade webhook-återanropet. Den här motringningen kan användas med affärslogik i ditt program för att fastställa nästa steg när en av händelserna inträffar.

Exempel på hur du kan deserialisera händelsen RecognizeCompleted :

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

Exempel på hur du kan deserialisera RecognizeFailed-händelsen :

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

Exempel på hur du kan deserialisera händelsen RecognizeCanceled :

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

Förutsättningar

För AI-funktioner

Tekniska specifikationer

Följande parametrar är tillgängliga för att anpassa funktionen Recognize:

Parameter Typ Standard (om det inte anges) beskrivning Obligatoriskt eller valfritt
Snabb

(Mer information om play-åtgärder finns i den här instruktionsguiden)		 FileSource, TextSource Anges inte Det här är det meddelande som du vill spela upp innan du känner igen indata. Valfritt
InterToneTimeout TimeSpan 2 sekunder

Min: 1 sekund
Max: 60 sekunder		 Begränsa i sekunder att Azure Communication Services väntar på att anroparen ska trycka på en annan siffra (tidsgräns mellan siffror). Valfritt
InitialSegmentationSilenceTimeoutInSeconds Integer 0,5 sekunder Hur länge åtgärden för att identifiera väntar på indata innan den överskrids. Läs mer här Valfritt
RecognizeInputsType Enum Dtmf Typ av indata som känns igen. Alternativen är dtmf, val, tal och speechordtmf. Obligatoriskt
InitialSilenceTimeout TimeSpan 5 sekunder

Min: 0 sekunder
Max: 300 sekunder (DTMF)
Max: 20 sekunder (val)
Max: 20 sekunder (tal)		 Den inledande tidsgränsen för tystnad justerar hur mycket ljud utan ljud som tillåts innan en fras innan igenkänningsförsöket slutar med ett resultat av typen "ingen matchning". Läs mer här Valfritt
MaxTonesToCollect Integer Inget standardvärde

Min: 1		 Antal siffror som en utvecklare förväntar sig som indata från deltagaren. Obligatoriskt
StopTones IEnumeration<DtmfTone> Anges inte Den siffra som deltagarna kan trycka på för att fly från en batch-DTMF-händelse. Valfritt
InterruptPrompt Bool Sant Om deltagaren har möjlighet att avbryta playMessage genom att trycka på en siffra. Valfritt
InterruptCallMediaOperation Bool Sant Om den här flaggan anges avbryter den aktuella anropsmedieåtgärden. Om ett ljud till exempel spelas upp avbryter det åtgärden och initierar igenkänningen. Valfritt
OperationContext String Anges inte Sträng som utvecklare kan skicka mitt i åtgärden, användbar för att tillåta utvecklare att lagra kontext om de händelser de får. Valfritt
Fraser String Anges inte Lista över fraser som associerar till etiketten, om någon av dessa hörs anses det vara en lyckad igenkänning. Obligatoriskt
Tonfall String Anges inte Tonen för att känna igen om användaren bestämmer sig för att trycka på ett tal i stället för att använda tal. Valfritt
Etikett String Anges inte Nyckelvärdet för igenkänning. Obligatoriskt
Språk String En-us Det språk som används för att känna igen tal. Valfritt
EndSilenceTimeout TimeSpan 0,5 sekunder Den sista pausen av talaren som används för att identifiera slutresultatet som genereras som tal. Valfritt

Kommentar

I situationer där både dtmf och tal finns i recognizeInputsType, kommer åtgärden recognize att fungera på den första indatatypen som tas emot, dvs. om användaren trycker på ett knappsatsnummer först kommer åtgärden att identifiera att betrakta det som en dtmf-händelse och fortsätta lyssna efter dtmf-toner. Om användaren talar först kommer identifieringsåtgärden att betrakta den som en taligenkänning och lyssna efter röstindata.

Skapa ett nytt JavaScript-program

Skapa ett nytt JavaScript-program i projektkatalogen. Initiera ett nytt Node.js projekt med följande kommando. Detta skapar en package.json fil för projektet, som används för att hantera projektets beroenden.

npm init -y

Installera Azure Communication Services Call Automation-paketet

npm install @azure/communication-call-automation

Skapa en ny JavaScript-fil i projektkatalogen, till exempel ge den namnet app.js. Du skriver JavaScript-koden i den här filen. Kör programmet med Node.js med följande kommando. Detta kör JavaScript-koden som du har skrivit.

node app.js

Upprätta ett anrop

Vid det här laget bör du vara bekant med att starta samtal, om du behöver lära dig mer om att ringa ett samtal följer du vår snabbstart. I den här snabbstarten skapar vi ett utgående anrop.

Anropa åtgärden för att identifiera

När programmet svarar på samtalet kan du ange information om hur du känner igen deltagares indata och hur du spelar upp en fråga.

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

För tal-till-text-flöden stöder callautomatiseringsåtgärden även användning av anpassade talmodeller. Funktioner som anpassade talmodeller kan vara användbara när du skapar ett program som behöver lyssna efter komplexa ord som standardmodellerna för tal till text kanske inte kan förstå. Ett bra exempel på detta kan vara när du skapar ett program för den telemedicinska industrin och din virtuella agent måste kunna känna igen medicinska termer. Du kan lära dig mer om att skapa och distribuera anpassade talmodeller här.

Tal-till-text-alternativ

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

Tal till text

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

Tal till text eller 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);

Kommentar

Om parametrar inte anges tillämpas standardvärdena där det är möjligt.

Ta emot uppdateringar av identifiera händelser

Utvecklare kan prenumerera på RecognizeCompleted - och RecognizeFailed-händelserna på webhook-återanropet som de registrerade för anropet för att skapa affärslogik i sitt program för att fastställa nästa steg när en av de tidigare nämnda händelserna inträffar.

Exempel på hur du kan deserialisera händelsen RecognizeCompleted :

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

Exempel på hur du kan deserialisera RecognizeFailed-händelsen :

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

Exempel på hur du kan deserialisera händelsen RecognizeCanceled :

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

Förutsättningar

För AI-funktioner

Tekniska specifikationer

Följande parametrar är tillgängliga för att anpassa funktionen Recognize:

Parameter Typ Standard (om det inte anges) beskrivning Obligatoriskt eller valfritt
Snabb

(Mer information om play-åtgärder finns i den här instruktionsguiden)		 FileSource, TextSource Anges inte Det här är det meddelande som du vill spela upp innan du känner igen indata. Valfritt
InterToneTimeout TimeSpan 2 sekunder

Min: 1 sekund
Max: 60 sekunder		 Begränsa i sekunder att Azure Communication Services väntar på att anroparen ska trycka på en annan siffra (tidsgräns mellan siffror). Valfritt
InitialSegmentationSilenceTimeoutInSeconds Integer 0,5 sekunder Hur länge åtgärden för att identifiera väntar på indata innan den överskrids. Läs mer här Valfritt
RecognizeInputsType Enum Dtmf Typ av indata som känns igen. Alternativen är dtmf, val, tal och speechordtmf. Obligatoriskt
InitialSilenceTimeout TimeSpan 5 sekunder

Min: 0 sekunder
Max: 300 sekunder (DTMF)
Max: 20 sekunder (val)
Max: 20 sekunder (tal)		 Den inledande tidsgränsen för tystnad justerar hur mycket ljud utan ljud som tillåts innan en fras innan igenkänningsförsöket slutar med ett resultat av typen "ingen matchning". Läs mer här Valfritt
MaxTonesToCollect Integer Inget standardvärde

Min: 1		 Antal siffror som en utvecklare förväntar sig som indata från deltagaren. Obligatoriskt
StopTones IEnumeration<DtmfTone> Anges inte Den siffra som deltagarna kan trycka på för att fly från en batch-DTMF-händelse. Valfritt
InterruptPrompt Bool Sant Om deltagaren har möjlighet att avbryta playMessage genom att trycka på en siffra. Valfritt
InterruptCallMediaOperation Bool Sant Om den här flaggan anges avbryter den aktuella anropsmedieåtgärden. Om ett ljud till exempel spelas upp avbryter det åtgärden och initierar igenkänningen. Valfritt
OperationContext String Anges inte Sträng som utvecklare kan skicka mitt i åtgärden, användbar för att tillåta utvecklare att lagra kontext om de händelser de får. Valfritt
Fraser String Anges inte Lista över fraser som associerar till etiketten, om någon av dessa hörs anses det vara en lyckad igenkänning. Obligatoriskt
Tonfall String Anges inte Tonen för att känna igen om användaren bestämmer sig för att trycka på ett tal i stället för att använda tal. Valfritt
Etikett String Anges inte Nyckelvärdet för igenkänning. Obligatoriskt
Språk String En-us Det språk som används för att känna igen tal. Valfritt
EndSilenceTimeout TimeSpan 0,5 sekunder Den sista pausen av talaren som används för att identifiera slutresultatet som genereras som tal. Valfritt

Kommentar

I situationer där både dtmf och tal finns i recognizeInputsType, kommer åtgärden recognize att fungera på den första indatatypen som tas emot, dvs. om användaren trycker på ett knappsatsnummer först kommer åtgärden att identifiera att betrakta det som en dtmf-händelse och fortsätta lyssna efter dtmf-toner. Om användaren talar först kommer identifieringsåtgärden att betrakta den som en taligenkänning och lyssna efter röstindata.

Skapa ett nytt Python-program

Konfigurera en virtuell Python-miljö för projektet

python -m venv play-audio-app

Aktivera din virtuella miljö

Använd följande kommando i Windows:

.\ play-audio-quickstart \Scripts\activate

Använd följande kommando i Unix:

source play-audio-quickstart /bin/activate

Installera Azure Communication Services Call Automation-paketet

pip install azure-communication-callautomation

Skapa programfilen i projektkatalogen, till exempel ge den namnet app.py. Du skriver Python-koden i den här filen.

Kör programmet med hjälp av Python med följande kommando. Detta kör Den Python-kod som du har skrivit.

python app.py

Upprätta ett anrop

Vid det här laget bör du vara bekant med att starta samtal, om du behöver lära dig mer om att ringa ett samtal följer du vår snabbstart. I den här snabbstarten skapar vi ett utgående anrop.

Anropa åtgärden för att identifiera

När programmet svarar på samtalet kan du ange information om hur du känner igen deltagares indata och hur du spelar upp en fråga.

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

För tal-till-text-flöden stöder callautomatiseringsåtgärden även användning av anpassade talmodeller. Funktioner som anpassade talmodeller kan vara användbara när du skapar ett program som behöver lyssna efter komplexa ord som standardmodellerna för tal till text kanske inte kan förstå. Ett bra exempel på detta kan vara när du skapar ett program för den telemedicinska industrin och din virtuella agent måste kunna känna igen medicinska termer. Du kan lära dig mer om att skapa och distribuera anpassade talmodeller här.

Tal-till-text-alternativ

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

Tal till text

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

Tal till text eller 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")

Kommentar

Om parametrar inte anges tillämpas standardvärdena där det är möjligt.

Ta emot uppdateringar av identifiera händelser

Utvecklare kan prenumerera på RecognizeCompleted - och RecognizeFailed-händelserna på webhook-återanropet som de registrerade för anropet för att skapa affärslogik i sitt program för att fastställa nästa steg när en av de tidigare nämnda händelserna inträffar.

Exempel på hur du kan deserialisera händelsen RecognizeCompleted :

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

Exempel på hur du kan deserialisera RecognizeFailed-händelsen :

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

Exempel på hur du kan deserialisera händelsen RecognizeCanceled :

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

Händelsekoder

Status Kod Underkod Meddelande
RecognizeCompleted 200 8531 Åtgärden har slutförts, maximalt antal mottagna siffror.
RecognizeCompleted 200 8514 Åtgärden slutfördes när stopptonen identifierades.
RecognizeCompleted 400 8508 Åtgärden misslyckades, åtgärden avbröts.
RecognizeCompleted 400 8532 Åtgärden misslyckades, tidsgränsen för tystnad mellan siffror uppnåddes.
RecognizeCanceled 400 8508 Åtgärden misslyckades, åtgärden avbröts.
RecognizeFailed 400 8510 Åtgärden misslyckades, tidsgränsen för inledande tystnad uppnåddes.
RecognizeFailed 500 8511 Åtgärden misslyckades, påträffade ett fel när kommandotolken skulle spelas upp.
RecognizeFailed 500 8512 Okänt internt serverfel.
RecognizeFailed 400 8510 Åtgärden misslyckades, tidsgränsen för inledande tystnad uppnåddes
RecognizeFailed 400 8532 Åtgärden misslyckades, tidsgränsen för tystnad mellan siffror uppnåddes.
RecognizeFailed 400 8565 Åtgärden misslyckades, felaktig begäran till Azure AI-tjänster. Kontrollera indataparametrar.
Det gick inte att identifiera 400 8565 Åtgärden misslyckades, felaktig begäran till Azure AI-tjänster. Det går inte att bearbeta den angivna nyttolasten, kontrollera indata från uppspelningskällan
RecognizeFailed 401 8565 Åtgärden misslyckades, autentiseringsfel för Azure AI-tjänster.
RecognizeFailed 403 8565 Åtgärden misslyckades, den förbjudna begäran till Azure AI-tjänster, den kostnadsfria prenumerationen som användes av begäran tog slut.
RecognizeFailed 429 8565 Åtgärden misslyckades, begäranden överskred antalet tillåtna samtidiga begäranden för Azure AI-tjänsteprenumerationen.
RecognizeFailed 408 8565 Åtgärden misslyckades, tidsgränsen för begäran till Azure AI-tjänster.
RecognizeFailed 500 8511 Åtgärden misslyckades, påträffade ett fel när kommandotolken skulle spelas upp.
RecognizeFailed 500 8512 Okänt internt serverfel.

Kända begränsningar

  • In-band DTMF stöds inte, använd RFC 2833 DTMF i stället.
  • Text-till-tal-textprompter stöder högst 400 tecken, om din fråga är längre än detta föreslår vi att du använder SSML för text-till-tal-baserade uppspelningsåtgärder.
  • För scenarier där du överskrider kvotgränsen för Speech-tjänsten kan du begära att den här lilmiten ökar genom att följa stegen som beskrivs här.

Rensa resurser

Om du vill rensa och ta bort en Communication Services-prenumeration kan du ta bort resursen eller resursgruppen. Om du tar bort resursgruppen tas även alla andra resurser som är associerade med den bort. Läs mer om att rensa resurser.

Nästa steg