Formação
Módulo
Criar um aplicativo Web de chamada de voz com os Serviços de Comunicação do Azure - Training
Neste módulo, você cria um aplicativo Web básico que pode ser usado para chamadas de voz com os Serviços de Comunicação do Azure.
Este browser já não é suportado.
Atualize para o Microsoft Edge para tirar partido das mais recentes funcionalidades, atualizações de segurança e de suporte técnico.
Este guia ajuda você a começar a reconhecer a entrada DTMF fornecida pelos participantes por meio do SDK de Automação de Chamadas dos Serviços de Comunicação do Azure.
Os seguintes parâmetros estão disponíveis para personalizar a função Reconhecer:
Parâmetro | Type | Padrão (se não especificado) | Description | Obrigatório ou Opcional |
---|---|---|---|---|
Prompt (Para mais informações, ver Personalizar prompts de voz para usuários com a ação Reproduzir) |
FileSource, TextSource | Não definido | A mensagem a ser reproduzida antes de reconhecer a entrada. | Opcional |
InterToneTimeout |
TimeSpan | 2 segundos Mínimo: 1 segundo Máx: 60 segundos |
Limite em segundos que os Serviços de Comunicação do Azure aguardam que o chamador pressione outro dígito (tempo limite entre dígitos). | Opcional |
InitialSegmentationSilenceTimeoutInSeconds |
Número inteiro | 0,5 segundo | Quanto tempo a ação de reconhecimento aguarda a entrada antes de considerá-la um tempo limite. Consulte Como reconhecer a fala. | Opcional |
RecognizeInputsType |
Enumeração | DTMF | Tipo de entrada que é reconhecida. As opções são dtmf , choices , speech , e speechordtmf . |
Necessário |
InitialSilenceTimeout |
TimeSpan | 5 segundos Mínimo: 0 segundos Máx: 300 segundos (DTMF) Máx: 20 segundos (Opções) Máx: 20 segundos (Fala) |
O tempo limite de silêncio inicial ajusta a quantidade de áudio não falado permitida antes de uma frase antes que a tentativa de reconhecimento termine em um resultado "sem correspondência". Consulte Como reconhecer a fala. | Opcional |
MaxTonesToCollect |
Número inteiro | Sem padrão MÍN: 1 |
Número de dígitos que um desenvolvedor espera como entrada do participante. | Necessário |
StopTones |
IEnumeração<DtmfTone> | Não definido | Os participantes do dígito podem pressionar para escapar de um evento DTMF em lote. | Opcional |
InterruptPrompt |
Bool | True | Se o participante tiver a capacidade de interromper o playMessage pressionando um dígito. | Opcional |
InterruptCallMediaOperation |
Bool | True | Se esse sinalizador estiver definido, ele interromperá a operação de mídia de chamada atual. Por exemplo, se algum áudio estiver sendo reproduzido, ele interrompe essa operação e inicia o reconhecimento. | Opcional |
OperationContext |
String | Não definido | String que os desenvolvedores podem passar ação intermediária, útil para permitir que os desenvolvedores armazenem contexto sobre os eventos que recebem. | Opcional |
Phrases |
String | Não definido | Lista de frases que se associam ao rótulo. Ouvir qualquer uma dessas frases resulta em um reconhecimento bem-sucedido. | Necessário |
Tone |
String | Não definido | O tom a ser reconhecido se o usuário decidir pressionar um número em vez de usar a fala. | Opcional |
Label |
String | Não definido | O valor-chave para o reconhecimento. | Necessário |
Language |
String | En-nos | A linguagem usada para reconhecer a fala. | Opcional |
EndSilenceTimeout |
TimeSpan | 0,5 segundo | A pausa final do orador usada para detetar o resultado final que é gerado como fala. | Opcional |
Nota
Em situações em que DTMF recognizeInputsType
e fala estão no , a ação reconhecer atua no primeiro tipo de entrada recebido. Por exemplo, se o usuário pressionar um número de teclado primeiro, a ação reconhecer considera-o um evento DTMF e continua ouvindo os tons DTMF. Se o usuário fala primeiro, a ação de reconhecimento considera um evento de reconhecimento de fala e ouve a entrada de voz.
Na janela do console do seu sistema operacional, use o dotnet
comando para criar um novo aplicativo Web.
dotnet new web -n MyApplication
Obtenha o pacote NuGet da Galeria NuGet | Azure.Communication.CallAutomation. Siga as instruções para instalar o pacote.
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);
Quando seu aplicativo atende a chamada, você pode fornecer informações sobre como reconhecer a entrada do participante e reproduzir um prompt.
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.
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);
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);
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
Se os parâmetros não forem definidos, os padrões serão aplicados sempre que possível.
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.
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;
}
}
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);
}
}
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);
}
Os seguintes parâmetros estão disponíveis para personalizar a função Reconhecer:
Parâmetro | Type | Padrão (se não especificado) | Description | Obrigatório ou Opcional |
---|---|---|---|---|
Prompt (Para mais informações, ver Personalizar prompts de voz para usuários com a ação Reproduzir) |
FileSource, TextSource | Não definido | A mensagem a ser reproduzida antes de reconhecer a entrada. | Opcional |
InterToneTimeout |
TimeSpan | 2 segundos Mínimo: 1 segundo Máx: 60 segundos |
Limite em segundos que os Serviços de Comunicação do Azure aguardam que o chamador pressione outro dígito (tempo limite entre dígitos). | Opcional |
InitialSegmentationSilenceTimeoutInSeconds |
Número inteiro | 0,5 segundo | Quanto tempo a ação de reconhecimento aguarda a entrada antes de considerá-la um tempo limite. Consulte Como reconhecer a fala. | Opcional |
RecognizeInputsType |
Enumeração | DTMF | Tipo de entrada que é reconhecida. As opções são dtmf , choices , speech , e speechordtmf . |
Necessário |
InitialSilenceTimeout |
TimeSpan | 5 segundos Mínimo: 0 segundos Máx: 300 segundos (DTMF) Máx: 20 segundos (Opções) Máx: 20 segundos (Fala) |
O tempo limite de silêncio inicial ajusta a quantidade de áudio não falado permitida antes de uma frase antes que a tentativa de reconhecimento termine em um resultado "sem correspondência". Consulte Como reconhecer a fala. | Opcional |
MaxTonesToCollect |
Número inteiro | Sem padrão MÍN: 1 |
Número de dígitos que um desenvolvedor espera como entrada do participante. | Necessário |
StopTones |
IEnumeração<DtmfTone> | Não definido | Os participantes do dígito podem pressionar para escapar de um evento DTMF em lote. | Opcional |
InterruptPrompt |
Bool | True | Se o participante tiver a capacidade de interromper o playMessage pressionando um dígito. | Opcional |
InterruptCallMediaOperation |
Bool | True | Se esse sinalizador estiver definido, ele interromperá a operação de mídia de chamada atual. Por exemplo, se algum áudio estiver sendo reproduzido, ele interrompe essa operação e inicia o reconhecimento. | Opcional |
OperationContext |
String | Não definido | String que os desenvolvedores podem passar ação intermediária, útil para permitir que os desenvolvedores armazenem contexto sobre os eventos que recebem. | Opcional |
Phrases |
String | Não definido | Lista de frases que se associam ao rótulo. Ouvir qualquer uma dessas frases resulta em um reconhecimento bem-sucedido. | Necessário |
Tone |
String | Não definido | O tom a ser reconhecido se o usuário decidir pressionar um número em vez de usar a fala. | Opcional |
Label |
String | Não definido | O valor-chave para o reconhecimento. | Necessário |
Language |
String | En-nos | A linguagem usada para reconhecer a fala. | Opcional |
EndSilenceTimeout |
TimeSpan | 0,5 segundo | A pausa final do orador usada para detetar o resultado final que é gerado como fala. | Opcional |
Nota
Em situações em que DTMF recognizeInputsType
e fala estão no , a ação reconhecer atua no primeiro tipo de entrada recebido. Por exemplo, se o usuário pressionar um número de teclado primeiro, a ação reconhecer considera-o um evento DTMF e continua ouvindo os tons DTMF. Se o usuário fala primeiro, a ação de reconhecimento considera um evento de reconhecimento de fala e ouve a entrada de voz.
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>
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>
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();
Quando seu aplicativo atende a chamada, você pode fornecer informações sobre como reconhecer a entrada do participante e reproduzir um prompt.
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.
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();
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();
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
Se os parâmetros não forem definidos, os padrões serão aplicados sempre que possível.
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.
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());
}
}
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());
}
}
if (acsEvent instanceof RecognizeCanceled) {
RecognizeCanceled event = (RecognizeCanceled) acsEvent;
log.info("Recognition canceled, context=" + event.getOperationContext());
}
Os seguintes parâmetros estão disponíveis para personalizar a função Reconhecer:
Parâmetro | Type | Padrão (se não especificado) | Description | Obrigatório ou Opcional |
---|---|---|---|---|
Prompt (Para mais informações, ver Personalizar prompts de voz para usuários com a ação Reproduzir) |
FileSource, TextSource | Não definido | A mensagem a ser reproduzida antes de reconhecer a entrada. | Opcional |
InterToneTimeout |
TimeSpan | 2 segundos Mínimo: 1 segundo Máx: 60 segundos |
Limite em segundos que os Serviços de Comunicação do Azure aguardam que o chamador pressione outro dígito (tempo limite entre dígitos). | Opcional |
InitialSegmentationSilenceTimeoutInSeconds |
Número inteiro | 0,5 segundo | Quanto tempo a ação de reconhecimento aguarda a entrada antes de considerá-la um tempo limite. Consulte Como reconhecer a fala. | Opcional |
RecognizeInputsType |
Enumeração | DTMF | Tipo de entrada que é reconhecida. As opções são dtmf , choices , speech , e speechordtmf . |
Necessário |
InitialSilenceTimeout |
TimeSpan | 5 segundos Mínimo: 0 segundos Máx: 300 segundos (DTMF) Máx: 20 segundos (Opções) Máx: 20 segundos (Fala) |
O tempo limite de silêncio inicial ajusta a quantidade de áudio não falado permitida antes de uma frase antes que a tentativa de reconhecimento termine em um resultado "sem correspondência". Consulte Como reconhecer a fala. | Opcional |
MaxTonesToCollect |
Número inteiro | Sem padrão MÍN: 1 |
Número de dígitos que um desenvolvedor espera como entrada do participante. | Necessário |
StopTones |
IEnumeração<DtmfTone> | Não definido | Os participantes do dígito podem pressionar para escapar de um evento DTMF em lote. | Opcional |
InterruptPrompt |
Bool | True | Se o participante tiver a capacidade de interromper o playMessage pressionando um dígito. | Opcional |
InterruptCallMediaOperation |
Bool | True | Se esse sinalizador estiver definido, ele interromperá a operação de mídia de chamada atual. Por exemplo, se algum áudio estiver sendo reproduzido, ele interrompe essa operação e inicia o reconhecimento. | Opcional |
OperationContext |
String | Não definido | String que os desenvolvedores podem passar ação intermediária, útil para permitir que os desenvolvedores armazenem contexto sobre os eventos que recebem. | Opcional |
Phrases |
String | Não definido | Lista de frases que se associam ao rótulo. Ouvir qualquer uma dessas frases resulta em um reconhecimento bem-sucedido. | Necessário |
Tone |
String | Não definido | O tom a ser reconhecido se o usuário decidir pressionar um número em vez de usar a fala. | Opcional |
Label |
String | Não definido | O valor-chave para o reconhecimento. | Necessário |
Language |
String | En-nos | A linguagem usada para reconhecer a fala. | Opcional |
EndSilenceTimeout |
TimeSpan | 0,5 segundo | A pausa final do orador usada para detetar o resultado final que é gerado como fala. | Opcional |
Nota
Em situações em que DTMF recognizeInputsType
e fala estão no , a ação reconhecer atua no primeiro tipo de entrada recebido. Por exemplo, se o usuário pressionar um número de teclado primeiro, a ação reconhecer considera-o um evento DTMF e continua ouvindo os tons DTMF. Se o usuário fala primeiro, a ação de reconhecimento considera um evento de reconhecimento de fala e ouve a entrada de voz.
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
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
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.
Quando seu aplicativo atende a chamada, você pode fornecer informações sobre como reconhecer a entrada do participante e reproduzir um prompt.
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.
const choices = [
{
label: "Confirm",
phrases: [ "Confirm", "First", "One" ],
tone: DtmfTone.One
},
{
label: "Cancel",
phrases: [ "Cancel", "Second", "Two" ],
tone: DtmfTone.Two
}
];
const textToPlay = "Hello, This is a reminder for your appointment at 2 PM, Say Confirm to confirm your appointment or Cancel to cancel the appointment. Thank you!";
const playSource: TextSource = { text: textToPlay, voiceName: "en-US-ElizabethNeural", kind: "textSource" };
const recognizeOptions: CallMediaRecognizeChoiceOptions = {
choices: choices,
interruptPrompt: true,
initialSilenceTimeoutInSeconds: 30,
playPrompt: playSource,
operationContext: "AppointmentReminderMenu",
kind: "callMediaRecognizeChoiceOptions",
//Only add the speechRecognitionModelEndpointId if you have a custom speech model you would like to use
speechRecognitionModelEndpointId: "YourCustomSpeechEndpointId"
};
await callAutomationClient.getCallConnection(callConnectionId)
.getCallMedia()
.startRecognizing(targetParticipant, recognizeOptions);
const textToPlay = "Hi, how can I help you today?";
const playSource: TextSource = { text: textToPlay, voiceName: "en-US-ElizabethNeural", kind: "textSource" };
const recognizeOptions: CallMediaRecognizeSpeechOptions = {
endSilenceTimeoutInSeconds: 1,
playPrompt: playSource,
operationContext: "OpenQuestionSpeech",
kind: "callMediaRecognizeSpeechOptions",
//Only add the speechRecognitionModelEndpointId if you have a custom speech model you would like to use
speechRecognitionModelEndpointId: "YourCustomSpeechEndpointId"
};
await callAutomationClient.getCallConnection(callConnectionId)
.getCallMedia()
.startRecognizing(targetParticipant, recognizeOptions);
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
Se os parâmetros não forem definidos, os padrões serão aplicados sempre que possível.
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.
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));
}
}
if (event.type === "Microsoft.Communication.RecognizeFailed") {
console.log("Recognize failed: data=%s", JSON.stringify(eventData, null, 2));
}
if (event.type === "Microsoft.Communication.RecognizeCanceled") {
console.log("Recognize canceled, context=%s", eventData.operationContext);
}
Os seguintes parâmetros estão disponíveis para personalizar a função Reconhecer:
Parâmetro | Type | Padrão (se não especificado) | Description | Obrigatório ou Opcional |
---|---|---|---|---|
Prompt (Para mais informações, ver Personalizar prompts de voz para usuários com a ação Reproduzir) |
FileSource, TextSource | Não definido | A mensagem a ser reproduzida antes de reconhecer a entrada. | Opcional |
InterToneTimeout |
TimeSpan | 2 segundos Mínimo: 1 segundo Máx: 60 segundos |
Limite em segundos que os Serviços de Comunicação do Azure aguardam que o chamador pressione outro dígito (tempo limite entre dígitos). | Opcional |
InitialSegmentationSilenceTimeoutInSeconds |
Número inteiro | 0,5 segundo | Quanto tempo a ação de reconhecimento aguarda a entrada antes de considerá-la um tempo limite. Consulte Como reconhecer a fala. | Opcional |
RecognizeInputsType |
Enumeração | DTMF | Tipo de entrada que é reconhecida. As opções são dtmf , choices , speech , e speechordtmf . |
Necessário |
InitialSilenceTimeout |
TimeSpan | 5 segundos Mínimo: 0 segundos Máx: 300 segundos (DTMF) Máx: 20 segundos (Opções) Máx: 20 segundos (Fala) |
O tempo limite de silêncio inicial ajusta a quantidade de áudio não falado permitida antes de uma frase antes que a tentativa de reconhecimento termine em um resultado "sem correspondência". Consulte Como reconhecer a fala. | Opcional |
MaxTonesToCollect |
Número inteiro | Sem padrão MÍN: 1 |
Número de dígitos que um desenvolvedor espera como entrada do participante. | Necessário |
StopTones |
IEnumeração<DtmfTone> | Não definido | Os participantes do dígito podem pressionar para escapar de um evento DTMF em lote. | Opcional |
InterruptPrompt |
Bool | True | Se o participante tiver a capacidade de interromper o playMessage pressionando um dígito. | Opcional |
InterruptCallMediaOperation |
Bool | True | Se esse sinalizador estiver definido, ele interromperá a operação de mídia de chamada atual. Por exemplo, se algum áudio estiver sendo reproduzido, ele interrompe essa operação e inicia o reconhecimento. | Opcional |
OperationContext |
String | Não definido | String que os desenvolvedores podem passar ação intermediária, útil para permitir que os desenvolvedores armazenem contexto sobre os eventos que recebem. | Opcional |
Phrases |
String | Não definido | Lista de frases que se associam ao rótulo. Ouvir qualquer uma dessas frases resulta em um reconhecimento bem-sucedido. | Necessário |
Tone |
String | Não definido | O tom a ser reconhecido se o usuário decidir pressionar um número em vez de usar a fala. | Opcional |
Label |
String | Não definido | O valor-chave para o reconhecimento. | Necessário |
Language |
String | En-nos | A linguagem usada para reconhecer a fala. | Opcional |
EndSilenceTimeout |
TimeSpan | 0,5 segundo | A pausa final do orador usada para detetar o resultado final que é gerado como fala. | Opcional |
Nota
Em situações em que DTMF recognizeInputsType
e fala estão no , a ação reconhecer atua no primeiro tipo de entrada recebido. Por exemplo, se o usuário pressionar um número de teclado primeiro, a ação reconhecer considera-o um evento DTMF e continua ouvindo os tons DTMF. Se o usuário fala primeiro, a ação de reconhecimento considera um evento de reconhecimento de fala e ouve a entrada de voz.
python -m venv play-audio-app
No Windows, use o seguinte comando:
.\ play-audio-quickstart \Scripts\activate
No Unix, use o seguinte comando:
source play-audio-quickstart /bin/activate
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
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.
Quando seu aplicativo atende a chamada, você pode fornecer informações sobre como reconhecer a entrada do participante e reproduzir um prompt.
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.
choices = [
RecognitionChoice(
label="Confirm",
phrases=[ "Confirm", "First", "One" ],
tone=DtmfTone.ONE
),
RecognitionChoice(
label="Cancel",
phrases=[ "Cancel", "Second", "Two" ],
tone=DtmfTone.TWO
)
]
text_to_play = "Hello, This is a reminder for your appointment at 2 PM, Say Confirm to confirm your appointment or Cancel to cancel the appointment. Thank you!"
play_source = TextSource(text=text_to_play, voice_name="en-US-ElizabethNeural")
call_automation_client.get_call_connection(call_connection_id).start_recognizing_media(
input_type=RecognizeInputType.CHOICES,
target_participant=target_participant,
choices=choices,
interrupt_prompt=True,
initial_silence_timeout=30,
play_prompt=play_source,
operation_context="AppointmentReminderMenu",
# Only add the speech_recognition_model_endpoint_id if you have a custom speech model you would like to use
speech_recognition_model_endpoint_id="YourCustomSpeechModelEndpointId")
text_to_play = "Hi, how can I help you today?"
play_source = TextSource(text=text_to_play, voice_name="en-US-ElizabethNeural")
call_automation_client.get_call_connection(call_connection_id).start_recognizing_media(
input_type=RecognizeInputType.SPEECH,
target_participant=target_participant,
end_silence_timeout=1,
play_prompt=play_source,
operation_context="OpenQuestionSpeech",
# Only add the speech_recognition_model_endpoint_id if you have a custom speech model you would like to use
speech_recognition_model_endpoint_id="YourCustomSpeechModelEndpointId")
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
Se os parâmetros não forem definidos, os padrões serão aplicados sempre que possível.
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.
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);
if event.type == "Microsoft.Communication.RecognizeFailed":
app.logger.info("Recognize failed: data=%s", event.data);
if event.type == "Microsoft.Communication.RecognizeCanceled":
# Handle the RecognizeCanceled event according to your application logic
Status | Código | Subcódigo | Mensagem |
---|---|---|---|
RecognizeCompleted |
200 | 8531 | Ação concluída, dígitos máximos recebidos. |
RecognizeCompleted |
200 | 8514 | Ação concluída quando o tom de parada foi detetado. |
RecognizeCompleted |
400 | 8508 | A ação falhou, a operação foi cancelada. |
RecognizeCompleted |
400 | 8532 | A ação falhou, o tempo limite de silêncio entre dígitos foi atingido. |
RecognizeCanceled |
400 | 8508 | A ação falhou, a operação foi cancelada. |
RecognizeFailed |
400 | 8510 | A ação falhou, o tempo limite de silêncio inicial foi atingido. |
RecognizeFailed |
500 | 8511 | A ação falhou, encontrou falha ao tentar reproduzir o prompt. |
RecognizeFailed |
500 | 8512 | Erro interno desconhecido do servidor. |
RecognizeFailed |
400 | 8510 | A ação falhou, o tempo limite de silêncio inicial foi atingido |
RecognizeFailed |
400 | 8532 | A ação falhou, o tempo limite de silêncio entre dígitos foi atingido. |
RecognizeFailed |
400 | 8565 | Falha na ação, solicitação incorreta para serviços de IA do Azure. Verifique os parâmetros de entrada. |
RecognizeFailed |
400 | 8565 | Falha na ação, solicitação incorreta para serviços de IA do Azure. Não é possível processar a carga útil fornecida, verifique a entrada da fonte de reprodução. |
RecognizeFailed |
401 | 8565 | Falha na ação, erro de autenticação dos serviços de IA do Azure. |
RecognizeFailed |
403 | 8565 | Falha na ação, solicitação proibida para serviços de IA do Azure, assinatura gratuita usada pela solicitação ficou sem cota. |
RecognizeFailed |
429 | 8565 | Falha na ação, as solicitações excederam o número de solicitações simultâneas permitidas para a assinatura de serviços do Azure AI. |
RecognizeFailed |
408 | 8565 | Falha na ação, a solicitação aos serviços de IA do Azure expirou. |
RecognizeFailed |
500 | 8511 | A ação falhou, encontrou falha ao tentar reproduzir o prompt. |
RecognizeFailed |
500 | 8512 | Erro interno desconhecido do servidor. |
Se quiser limpar e remover uma assinatura dos Serviços de Comunicação, você pode excluir o recurso ou grupo de recursos. A exclusão do grupo de recursos também exclui quaisquer outros recursos associados a ele. Saiba mais sobre a limpeza de recursos.
Formação
Módulo
Criar um aplicativo Web de chamada de voz com os Serviços de Comunicação do Azure - Training
Neste módulo, você cria um aplicativo Web básico que pode ser usado para chamadas de voz com os Serviços de Comunicação do Azure.
Documentação
Fornece um guia de instruções sobre como usar ações de mídia de chamada intermediária em uma chamada com o Call Automation.
Reproduzir áudio em chamada - An Azure Communication Services concept document
Informações conceituais sobre a reprodução de áudio em chamada usando a automação de chamadas.
Fornece um início rápido para reproduzir áudio para os participantes como parte de uma chamada.