Como controlar ações de mídia com a Automação de Chamadas

A Automação de Chamadas usa uma interface da API REST para receber solicitações de ações e fornecer respostas para notificar se a solicitação foi enviada com êxito. Devido à natureza assíncrona da chamada, a maioria das ações tem eventos correspondentes que são disparados quando a ação é concluída com êxito ou quando falha. Este guia aborda as ações disponíveis para desenvolvedores durante chamadas, como Enviar DTMF e Reconhecimento DTMF Contínuo. As ações são acompanhadas com amostas de código sobre como invocar a ação.

A Automação de Chamadas dá suporte a várias outras ações para gerenciar as chamadas e a gravação que não estão incluídas neste guia.

Observação

Atualmente, a Automação de Chamadas não interopera com o Microsoft Teams. Ações como fazer, redirecionar uma chamada para um usuário do Teams ou tocando áudio para um usuário do Teams usando a Automação de Chamadas não têm suporte.

Como pré-requisito, recomendamos que você leia os artigos abaixo para aproveitar ao máximo este guia:

1. Guia de conceitos da Automação de Chamadas que descreve o modelo de programação de eventos de ação e os retornos de chamada de eventos.
2. Saiba mais sobre os identificadores de usuário, como CommunicationUserIdentifier e PhoneNumberIdentifier, usados neste guia.
3. Saiba mais sobre como controlar e orientar chamadas com a Automação de Chamadas, que ensina sobre como lidar com as noções básicas de lidar com uma chamada.

Para todos os exemplos de código, client é o objeto CallAutomationClient que pode ser criado conforme mostrado e callConnection é o objeto CallConnection obtido da resposta Answer ou CreateCall. Você também pode obtê-lo dos eventos de retorno de chamada recebidos pelo aplicativo.

csharp

var callAutomationClient = new CallAutomationClient("<Azure Communication Services connection string>");

Java

CallAutomationClient callAutomationClient = new CallAutomationClientBuilder() 
    .connectionString("<Azure Communication Services connection string>") 
    .buildClient();

JavaScript

