Compartir a través de

Recopilación de entradas de usuario con la acción Reconocer

  • Artículo

Esta guía le ayudará a empezar a reconocer la entrada DTMF proporcionada por los participantes a través del SDK de Automatización de llamadas de Azure Communication Services.

Requisitos previos

Para las características de IA

Especificaciones técnicas

Los parámetros siguientes están disponibles para personalizar la función Recognize:

Parámetro Tipo Valor predeterminado (si no se especifica) Descripción Requerido u Opcional
Prompt

(para obtener más información sobre la acción Reproducir, consulte esta guía paso a paso)		 FileSource, TextSource Sin establecer Este es el mensaje que quieres reproducir antes de reconocer la entrada. Opcionales
InterToneTimeout TimeSpan 2 segundos

Min: 1 segundo
Máximo: 60 segundos		 Limite en segundos que Azure Communication Services espera a que el autor de la llamada presione otro dígito (tiempo de espera entre dígitos). Opcionales
InitialSegmentationSilenceTimeoutInSeconds Entero 0.5 segundos Cuánto tiempo espera la acción de reconocimiento para la entrada antes de considerarlo un tiempo de espera. Puede obtener más información aquí. Opcionales
RecognizeInputsType Enum dtmf Tipo de entrada que se reconoce. Las opciones son dtmf, opciones, voz y speechordtmf. Obligatorio
InitialSilenceTimeout TimeSpan 5 segundos

Min: 0 segundos
Máximo: 300 segundos (DTMF)
Máximo: 20 segundos (opciones)
Máximo: 20 segundos (voz)		 El tiempo de espera de silencio inicial ajusta la cantidad de audio que no es de voz permitida antes de una frase antes de que el intento de reconocimiento termine en un resultado "sin coincidencia". Puede obtener más información aquí. Opcionales
MaxTonesToCollect Entero Sin valor predeterminado

Min: 1		 Número de dígitos que un desarrollador espera como entrada del participante. Obligatorio
StopTones IEnumeration<DtmfTone> Sin establecer Los participantes de dígitos pueden presionar para escapar de un evento DTMF por lotes. Opcionales
InterruptPrompt Booleano True Si el participante tiene la capacidad de interrumpir el playMessage presionando un dígito. Opcionales
InterruptCallMediaOperation Booleano True Si se establece esta marca, se interrumpe la operación multimedia de llamada actual. Por ejemplo, si se reproduce algún audio, se interrumpe esa operación y se inicia el reconocimiento. Opcionales
OperationContext Cadena Sin establecer Cadena que los desarrolladores pueden pasar la acción intermedia, útil para permitir que los desarrolladores almacenen contexto sobre los eventos que reciben. Opcionales
Frases Cadena Sin establecer Lista de frases que se asocian a la etiqueta, si alguna de estas se escucha, se considera un reconocimiento correcto. Obligatorio
Tono Cadena Sin establecer Tono que se debe reconocer si el usuario decide presionar un número en lugar de usar la voz. Opcionales
Etiqueta Cadena Sin establecer Valor clave para el reconocimiento. Obligatorio
Lenguaje Cadena En-us Idioma que se usa para el reconocimiento de la voz. Opcionales
EndSilenceTimeout TimeSpan 0.5 segundos La pausa final del hablante usada para detectar el resultado final que se genera como voz. Opcionales

Nota:

En situaciones en las que tanto dtmf como voz se encuentran en recognizeInputsType, la acción de reconocimiento actuará sobre el primer tipo de entrada recibido, es decir, si el usuario presiona un número de teclado primero, la acción de reconocimiento la considerará un evento dtmf y continuará escuchando los tonos dtmf. Si el usuario habla primero, la acción reconocerá que es un reconocimiento de voz y escuchará la entrada de voz.

Creación de una aplicación de C#

En la ventana de consola del sistema operativo, use el comando dotnet para crear una aplicación web.

dotnet new web -n MyApplication

Instalación del paquete NuGet.

El paquete NuGet se puede obtener desde aquí, si aún no lo has hecho.

Establecimiento de una llamada

En este punto, debe estar familiarizado con el inicio de llamadas, si necesita obtener más información sobre cómo realizar una llamada, siga nuestro inicio rápido. También puedes usar el fragmento de código proporcionado aquí para comprender cómo responder a una llamada.

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

Llamada a la acción de reconocimiento

Cuando la aplicación responde a la llamada, puede proporcionar información sobre cómo reconocer la entrada del participante y reproducir un mensaje.

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

