Como controlar ações de mídia mid-call com o Call Automation

A Automação de Chamadas usa uma interface de API REST para receber solicitações de ações e fornecer respostas para notificar se a solicitação foi enviada com êxito ou não. Devido à natureza assíncrona da chamada, a maioria das ações tem eventos correspondentes que são acionados quando a ação é concluída com êxito ou 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 de um código de exemplo sobre como invocar a referida ação.

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

Nota

Atualmente, a automação de chamadas não interopera com o Microsoft Teams. Não há suporte para ações como fazer, redirecionar uma chamada para um usuário do Teams ou reproduzir áudio para um usuário do Teams usando o Call Automation.

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

1. Guia de conceitos de automação de chamadas que descreve o modelo de programação de eventos de ação e retornos de chamada de eventos.
2. Saiba mais sobre identificadores de usuário como CommunicationUserIdentifier e PhoneNumberIdentifier usados neste guia.
3. Saiba mais sobre como controlar e direcionar chamadas com a Automação de chamadas, que ensina como lidar com os conceitos básicos 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 de eventos de retorno de chamada recebidos pelo seu aplicativo.

Afiado

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á está em uma chamada e precisa convidar outro participante que tenha um número de ramal ou um menu IVR para navegar.

Nota

Isso só é suportado para participantes PSTN externos e suporta o envio de um máximo de 18 tons de cada vez.

Método SendDtmfAsync

Envie uma lista de tons DTMF para um participante externo.

Afiado

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 SendDtmfTonesCompleted eventos e SendDtmfTonesFailed para criar lógica de negócios em seu aplicativo para determinar as próximas etapas.

Exemplo de evento SendDtmfTonesCompleted

Afiado

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

Afiado

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 DTMF contínuo

Você pode se inscrever para receber tons DTMF contínuos durante toda a chamada. Seu aplicativo recebe tons DTMF quando o participante alvo pressiona uma tecla em seu teclado. Estes tons são enviados para a sua aplicação, um a um, à medida que o participante os pressiona.

Método StartContinuousDtmfRecognitionAsync

Comece a detetar tons DTMF enviados por um participante.

Afiado

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 seu aplicativo não deseja mais receber tons DTMF do participante, você pode usar o método para informar os StopContinuousDtmfRecognitionAsync Serviços de Comunicação do Azure para parar de detetar tons DTMF.

StopContinuousDtmfRecognitionAsync

Pare de detetar tons DTMF enviados pelo participante.

Afiado

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 detetado com êxito.

Afiado

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 um SequenceId como parte do ContinuousDtmfRecognitionToneReceived evento, 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 deteção de tom DTMF falha.

Afiado

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 parou, isso pode ser porque seu aplicativo invocou o StopContinuousDtmfRecognitionAsync evento ou porque a chamada terminou.

Afiado

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

Em Espera

A ação de retenção permite que os desenvolvedores interrompam 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 período, você pode optar por reproduzir o áudio para o participante que está em espera.

Afiado

// 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
)
'''

Unhold

A ação de não retenção permite que os desenvolvedores retomem uma conversa entre um participante e um sistema ou agente que foi pausado anteriormente. Quando o participante for retirado, poderá ouvir novamente o sistema ou agente.

Afiado

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 (pré-visualização pública)

O streaming de áudio permite-lhe subscrever fluxos de áudio em tempo real a partir de uma chamada em curso. Para obter orientações mais detalhadas sobre como começar a usar o streaming de áudio e informações sobre eventos de retorno de chamada de streaming de áudio, consulte esta página.

Transcrição em tempo real (pré-visualização 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 orientações 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ções 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/enfileirada.

Operação existente	Perna de chamada	Permitido	Não permitido
PlayToAll	Principal	PlayToAll, Recognize(Chamada sem grupo), PlayTo, Recognize(Chamada de grupo), SendDTMF, StartContinuousDtmfRecognition	Nenhuma
Reconhecer(Chamada sem grupo)	Principal	PlayToAll, Recognize(Chamada sem grupo), PlayTo, Recognize(Chamada de grupo), SendDTMF, StartContinuousDtmfRecognition	Nenhuma
Reproduzir em	Sub	PlayToAll, Reconhecer (chamada sem grupo)	PlayTo, Recognize(Chamada de Grupo), SendDTMF, StartContinuousDtmfRecognition
Reconhecer (Chamada em Grupo)	Sub	PlayToAll, Reconhecer (chamada sem grupo)	PlayTo, Recognize(Chamada de Grupo), SendDTMF, StartContinuousDtmfRecognition
SendDTMF	Sub	PlayToAll, Reconhecer (chamada sem grupo)	PlayTo, Recognize(Chamada de Grupo), SendDTMF, StartContinuousDtmfRecognition
StartContinuousDtmfRecognition	Sub	PlayToAll, Recognize(Non-Group Call),PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition	Nenhuma