callAutomationClient = new CallAutomationClient(("<Azure Communication Services connection string>"); 

Python

call_automation_client = CallAutomationClient.from_connection_string((("<Azure Communication Services connection string>") 

Enviar DTMF

Você pode enviar tons DTMF para um participante externo, o que pode ser útil quando você já estiver em uma chamada e precisar convidar outro participante que tenha um número de extensão ou um menu IVR para navegar.

Observação

Isso só tem suporte para participantes PSTN externos e dá suporte ao envio de no máximo 18 tons por vez.

Método SendDtmfAsync

Envie uma lista de tons DTMF para um participante externo.

csharp

var tones = new DtmfTone[] { DtmfTone.One, DtmfTone.Two, DtmfTone.Three, DtmfTone.Pound }; 
var sendDtmfTonesOptions = new SendDtmfTonesOptions(tones, new PhoneNumberIdentifier(calleePhonenumber))
{ 
	OperationContext = "dtmfs-to-ivr" 
}; 

var sendDtmfAsyncResult = await callAutomationClient.GetCallConnection(callConnectionId) 
	.GetCallMedia() 
        .SendDtmfTonesAsync(sendDtmfTonesOptions); 

Java

List<DtmfTone> tones = Arrays.asList(DtmfTone.ONE, DtmfTone.TWO, DtmfTone.THREE, DtmfTone.POUND); 
SendDtmfTonesOptions options = new SendDtmfTonesOptions(tones, new PhoneNumberIdentifier(c2Target)); 
options.setOperationContext("dtmfs-to-ivr"); 
callAutomationClient.getCallConnectionAsync(callConnectionId) 
	.getCallMediaAsync() 
	.sendDtmfTonesWithResponse(options) 
	.block(); 

JavaScript

const tones = [DtmfTone.One, DtmfTone.Two, DtmfTone.Three];
const sendDtmfTonesOptions: SendDtmfTonesOptions = {
	operationContext: "dtmfs-to-ivr"
};
const result: SendDtmfTonesResult = await callAutomationClient.getCallConnection(callConnectionId)
	.getCallMedia()
	.sendDtmfTones(tones, {
		phoneNumber: c2Target
	}, sendDtmfTonesOptions);
console.log("sendDtmfTones, result=%s", result);

Python

tones = [DtmfTone.ONE, DtmfTone.TWO, DtmfTone.THREE]
result = call_automation_client.get_call_connection(call_connection_id).send_dtmf_tones(
	tones = tones,
	target_participant = PhoneNumberIdentifier(c2_target),
	operation_context = "dtmfs-to-ivr")
app.logger.info("Send dtmf, result=%s", result)

Quando seu aplicativo envia esses tons DTMF, você recebe atualizações de eventos. Você pode usar os eventos SendDtmfTonesCompleted e SendDtmfTonesFailed para criar lógica de negócios em seu aplicativo para determinar as próximas etapas.

Exemplo de evento SendDtmfTonesCompleted

csharp

if (acsEvent is SendDtmfTonesCompleted sendDtmfCompleted) 
{ 
    logger.LogInformation("Send DTMF succeeded, context={context}", sendDtmfCompleted.OperationContext); 
} 

Java

if (acsEvent instanceof SendDtmfTonesCompleted) { 
    SendDtmfTonesCompleted event = (SendDtmfTonesCompleted) acsEvent; 
    log.info("Send dtmf succeeded: context=" + event.getOperationContext()); 
} 

JavaScript

if (event.type === "Microsoft.Communication.SendDtmfTonesCompleted") {
	console.log("Send dtmf succeeded: context=%s", eventData.operationContext);
}

Python

if event.type == "Microsoft.Communication.SendDtmfTonesCompleted":
	app.logger.info("Send dtmf succeeded: context=%s", event.data['operationContext']);

Exemplo de SendDtmfTonesFailed

csharp

if (acsEvent is SendDtmfTonesFailed sendDtmfFailed) 
{ 
    logger.LogInformation("Send dtmf failed: result={result}, context={context}", 
        sendDtmfFailed.ResultInformation?.Message, sendDtmfFailed.OperationContext); 
} 

Java

if (acsEvent instanceof SendDtmfTonesFailed) { 
    SendDtmfTonesFailed event = (SendDtmfTonesFailed) acsEvent; 
    log.info("Send dtmf failed: result=" + event.getResultInformation().getMessage() + ", context=" 
        + event.getOperationContext()); 
} 

JavaScript

if (event.type === "Microsoft.Communication.SendDtmfTonesFailed") {
	console.log("sendDtmfTones failed: result=%s, context=%s",
		eventData.resultInformation.message,
		eventData.operationContext);
}

Python

if event.type == "Microsoft.Communication.SendDtmfTonesFailed": 
    app.logger.info("Send dtmf failed: result=%s, context=%s", event.data['resultInformation']['message'], event.data['operationContext']) 

Reconhecimento de DTMF contínuo

Você pode assinar para receber tons DTMF contínuos durante toda a chamada. Seu aplicativo recebe tons DTMF à medida que o participante de destino pressiona uma tecla em seu teclado. Esses tons são enviados ao aplicativo um a um enquanto o participante os pressiona.

Método StartContinuousDtmfRecognitionAsync

Comece a detectar tons DTMF enviados por um participante.

csharp

await callAutomationClient.GetCallConnection(callConnectionId) 
    .GetCallMedia() 
    .StartContinuousDtmfRecognitionAsync(new PhoneNumberIdentifier(c2Target), "dtmf-reco-on-c2"); 

Java

ContinuousDtmfRecognitionOptions options = new ContinuousDtmfRecognitionOptions(new PhoneNumberIdentifier(c2Target)); 
options.setOperationContext("dtmf-reco-on-c2"); 
callAutomationClient.getCallConnectionAsync(callConnectionId) 
	.getCallMediaAsync() 
	.startContinuousDtmfRecognitionWithResponse(options) 
	.block(); 

JavaScript

const continuousDtmfRecognitionOptions: ContinuousDtmfRecognitionOptions = {
	operationContext: "dtmf-reco-on-c2"
};

await callAutomationclient.getCallConnection(callConnectionId)
	.getCallMedia()
	.startContinuousDtmfRecognition({
		phoneNumber: c2Target
	}, continuousDtmfRecognitionOptions);

Python

call_automation_client.get_call_connection(
    call_connection_id
).start_continuous_dtmf_recognition(
    target_participant=PhoneNumberIdentifier(c2_target),
    operation_context="dtmf-reco-on-c2",
)
app.logger.info("Started continuous DTMF recognition")

Quando o aplicativo não quiser mais receber tons DTMF do participante, você poderá usar o método StopContinuousDtmfRecognitionAsync para permitir que os Serviços de Comunicação do Azure saibam para parar de detectar tons DTMF.

StopContinuousDtmfRecognitionAsync

Comece a detectar tons DTMF enviados por participante.

csharp

var continuousDtmfRecognitionOptions = new ContinuousDtmfRecognitionOptions(new PhoneNumberIdentifier(callerPhonenumber)) 
{ 
    OperationContext = "dtmf-reco-on-c2" 
}; 

var startContinuousDtmfRecognitionAsyncResult = await callAutomationClient.GetCallConnection(callConnectionId) 
    .GetCallMedia() 
    .StartContinuousDtmfRecognitionAsync(continuousDtmfRecognitionOptions); 

Java

ContinuousDtmfRecognitionOptions options = new ContinuousDtmfRecognitionOptions(new PhoneNumberIdentifier(c2Target)); 
options.setOperationContext("dtmf-reco-on-c2"); 
callAutomationClient.getCallConnectionAsync(callConnectionId) 
	.getCallMediaAsync() 
	.stopContinuousDtmfRecognitionWithResponse(options) 
	.block(); 

JavaScript

const continuousDtmfRecognitionOptions: ContinuousDtmfRecognitionOptions = {
	operationContext: "dtmf-reco-on-c2"
};

await callAutomationclient.getCallConnection(callConnectionId)
	.getCallMedia()
	.stopContinuousDtmfRecognition({
		phoneNumber: c2Target
	}, continuousDtmfRecognitionOptions);

Python

call_automation_client.get_call_connection(call_connection_id).stop_continuous_dtmf_recognition( 
    target_participant=PhoneNumberIdentifier(c2_target), 
    operation_context="dtmf-reco-on-c2") 
app.logger.info("Stopped continuous DTMF recognition") 

Seu aplicativo recebe atualizações de eventos quando essas ações são bem-sucedidas ou falham. Você pode usar esses eventos para criar uma lógica de negócios personalizada para configurar a próxima etapa que seu aplicativo precisa executar quando receber essas atualizações de eventos.

Evento ContinuousDtmfRecognitionToneReceived

Exemplo de como você pode lidar com um tom DTMF detectado com êxito.

csharp

if (acsEvent is ContinuousDtmfRecognitionToneReceived continuousDtmfRecognitionToneReceived) 
{ 
	logger.LogInformation("Tone detected: sequenceId={sequenceId}, tone={tone}", 
	continuousDtmfRecognitionToneReceived.SequenceId, 
        continuousDtmfRecognitionToneReceived.Tone); 
} 

Java

 if (acsEvent instanceof ContinuousDtmfRecognitionToneReceived) { 
	ContinuousDtmfRecognitionToneReceived event = (ContinuousDtmfRecognitionToneReceived) acsEvent; 
	log.info("Tone detected: sequenceId=" + event.getSequenceId() 
		+ ", tone=" + event.getTone().convertToString() 
		+ ", context=" + event.getOperationContext()); 
} 

JavaScript

if (event.type === "Microsoft.Communication.ContinuousDtmfRecognitionToneReceived") { 
	console.log("Tone detected: sequenceId=%s, tone=%s, context=%s", 
        	eventData.sequenceId, 
        	eventData.tone, 
		eventData.operationContext); 
} 

Python

if event.type == "Microsoft.Communication.ContinuousDtmfRecognitionToneReceived":  
	app.logger.info("Tone detected: sequenceId=%s, tone=%s, context=%s",  
		event.data['sequenceId'],  
                event.data['tone'],  
		event.data['operationContext'])  

Os Serviços de Comunicação do Azure fornecem uma SequenceId como parte do evento ContinuousDtmfRecognitionToneReceived, que seu aplicativo pode usar para reconstruir a ordem na qual o participante inseriu os tons DTMF.

Evento ContinuousDtmfRecognitionFailed

Exemplo de como você pode lidar quando a detecção de tom DTMF falha.

csharp

if (acsEvent is ContinuousDtmfRecognitionToneFailed continuousDtmfRecognitionToneFailed) 
{ 
    logger.LogInformation("Start continuous DTMF recognition failed, result={result}, context={context}", 
        continuousDtmfRecognitionToneFailed.ResultInformation?.Message, 
        continuousDtmfRecognitionToneFailed.OperationContext); 
} 

Java

if (acsEvent instanceof ContinuousDtmfRecognitionToneFailed) { 
    ContinuousDtmfRecognitionToneFailed event = (ContinuousDtmfRecognitionToneFailed) acsEvent; 
    log.info("Tone failed: result="+ event.getResultInformation().getMessage() 
        + ", context=" + event.getOperationContext()); 
} 

JavaScript

if (event.type === "Microsoft.Communication.ContinuousDtmfRecognitionToneFailed") {
	console.log("Tone failed: result=%s, context=%s", eventData.resultInformation.message, eventData.operationContext);
}

Python

if event.type == "Microsoft.Communication.ContinuousDtmfRecognitionToneFailed":
    app.logger.info(
        "Tone failed: result=%s, context=%s",
        event.data["resultInformation"]["message"],
        event.data["operationContext"],
    )

Evento ContinuousDtmfRecogntionStopped

Exemplo de como lidar quando o reconhecimento DTMF contínuo foi interrompido, isso pode ser porque seu aplicativo invocou o evento StopContinuousDtmfRecognitionAsync ou porque a chamada terminou.

csharp

if (acsEvent is ContinuousDtmfRecognitionStopped continuousDtmfRecognitionStopped) 
{ 
    logger.LogInformation("Continuous DTMF recognition stopped, context={context}", continuousDtmfRecognitionStopped.OperationContext); 
} 

Java

if (acsEvent instanceof ContinuousDtmfRecognitionStopped) { 
    ContinuousDtmfRecognitionStopped event = (ContinuousDtmfRecognitionStopped) acsEvent; 
    log.info("Tone stopped, context=" + event.getOperationContext()); 
} 

JavaScript

if (event.type === "Microsoft.Communication.ContinuousDtmfRecognitionStopped") {
	console.log("Tone stopped: context=%s", eventData.operationContext);
}

Python

if event.type == "Microsoft.Communication.ContinuousDtmfRecognitionStopped":
    app.logger.info("Tone stoped: context=%s", event.data["operationContext"])

Hold

A ação de retenção permite que os desenvolvedores pausem temporariamente uma conversa entre um participante e um sistema ou agente. Isso pode ser útil em cenários em que o participante precisa ser transferido para outro agente ou departamento ou quando o agente precisa consultar um supervisor em segundo plano antes de continuar a conversa. Durante esse tempo, você pode optar por reproduzir áudio para o participante que está em espera.

csharp

// Option 1: Hold without additional options
await callAutomationClient.GetCallConnection(callConnectionId)
    .GetCallMedia().HoldAsync(c2Target);

/*
// Option 2: Hold with play source
PlaySource playSource = /* initialize playSource */;
await callAutomationClient.GetCallConnection(callConnectionId)
    .GetCallMedia().HoldAsync(c2Target, playSource);

// Option 3: Hold with options
var holdOptions = new HoldOptions(target) 
{ 
    OperationCallbackUri = new Uri(""),
    OperationContext = "holdcontext"
};
await callMedia.HoldAsync(holdOptions);
*/

java

// Option 1: Hold with options
PlaySource playSource = /* initialize playSource */;
HoldOptions holdOptions = new HoldOptions(target)
    .setOperationCallbackUrl(appConfig.getBasecallbackuri())
    .setPlaySource(playSource)
    .setOperationContext("holdPstnParticipant");

client.getCallConnection(callConnectionId).getCallMedia().holdWithResponse(holdOptions, Context.NONE);

/*
// Option 2: Hold without additional options
client.getCallConnection(callConnectionId).getCallMedia().hold(target);
*/

JavaScript

// Option 1: Hold with options
const options = {
    playSource: playSource,
    operationContext: "holdUserContext",
    operationCallbackUrl: "URL" // replace with actual callback URL
};
await callMedia.hold(targetuser, options);

/*
// Option 2: Hold without additional options
await callMedia.hold(targetuser);
*/

Python

# Option 1: Hold without additional options
call_connection_client.hold(target_participant=PhoneNumberIdentifier(TARGET_PHONE_NUMBER))

'''
# Option 2: Hold with options
call_connection_client.hold(
    target_participant=PhoneNumberIdentifier(TARGET_PHONE_NUMBER),
    play_source=play_source,
    operation_context="holdUserContext",
    operation_callback_url="URL" # replace with actual callback URL
)
'''

Desativar espera

A ação de retenção permite que os desenvolvedores resumem uma conversa entre um participante e um sistema ou agente que estava em pausa. Quando o participante for retirado da espera, ele poderá ouvir o sistema ou o agente novamente.

csharp

var unHoldOptions = new UnholdOptions(target) 
{ 
    OperationContext = "UnHoldPstnParticipant" 
}; 

// Option 1
var UnHoldParticipant = await callMedia.UnholdAsync(unHoldOptions);

/* 
// Option 2
var UnHoldParticipant = await callMedia.UnholdAsync(target);
*/

java

// Option 1
client.getCallConnection(callConnectionId).getCallMedia().unholdWithResponse(target, "unholdPstnParticipant", Context.NONE);

/* 
// Option 2
client.getCallConnection(callConnectionId).getCallMedia().unhold(target);
*/

JavaScript

const unholdOptions = { 
    operationContext: "unholdUserContext" 
}; 

// Option 1
await callMedia.unhold(target);

/* 
// Option 2
await callMedia.unhold(target, unholdOptions);
*/

Python

# Option 1
call_connection_client.unhold(target_participant=PhoneNumberIdentifier(TARGET_PHONE_NUMBER)) 

'''
# Option 2
call_connection_client.unhold(target_participant=PhoneNumberIdentifier(TARGET_PHONE_NUMBER), operation_context="holdUserContext") 
'''

Streaming de áudio (versão prévia pública)

O streaming de áudio permite que você assine fluxos de áudio em tempo real de uma chamada em andamento. Para obter diretrizes mais detalhadas sobre como começar a usar a transmissão de áudio e informações sobre eventos de retorno de chamada de transmissão de áudio, consulte está página.

Transcrição em tempo real (versão prévia pública)

A transcrição em tempo real permite que você acesse transcrições ao vivo para o áudio de uma chamada em andamento. Para obter diretrizes mais detalhadas sobre como começar a usar a transcrição em tempo real e informações sobre eventos de retorno de chamada de transcrição em tempo real, consulte esta página.

Tabela de compatibilidade de ação de mídia

A tabela a seguir ilustra quais operações de mídia podem ser executadas/enfileiradas se uma operação anterior ainda estiver em execução/na fila.

Operação existente	Etapa de chamada	Permitido	Não permitido
PlayToAll	Principal	PlayToAll, Recognize(Non-Group Call), PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition	Nenhum
Recognize(Chamada não agrupada)	Principal	PlayToAll, Recognize(Non-Group Call), PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition	Nenhum
Reproduzir	Sub	PlayToAll, Recognize(Non-Group Call)	PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition
Recognize(Group Call)	Sub	PlayToAll, Recognize(Non-Group Call)	PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition
SendDTMF	Sub	PlayToAll, Recognize(Non-Group Call)	PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition
StartContinuousDtmfRecognition	Sub	PlayToAll, Recognize(Non-Group Call),PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition	Nenhum