En el caso de los flujos de conversión de voz a texto, la acción de reconocimiento de automatización de llamadas también admite el uso de modelos de voz personalizados. Las características como los modelos de voz personalizados pueden ser útiles cuando se crea una aplicación que necesita escuchar palabras complejas que los modelos predeterminados de conversión de voz a texto pueden no ser capaces de entender, un buen ejemplo de esto puede ser cuando se crea una aplicación para el sector telemédico y el agente virtual debe ser capaz de reconocer términos médicos. Puedes obtener más información sobre cómo crear e implementar modelos de voz personalizados aquí.

Opciones de conversión de voz en texto

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

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

Conversión de voz en texto o 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);

Nota:

Si no se establecen parámetros, los valores predeterminados se aplican siempre que sea posible.

Recepción de actualizaciones de eventos de reconocimiento

Los desarrolladores pueden suscribirse a los eventos RecognizeCompleted y RecognizeFailed en la devolución de llamada de webhook que registraron para la llamada para crear lógica de negocios en su aplicación para determinar los pasos siguientes cuando se produce uno de los eventos mencionados anteriormente.

Ejemplo de cómo se puede deserializar el evento 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; 
    } 
}

Ejemplo de cómo se puede deserializar el evento RecognizeFailed:

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

Ejemplo de cómo se puede deserializar el evento 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);
        }

Requisitos previos

Para las características de IA

Especificaciones técnicas

Los parámetros siguientes están disponibles para personalizar la función Recognize:

Parámetro Tipo Valor predeterminado (si no se especifica) Descripción Requerido u Opcional
Prompt

(para obtener más información sobre la acción Reproducir, consulte esta guía paso a paso)		 FileSource, TextSource Sin establecer Este es el mensaje que quieres reproducir antes de reconocer la entrada. Opcionales
InterToneTimeout TimeSpan 2 segundos

Min: 1 segundo
Máximo: 60 segundos		 Limite en segundos que Azure Communication Services espera a que el autor de la llamada presione otro dígito (tiempo de espera entre dígitos). Opcionales
InitialSegmentationSilenceTimeoutInSeconds Entero 0.5 segundos Cuánto tiempo espera la acción de reconocimiento para la entrada antes de considerarlo un tiempo de espera. Puede obtener más información aquí. Opcionales
RecognizeInputsType Enum dtmf Tipo de entrada que se reconoce. Las opciones son dtmf, opciones, voz y speechordtmf. Obligatorio
InitialSilenceTimeout TimeSpan 5 segundos

Min: 0 segundos
Máximo: 300 segundos (DTMF)
Máximo: 20 segundos (opciones)
Máximo: 20 segundos (voz)		 El tiempo de espera de silencio inicial ajusta la cantidad de audio que no es de voz permitida antes de una frase antes de que el intento de reconocimiento termine en un resultado "sin coincidencia". Puede obtener más información aquí. Opcionales
MaxTonesToCollect Entero Sin valor predeterminado

Min: 1		 Número de dígitos que un desarrollador espera como entrada del participante. Obligatorio
StopTones IEnumeration<DtmfTone> Sin establecer Los participantes de dígitos pueden presionar para escapar de un evento DTMF por lotes. Opcionales
InterruptPrompt Booleano True Si el participante tiene la capacidad de interrumpir el playMessage presionando un dígito. Opcionales
InterruptCallMediaOperation Booleano True Si se establece esta marca, se interrumpe la operación multimedia de llamada actual. Por ejemplo, si se reproduce algún audio, se interrumpe esa operación y se inicia el reconocimiento. Opcionales
OperationContext Cadena Sin establecer Cadena que los desarrolladores pueden pasar la acción intermedia, útil para permitir que los desarrolladores almacenen contexto sobre los eventos que reciben. Opcionales
Frases Cadena Sin establecer Lista de frases que se asocian a la etiqueta, si alguna de estas se escucha, se considera un reconocimiento correcto. Obligatorio
Tono Cadena Sin establecer Tono que se debe reconocer si el usuario decide presionar un número en lugar de usar la voz. Opcionales
Etiqueta Cadena Sin establecer Valor clave para el reconocimiento. Obligatorio
Lenguaje Cadena En-us Idioma que se usa para el reconocimiento de la voz. Opcionales
EndSilenceTimeout TimeSpan 0.5 segundos La pausa final del hablante usada para detectar el resultado final que se genera como voz. Opcionales

Nota:

En situaciones en las que tanto dtmf como voz se encuentran en recognizeInputsType, la acción de reconocimiento actuará sobre el primer tipo de entrada recibido, es decir, si el usuario presiona un número de teclado primero, la acción de reconocimiento la considerará un evento dtmf y continuará escuchando los tonos dtmf. Si el usuario habla primero, la acción reconocerá que es un reconocimiento de voz y escuchará la entrada de voz.

Creación de una aplicación Java

En la ventana de terminal o de comandos, navegue hasta el directorio en el que quiere crear la aplicación de Java. Ejecuta el comando mvn para generar el proyecto de Java a partir de la plantilla maven-archetype-quickstart.

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

El comando mvn crea un directorio con el mismo nombre que el argumento artifactId. En este directorio, el directorio src/main/java contiene el código fuente del proyecto, el directorio src/test/java contiene el origen de prueba.

Verás que el paso ‘generar’ creó un directorio con el mismo nombre que el objeto artifactId. En este directorio, el directorio src/main/java contiene el código fuente, el directorio src/test/java contiene pruebas, y el archivo pom.xml es el modelo de objetos del proyecto o POM.

Actualice el archivo POM de la aplicación para usar Java 8 o posterior.

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

Incorporación de referencias de paquete

En el archivo POM, agregue la siguiente referencia para el proyecto

azure-communication-callautomation

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

Establecimiento de una llamada

En este punto, debe estar familiarizado con el inicio de llamadas, si necesita obtener más información sobre cómo realizar una llamada, siga nuestro inicio rápido. También puedes usar el fragmento de código proporcionado aquí para comprender cómo responder a una llamada.

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

Llamada a la acción de reconocimiento

Cuando la aplicación responde a la llamada, puede proporcionar información sobre cómo reconocer la entrada del participante y reproducir un mensaje.

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

En el caso de los flujos de conversión de voz a texto, la acción de reconocimiento de automatización de llamadas también admite el uso de modelos de voz personalizados. Las características como los modelos de voz personalizados pueden ser útiles cuando se crea una aplicación que necesita escuchar palabras complejas que los modelos predeterminados de conversión de voz a texto pueden no ser capaces de entender, un buen ejemplo de esto puede ser cuando se crea una aplicación para el sector telemédico y el agente virtual debe ser capaz de reconocer términos médicos. Puedes obtener más información sobre cómo crear e implementar modelos de voz personalizados aquí.

Opciones de conversión de voz en texto

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

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

Conversión de voz en texto o 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();

Nota:

Si no se establecen parámetros, los valores predeterminados se aplican siempre que sea posible.

Recepción de actualizaciones de eventos de reconocimiento

Los desarrolladores pueden suscribirse a eventos RecognizeCompleted y RecognizeFailed en la devolución de llamada de webhook registrada. Esta devolución de llamada se puede usar con lógica de negocios en la aplicación para determinar los pasos siguientes cuando se produce uno de los eventos.

Ejemplo de cómo se puede deserializar el evento 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()); 
    } 
}

Ejemplo de cómo se puede deserializar el evento RecognizeFailed:

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

Ejemplo de cómo se puede deserializar el evento RecognizeCanceled:

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

Requisitos previos

Para las características de IA

Especificaciones técnicas

Los parámetros siguientes están disponibles para personalizar la función Recognize:

Parámetro Tipo Valor predeterminado (si no se especifica) Descripción Requerido u Opcional
Prompt

(para obtener más información sobre la acción Reproducir, consulte esta guía paso a paso)		 FileSource, TextSource Sin establecer Este es el mensaje que quieres reproducir antes de reconocer la entrada. Opcionales
InterToneTimeout TimeSpan 2 segundos

Min: 1 segundo
Máximo: 60 segundos		 Limite en segundos que Azure Communication Services espera a que el autor de la llamada presione otro dígito (tiempo de espera entre dígitos). Opcionales
InitialSegmentationSilenceTimeoutInSeconds Entero 0.5 segundos Cuánto tiempo espera la acción de reconocimiento para la entrada antes de considerarlo un tiempo de espera. Puede obtener más información aquí. Opcionales
RecognizeInputsType Enum dtmf Tipo de entrada que se reconoce. Las opciones son dtmf, opciones, voz y speechordtmf. Obligatorio
InitialSilenceTimeout TimeSpan 5 segundos

