Coletar a entrada do usuário com a ação Reconhecer

Pré-requisitos

• Conta do Azure com uma subscrição ativa, para obter detalhes, consulte Criar uma conta gratuitamente..
• Recurso dos Serviços de Comunicação do Azure. Consulte Criar um recurso dos Serviços de Comunicação do Azure. Observe a cadeia de conexão para este recurso.
• Crie um novo aplicativo de serviço Web usando o SDK de automação de chamadas.
• A biblioteca .NET mais recente para o seu sistema operativo.
• O pacote NuGet mais recente.

Para recursos de IA

• Crie e ligue as Foundry Tools ao seu recurso Azure Communication Services.
• Crie um subdomínio personalizado para seu recurso de serviços de IA do Azure.

Especificações técnicas

Os seguintes parâmetros estão disponíveis para personalizar a função Reconhecer:

Criar um novo aplicativo C#

Na janela do console do seu sistema operacional, use o dotnet comando para criar um novo aplicativo Web.

dotnet new web -n MyApplication

Instalar o pacote NuGet

Obtenha o pacote NuGet da Galeria NuGet | Azure.Communication.CallAutomation. Siga as instruções para instalar o pacote.

Estabeleça uma chamada

A esta altura, você deve estar familiarizado com o início de chamadas. Para obter mais informações sobre como fazer uma chamada, consulte Guia de início rápido: fazer e fazer chamada de saída. Você também pode usar o trecho de código fornecido aqui para entender como atender uma chamada.

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

Chamar a ação de reconhecimento

Quando seu aplicativo atende a chamada, você pode fornecer informações sobre como reconhecer a entrada do participante e reproduzir um prompt.

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

Para fluxos de fala para texto, a ação Reconhecer automação de chamadas também oferece suporte ao uso de modelos de fala personalizados. Recursos como modelos de fala personalizados podem ser úteis quando você está criando um aplicativo que precisa ouvir palavras complexas que os modelos padrão de fala para texto podem não entender. Um exemplo é quando você está criando um aplicativo para o setor de telemedicina e seu agente virtual precisa ser capaz de reconhecer termos médicos. Você pode saber mais em Criar um projeto de fala personalizado.

Opções de fala para 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",
    SpeechLanguages = new List<string> { "en-US", "hi-IN", "fr-FR" },
    //Only add the SpeechModelEndpointId if you have a custom speech model you would like to use
    SpeechModelEndpointId = "YourCustomSpeechModelEndpointId"
};
var recognizeResult = await callAutomationClient.GetCallConnection(callConnectionId)
  .GetCallMedia()
  .StartRecognizingAsync(recognizeOptions);

Conversão de Voz em Texto

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

Conversão de voz em texto ou DTMF

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

Identificação linguística em tempo real (Pré-visualização)

Com o adicional de identificação de idioma em tempo real, os desenvolvedores podem detetar automaticamente idiomas falados para permitir comunicações naturais semelhantes às humanas e eliminar a seleção manual de idiomas pelos usuários finais.

string textToPlay = "Hi, how can I help you today?";
var playSource = new TextSource(textToPlay, "en-US-ElizabethNeural");
var recognizeOptions = new CallMediaRecognizeSpeechOptions(targetParticipant: new PhoneNumberIdentifier(targetParticipant))
{
    Prompt = playSource,
    InterruptCallMediaOperation = false,
    InterruptPrompt = false,
    InitialSilenceTimeout = TimeSpan.FromSeconds(10),
    OperationContext = "OpenQuestionSpeech",
    // Enable Language Identification
    SpeechLanguages = new List<string> { "en-US", "hi-IN", "fr-FR" },
    // Only add the SpeechModelEndpointId if you have a custom speech model you would like to use
    SpeechModelEndpointId = "YourCustomSpeechModelEndpointId"
};
var recognizeResult = await callAutomationClient.GetCallConnection(callConnectionId)
    .GetCallMedia()
    .StartRecognizingAsync(recognizeOptions);

Análise de Sentimento (Pré-visualização)