Min: 0 segundos
Máximo: 300 segundos (DTMF)
Máximo: 20 segundos (opciones)
Máximo: 20 segundos (voz)		 El tiempo de espera de silencio inicial ajusta la cantidad de audio que no es de voz permitida antes de una frase antes de que el intento de reconocimiento termine en un resultado "sin coincidencia". Puede obtener más información aquí. Opcionales
MaxTonesToCollect Entero Sin valor predeterminado

Min: 1		 Número de dígitos que un desarrollador espera como entrada del participante. Obligatorio
StopTones IEnumeration<DtmfTone> Sin establecer Los participantes de dígitos pueden presionar para escapar de un evento DTMF por lotes. Opcionales
InterruptPrompt Booleano True Si el participante tiene la capacidad de interrumpir el playMessage presionando un dígito. Opcionales
InterruptCallMediaOperation Booleano True Si se establece esta marca, se interrumpe la operación multimedia de llamada actual. Por ejemplo, si se reproduce algún audio, se interrumpe esa operación y se inicia el reconocimiento. Opcionales
OperationContext Cadena Sin establecer Cadena que los desarrolladores pueden pasar la acción intermedia, útil para permitir que los desarrolladores almacenen contexto sobre los eventos que reciben. Opcionales
Frases Cadena Sin establecer Lista de frases que se asocian a la etiqueta, si alguna de estas se escucha, se considera un reconocimiento correcto. Obligatorio
Tono Cadena Sin establecer Tono que se debe reconocer si el usuario decide presionar un número en lugar de usar la voz. Opcionales
Etiqueta Cadena Sin establecer Valor clave para el reconocimiento. Obligatorio
Lenguaje Cadena En-us Idioma que se usa para el reconocimiento de la voz. Opcionales
EndSilenceTimeout TimeSpan 0.5 segundos La pausa final del hablante usada para detectar el resultado final que se genera como voz. Opcionales

Nota:

En situaciones en las que tanto dtmf como voz se encuentran en recognizeInputsType, la acción de reconocimiento actuará sobre el primer tipo de entrada recibido, es decir, si el usuario presiona un número de teclado primero, la acción de reconocimiento la considerará un evento dtmf y continuará escuchando los tonos dtmf. Si el usuario habla primero, la acción reconocerá que es un reconocimiento de voz y escuchará la entrada de voz.

Creación de una aplicación de JavaScript

Crea una nueva aplicación de JavaScript en el directorio del proyecto. Inicia un nuevo proyecto de Node.js con el siguiente comando. Esto crea un archivo package.json para el proyecto, que se usa para administrar las dependencias del proyecto.

npm init -y

Instalación del paquete de Automatización de llamadas de Azure Communication Services

npm install @azure/communication-call-automation

Crea un nuevo archivo JavaScript en el directorio del proyecto, por ejemplo, asígnale el nombre app.js. Escribe el código JavaScript en este archivo. Ejecuta la aplicación mediante Node.js con el comando siguiente. Esto ejecuta el código JavaScript que has escrito.

node app.js

Establecimiento de una llamada

En este punto, debe estar familiarizado con el inicio de llamadas, si necesita obtener más información sobre cómo realizar una llamada, siga nuestro inicio rápido. En este inicio rápido, creamos una llamada saliente.

Llamada a la acción de reconocimiento

Cuando la aplicación responde a la llamada, puede proporcionar información sobre cómo reconocer la entrada del participante y reproducir un mensaje.

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

En el caso de los flujos de conversión de voz a texto, la acción de reconocimiento de automatización de llamadas también admite el uso de modelos de voz personalizados. Las características como los modelos de voz personalizados pueden ser útiles cuando se crea una aplicación que necesita escuchar palabras complejas que los modelos predeterminados de conversión de voz a texto pueden no ser capaces de entender, un buen ejemplo de esto puede ser cuando se crea una aplicación para el sector telemédico y el agente virtual debe ser capaz de reconocer términos médicos. Puedes obtener más información sobre cómo crear e implementar modelos de voz personalizados aquí.

Opciones de conversión de voz en texto

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

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

Conversión de voz en texto o 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);

Nota:

Si no se establecen parámetros, los valores predeterminados se aplican siempre que sea posible.

Recepción de actualizaciones de eventos de reconocimiento

Los desarrolladores pueden suscribirse a los eventos RecognizeCompleted y RecognizeFailed en la devolución de llamada de webhook que registraron para la llamada para crear lógica de negocios en su aplicación para determinar los pasos siguientes cuando se produce uno de los eventos mencionados anteriormente.

Ejemplo de cómo se puede deserializar el evento 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)); 
    } 
}