A API Reconhecer suporta análise de sentimento ao usar entrada de fala. Acompanhe o tom emocional das conversas em tempo real para apoiar as interações com clientes e agentes e permita que os supervisores intervenham quando necessário. Também pode ser útil para roteamento, personalização ou análise.

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

Receber atualizações de eventos de reconhecimento

Os desenvolvedores podem se inscrever RecognizeCompleted e RecognizeFailed eventos no retorno de chamada do webhook registrado. Use este retorno de chamada com lógica de negócios em seu aplicativo para determinar as próximas etapas quando um dos eventos ocorrer.

Exemplo de como você pode desserializar o evento RecognizeCompleted :

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

    callConnectionId = recognizeCompleted.CallConnectionId;

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

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

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

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

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

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

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

        default:
            logger.LogInformation("Recognize completed successfully, recognizeResult={recognizeResult}", recognizeCompleted.RecognizeResult);
            break;
    }
}

Exemplo de como você pode desserializar o evento RecognizeFailed :

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

Exemplo de como você pode desserializar o 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);
        }

Pré-requisitos

• Conta do Azure com uma subscrição ativa, para obter detalhes, consulte Criar uma conta gratuitamente..
• Recurso dos Serviços de Comunicação do Azure. Consulte Criar um recurso dos Serviços de Comunicação do Azure
• Crie um novo aplicativo de serviço Web usando o SDK de automação de chamadas.
• Java Development Kit versão 8 ou superior.
• Apache Maven.

Para recursos de IA

• Crie e ligue as Foundry Tools ao seu recurso Azure Communication Services.
• Crie um subdomínio personalizado para seu recurso de serviços de IA do Azure.

Especificações técnicas

Os seguintes parâmetros estão disponíveis para personalizar a função Reconhecer:

Criar uma nova aplicação Java

No seu terminal ou janela de comando, navegue até o diretório onde você gostaria de criar sua aplicação Java. Execute o mvn comando para gerar o projeto Java a partir do modelo maven-archetype-quickstart.

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

O mvn comando cria um diretório com o mesmo nome do artifactId argumento. O src/main/java diretório contém o código-fonte do projeto. O src/test/java diretório contém a fonte de teste.

Observe que a generate etapa criou um diretório com o mesmo nome do artifactId. O src/main/java diretório contém código-fonte. O src/test/java diretório contém testes. O pom.xml arquivo é o Project Object Model (POM) do projeto.

Atualize o arquivo POM de seus aplicativos para usar Java 8 ou superior.

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

Adicionar referências de pacote

No arquivo POM, adicione a seguinte referência para o projeto:

azure-communication-callautomation

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

Estabeleça uma chamada

A esta altura, você deve estar familiarizado com o início de chamadas. Para obter mais informações sobre como fazer uma chamada, consulte Guia de início rápido: fazer e fazer chamada de saída. Você também pode usar o trecho de código fornecido aqui para entender como atender uma chamada.

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

Chamar a ação de reconhecimento

Quando seu aplicativo atende a chamada, você pode fornecer informações sobre como reconhecer a entrada do participante e reproduzir um prompt.

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

Para fluxos de fala para texto, a ação Reconhecer automação de chamadas também oferece suporte ao uso de modelos de fala personalizados. Recursos como modelos de fala personalizados podem ser úteis quando você está criando um aplicativo que precisa ouvir palavras complexas que os modelos padrão de fala para texto podem não entender. Um exemplo é quando você está criando um aplicativo para o setor de telemedicina e seu agente virtual precisa ser capaz de reconhecer termos médicos. Você pode saber mais em Criar um projeto de fala personalizado.

Opções de fala para 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)
  .setSpeechLanguages("en-US", "es-ES", "hi-IN")
  .setSentimentAnalysisEnabled(true)
  .setOperationContext("AppointmentReminderMenu")
  //Only add the SpeechRecognitionModelEndpointId if you have a custom speech model you would like to use
  .setSpeechRecognitionModelEndpointId("YourCustomSpeechModelEndpointID"); 
var recognizeResponse = callAutomationClient.getCallConnectionAsync(callConnectionId)
  .getCallMediaAsync()
  .startRecognizingWithResponse(recognizeOptions)
  .block();

Conversão de Voz em Texto

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

Conversão de voz em texto ou 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(); 

Identificação linguística em tempo real (Pré-visualização)

Com o adicional de identificação de idioma em tempo real, os desenvolvedores podem detetar automaticamente idiomas falados para permitir comunicações naturais semelhantes às humanas e eliminar a seleção manual de idiomas pelos usuários finais.

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

var recognizeOptions = new CallMediaRecognizeSpeechOptions(participant, Duration.ofSeconds(15))
    .setPlayPrompt(playSource)
    .setInterruptPrompt(false)
    .setInitialSilenceTimeout(Duration.ofSeconds(15))
    .setSentimentAnalysisEnabled(true)
    .setSpeechLanguages("en-US", "es-ES", "hi-IN")
    .setOperationContext("OpenQuestionSpeech")
    // Only add the SpeechRecognitionModelEndpointId if you have a custom speech model you would like to use
    .setSpeechRecognitionModelEndpointId("YourCustomSpeechModelEndpointID");

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

Análise de Sentimento (Pré-visualização)

A API Reconhecer suporta análise de sentimento ao usar entrada de fala. Acompanhe o tom emocional das conversas em tempo real para apoiar as interações com clientes e agentes e permita que os supervisores intervenham quando necessário. Também pode ser útil para roteamento, personalização ou análise.

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

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

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

Receber atualizações de eventos de reconhecimento

Os desenvolvedores podem se inscrever RecognizeCompleted e RecognizeFailed eventos no retorno de chamada do webhook registrado. Use este retorno de chamada com lógica de negócios em seu aplicativo para determinar as próximas etapas quando um dos eventos ocorrer.

Exemplo de como você pode desserializar o 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();
        String languageIdentified = collectChoiceResult.getLanguageIdentified();
        log.info("Recognition completed, labelDetected=" + labelDetected + ", phraseDetected=" + phraseDetected + ", context=" + event.getOperationContext());
        log.info("Language Identified: " + languageIdentified);
        if (choiceResult.getSentimentAnalysisResult() != null) {
            log.info("Sentiment: " + choiceResult.getSentimentAnalysisResult().getSentiment());
        }
    } else if (recognizeResult instanceof SpeechResult) { 
        SpeechResult speechResult = (SpeechResult) recognizeResult; 
        String text = speechResult.getSpeech();
        String languageIdentified = speechResult.getLanguageIdentified();
        log.info("Recognition completed, text=" + text + ", context=" + event.getOperationContext());
        log.info("Language Identified: " + languageIdentified);
        if (speechResult.getSentimentAnalysisResult() != null) {
            log.info("Sentiment: " + speechResult.getSentimentAnalysisResult().getSentiment());
        }
    } else { 
        log.info("Recognition completed, result=" + recognizeResult + ", context=" + event.getOperationContext()); 
    } 
} 

Exemplo de como você pode desserializar o 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()); 
    } 
} 

Exemplo de como você pode desserializar o evento RecognizeCanceled :

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

Pré-requisitos

• Conta do Azure com uma subscrição ativa, para obter detalhes, consulte Criar uma conta gratuitamente.
• Recurso dos Serviços de Comunicação do Azure. Consulte Criar um recurso dos Serviços de Comunicação do Azure. Observe a cadeia de conexão para este recurso.
• Crie um novo aplicativo de serviço Web usando o SDK de automação de chamadas.
• Tem Node.js instalado, você pode instalá-lo a partir de seu site oficial.

Para recursos de IA

• Crie e ligue as Foundry Tools ao seu recurso Azure Communication Services.
• Crie um subdomínio personalizado para seu recurso de serviços de IA do Azure.

Especificações técnicas

Os seguintes parâmetros estão disponíveis para personalizar a função Reconhecer:

Criar um novo aplicativo JavaScript

Crie um novo aplicativo JavaScript no diretório do projeto. Inicialize um novo projeto Node.js com o seguinte comando. Isso cria um arquivo de package.json para seu projeto, que gerencia as dependências do projeto.

npm init -y

Instalar o pacote de Automação de Chamadas dos Serviços de Comunicação do Azure

npm install @azure/communication-call-automation

Crie um novo arquivo JavaScript no diretório do seu projeto, por exemplo, nomeie-o app.js. Escreva seu código JavaScript neste arquivo.

Execute seu aplicativo usando o Node.js com o seguinte comando.

node app.js

Estabeleça uma chamada

A esta altura, você deve estar familiarizado com o início de chamadas. Para obter mais informações sobre como fazer uma chamada, consulte Guia de início rápido: fazer e fazer chamada de saída.

Chamar a ação de reconhecimento

Quando seu aplicativo atende a chamada, você pode fornecer informações sobre como reconhecer a entrada do participante e reproduzir um prompt.

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

Para fluxos de fala para texto, a ação Reconhecer automação de chamadas também oferece suporte ao uso de modelos de fala personalizados. Recursos como modelos de fala personalizados podem ser úteis quando você está criando um aplicativo que precisa ouvir palavras complexas que os modelos padrão de fala para texto podem não entender. Um exemplo é quando você está criando um aplicativo para o setor de telemedicina e seu agente virtual precisa ser capaz de reconhecer termos médicos. Você pode saber mais em Criar um projeto de fala personalizado.

Opções de fala para 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); 

Conversão de Voz em Texto

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

Conversão de voz em texto ou 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); 

Identificação linguística em tempo real (Pré-visualização)

Com o adicional de identificação de idioma em tempo real, os desenvolvedores podem detetar automaticamente idiomas falados para permitir comunicações naturais semelhantes às humanas e eliminar a seleção manual de idiomas pelos usuários finais.

const textToPlay = "Hi, how can I help you today?";
const playSource: TextSource = {
  text: textToPlay,
  voiceName: "en-US-ElizabethNeural",
  kind: "textSource"
};
const recognizeOptions: CallMediaRecognizeSpeechOptions = {
  endSilenceTimeoutInSeconds: 30,
  playPrompt: playSource,
  operationContext: "speechContext",
  kind: "callMediaRecognizeSpeechOptions",
  // Enable Language Identification
  speechLanguages: ["en-US", "hi-IN", "fr-FR"],
  // Only add the speechRecognitionModelEndpointId if you have a custom speech model you would like to use
  speechRecognitionModelEndpointId: "YourCustomSpeechEndpointId"
};
await callAutomationClient.getCallConnection(callConnectionId)
  .getCallMedia()
  .startRecognizing(targetParticipant, recognizeOptions);

Análise de Sentimento (Pré-visualização)

A API Reconhecer suporta análise de sentimento ao usar entrada de fala. Acompanhe o tom emocional das conversas em tempo real para apoiar as interações com clientes e agentes e permita que os supervisores intervenham quando necessário. Também pode ser útil para roteamento, personalização ou análise.

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

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

  // Enable Sentiment Analysis
  enableSentimentAnalysis: true
};

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

Receber atualizações de eventos de reconhecimento

Os desenvolvedores podem se inscrever RecognizeCompleted e RecognizeFailed eventos no retorno de chamada do webhook registrado. Use este retorno de chamada com lógica de negócios em seu aplicativo para determinar as próximas etapas quando um dos eventos ocorrer.

Exemplo de como você pode desserializar o evento RecognizeCompleted :

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

  const callConnectionId = eventData.callConnectionId;

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

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

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

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

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

Exemplo de como você pode desserializar o evento RecognizeFailed :

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

Exemplo de como você pode desserializar o evento RecognizeCanceled :

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

Pré-requisitos