Ejemplo de cómo se puede deserializar el evento RecognizeFailed:

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

Ejemplo de cómo se puede deserializar el evento RecognizeCanceled:

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

Requisitos previos

Para las características de IA

Especificaciones técnicas

Los parámetros siguientes están disponibles para personalizar la función Recognize:

Parámetro Tipo Valor predeterminado (si no se especifica) Descripción Requerido u Opcional
Prompt

(para obtener más información sobre la acción Reproducir, consulte esta guía paso a paso)		 FileSource, TextSource Sin establecer Este es el mensaje que quieres reproducir antes de reconocer la entrada. Opcionales
InterToneTimeout TimeSpan 2 segundos

Min: 1 segundo
Máximo: 60 segundos		 Limite en segundos que Azure Communication Services espera a que el autor de la llamada presione otro dígito (tiempo de espera entre dígitos). Opcionales
InitialSegmentationSilenceTimeoutInSeconds Entero 0.5 segundos Cuánto tiempo espera la acción de reconocimiento para la entrada antes de considerarlo un tiempo de espera. Puede obtener más información aquí. Opcionales
RecognizeInputsType Enum dtmf Tipo de entrada que se reconoce. Las opciones son dtmf, opciones, voz y speechordtmf. Obligatorio
InitialSilenceTimeout TimeSpan 5 segundos

Min: 0 segundos
Máximo: 300 segundos (DTMF)
Máximo: 20 segundos (opciones)
Máximo: 20 segundos (voz)		 El tiempo de espera de silencio inicial ajusta la cantidad de audio que no es de voz permitida antes de una frase antes de que el intento de reconocimiento termine en un resultado "sin coincidencia". Puede obtener más información aquí. Opcionales
MaxTonesToCollect Entero Sin valor predeterminado

Min: 1		 Número de dígitos que un desarrollador espera como entrada del participante. Obligatorio
StopTones IEnumeration<DtmfTone> Sin establecer Los participantes de dígitos pueden presionar para escapar de un evento DTMF por lotes. Opcionales
InterruptPrompt Booleano True Si el participante tiene la capacidad de interrumpir el playMessage presionando un dígito. Opcionales
InterruptCallMediaOperation Booleano True Si se establece esta marca, se interrumpe la operación multimedia de llamada actual. Por ejemplo, si se reproduce algún audio, se interrumpe esa operación y se inicia el reconocimiento. Opcionales
OperationContext Cadena Sin establecer Cadena que los desarrolladores pueden pasar la acción intermedia, útil para permitir que los desarrolladores almacenen contexto sobre los eventos que reciben. Opcionales
Frases Cadena Sin establecer Lista de frases que se asocian a la etiqueta, si alguna de estas se escucha, se considera un reconocimiento correcto. Obligatorio
Tono Cadena Sin establecer Tono que se debe reconocer si el usuario decide presionar un número en lugar de usar la voz. Opcionales
Etiqueta Cadena Sin establecer Valor clave para el reconocimiento. Obligatorio
Lenguaje Cadena En-us Idioma que se usa para el reconocimiento de la voz. Opcionales
EndSilenceTimeout TimeSpan 0.5 segundos La pausa final del hablante usada para detectar el resultado final que se genera como voz. Opcionales

Nota:

En situaciones en las que tanto dtmf como voz se encuentran en recognizeInputsType, la acción de reconocimiento actuará sobre el primer tipo de entrada recibido, es decir, si el usuario presiona un número de teclado primero, la acción de reconocimiento la considerará un evento dtmf y continuará escuchando los tonos dtmf. Si el usuario habla primero, la acción reconocerá que es un reconocimiento de voz y escuchará la entrada de voz.

Creación de una nueva aplicación de Python

Configuración de un entorno virtual de Python para el proyecto

python -m venv play-audio-app

Activación del entorno virtual

En Windows, usa el siguiente comando:

.\ play-audio-quickstart \Scripts\activate

En Unix, usa el comando siguiente:

source play-audio-quickstart /bin/activate

Instalación del paquete de Automatización de llamadas de Azure Communication Services

pip install azure-communication-callautomation

Crea el archivo de aplicación en el directorio del proyecto, por ejemplo, asígnale el nombre app.py. Escribe el código de Python en este archivo.

Ejecuta la aplicación mediante Python con el comando siguiente. Esto ejecuta el código de Python que has escrito.

python app.py

Establecimiento de una llamada

En este punto, debe estar familiarizado con el inicio de llamadas, si necesita obtener más información sobre cómo realizar una llamada, siga nuestro inicio rápido. En este inicio rápido, creamos una llamada saliente.

Llamada a la acción de reconocimiento

Cuando la aplicación responde a la llamada, puede proporcionar información sobre cómo reconocer la entrada del participante y reproducir un mensaje.

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

En el caso de los flujos de conversión de voz a texto, la acción de reconocimiento de automatización de llamadas también admite el uso de modelos de voz personalizados. Las características como los modelos de voz personalizados pueden ser útiles cuando se crea una aplicación que necesita escuchar palabras complejas que los modelos predeterminados de conversión de voz a texto pueden no ser capaces de entender, un buen ejemplo de esto puede ser cuando se crea una aplicación para el sector telemédico y el agente virtual debe ser capaz de reconocer términos médicos. Puedes obtener más información sobre cómo crear e implementar modelos de voz personalizados aquí.

Opciones de conversión de voz en texto

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

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

Conversión de voz en texto o 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")

Nota:

Si no se establecen parámetros, los valores predeterminados se aplican siempre que sea posible.

Recepción de actualizaciones de eventos de reconocimiento

Los desarrolladores pueden suscribirse a los eventos RecognizeCompleted y RecognizeFailed en la devolución de llamada de webhook que registraron para la llamada para crear lógica de negocios en su aplicación para determinar los pasos siguientes cuando se produce uno de los eventos mencionados anteriormente.

Ejemplo de cómo se puede deserializar el evento 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);

Ejemplo de cómo se puede deserializar el evento RecognizeFailed:

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

Ejemplo de cómo se puede deserializar el evento RecognizeCanceled:

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

Códigos de evento

Estado Código SubCode Mensaje
RecognizeCompleted 200 8531 Acción completada, número máximo de dígitos recibidos.
RecognizeCompleted 200 8514 Acción completada a medida que se detectó el tono de detención.
RecognizeCompleted 400 8508 Error de acción, se canceló la operación.
RecognizeCompleted 400 8532 Error de acción: se alcanzó el tiempo de espera de silencio entre dígitos.
RecognizeCanceled 400 8508 Error de acción, se canceló la operación.
RecognizeFailed 400 8510 Ha habido un error, se ha alcanzado el tiempo de espera de silencio inicial.
RecognizeFailed 500 8511 Error de acción al intentar reproducir el símbolo del sistema.
RecognizeFailed 500 8512 Error interno desconocido del servidor.
RecognizeFailed 400 8510 Error de acción, se alcanzó el tiempo de espera de silencio inicial
RecognizeFailed 400 8532 Error de acción: se alcanzó el tiempo de espera de silencio entre dígitos.
RecognizeFailed 400 8565 Ha habido un error, solicitud incorrecta a los servicios de Azure AI. Compruebe los parámetros de entrada.
Error de reconocimiento 400 8565 Ha habido un error, solicitud incorrecta a los servicios de Azure AI. No se puede procesar la carga proporcionada, comprueba la entrada de origen de reproducción.
RecognizeFailed 401 8565 Ha habido un error, error de autenticación de los servicios de Azure AI.
RecognizeFailed 403 8565 Ha habido un error, solicitud prohibida a los servicios de Azure AI, la suscripción gratuita usada por la solicitud ha agotado la cuota.
RecognizeFailed 429 8565 Ha habido un error, las solicitudes superaron el número de solicitudes simultáneas permitidas para la suscripción de servicios de Azure AI.
RecognizeFailed 408 8565 Ha habido un error, se agota el tiempo de espera de la solicitud a los servicios de Azure AI.
RecognizeFailed 500 8511 Error de acción al intentar reproducir el símbolo del sistema.
RecognizeFailed 500 8512 Error interno desconocido del servidor.

Limitaciones conocidas

  • DTMF en banda no se admite, use RFC 2833 DTMF en su lugar.
  • Los mensajes de texto a voz admiten un máximo de 400 caracteres, si el mensaje es mayor que este se recomienda usar SSML para acciones de reproducción basadas en texto a voz.
  • En escenarios en los que se supera el límite de cuota del servicio de voz, puedes solicitar aumentar este limite siguiendo los pasos descritos aquí.

Limpieza de recursos

Si quiere limpiar y quitar una suscripción a Communication Services, puede eliminar el recurso o grupo de recursos. Al eliminar el grupo de recursos, también se elimina cualquier otro recurso que esté asociado a él. Obtenga más información sobre la limpieza de recursos.

Pasos siguientes