• Conta do Azure com uma subscrição ativa, para obter detalhes, consulte Criar uma conta gratuitamente.
• Recurso dos Serviços de Comunicação do Azure. Consulte Criar um recurso dos Serviços de Comunicação do Azure. Observe a cadeia de conexão para este recurso.
• Crie um novo aplicativo de serviço Web usando o SDK de automação de chamadas.
• Instale o Python a partir do Python.org.

Para recursos de IA

• Crie e ligue as Foundry Tools ao seu recurso Azure Communication Services.
• Crie um subdomínio personalizado para seu recurso de serviços de IA do Azure.

Especificações técnicas

Os seguintes parâmetros estão disponíveis para personalizar a função Reconhecer:

Criar uma aplicação Python nova

Configurar um ambiente virtual Python para o seu projeto

python -m venv play-audio-app

Ativar o ambiente virtual

No Windows, use o seguinte comando:

.\ play-audio-quickstart \Scripts\activate

No Unix, use o seguinte comando:

source play-audio-quickstart /bin/activate

Instalar o pacote de Automação de Chamadas dos Serviços de Comunicação do Azure

pip install azure-communication-callautomation

Crie seu arquivo de aplicativo no diretório do projeto, por exemplo, nomeie-o app.py. Escreva seu código Python neste arquivo.

Execute seu aplicativo usando Python com o seguinte comando.

python app.py

Estabeleça uma chamada

A esta altura, você deve estar familiarizado com o início de chamadas. Para obter mais informações sobre como fazer uma chamada, consulte Guia de início rápido: fazer e fazer chamada de saída.

Chamar a ação de reconhecimento

Quando seu aplicativo atende a chamada, você pode fornecer informações sobre como reconhecer a entrada do participante e reproduzir um prompt.

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

Para fluxos de fala para texto, a ação Reconhecer automação de chamadas também oferece suporte ao uso de modelos de fala personalizados. Recursos como modelos de fala personalizados podem ser úteis quando você está criando um aplicativo que precisa ouvir palavras complexas que os modelos padrão de fala para texto podem não entender. Um exemplo é quando você está criando um aplicativo para o setor de telemedicina e seu agente virtual precisa ser capaz de reconhecer termos médicos. Você pode saber mais em Criar um projeto de fala personalizado.

Opções de fala para 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")  

Conversão de Voz em Texto

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

Conversão de voz em texto ou 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") 

Identificação linguística em tempo real (Pré-visualização)

Com o adicional de identificação de idioma em tempo real, os desenvolvedores podem detetar automaticamente idiomas falados para permitir comunicações naturais semelhantes às humanas e eliminar a seleção manual de idiomas pelos usuários finais.

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

connection_client = call_automation_client.get_call_connection(call_connection_id)

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

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

    # Only add the speech_recognition_model_endpoint_id if you have a custom speech model you would like to use
    speech_recognition_model_endpoint_id="YourCustomSpeechModelEndpointId"
)

Análise de Sentimento (Pré-visualização)

A API Reconhecer suporta análise de sentimento ao usar entrada de fala. Acompanhe o tom emocional das conversas em tempo real para apoiar as interações com clientes e agentes e permita que os supervisores intervenham quando necessário. Também pode ser útil para roteamento, personalização ou análise.

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

connection_client = call_automation_client.get_call_connection(call_connection_id)

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

    # Only add the speech_recognition_model_endpoint_id if you have a custom speech model you would like to use
    speech_recognition_model_endpoint_id="YourCustomSpeechModelEndpointId"
)

Receber atualizações de eventos de reconhecimento

Os desenvolvedores podem se inscrever RecognizeCompleted e RecognizeFailed eventos no retorno de chamada do webhook registrado. Use este retorno de chamada com lógica de negócios em seu aplicativo para determinar as próximas etapas quando um dos eventos ocorrer.

Exemplo de como você pode desserializar o evento RecognizeCompleted :

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

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

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

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

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

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

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

    else:
        print(f"Recognition completed: data={event.data}")

Exemplo de como você pode desserializar o evento RecognizeFailed :

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

Exemplo de como você pode desserializar o evento RecognizeCanceled :

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