Procedimiento para controlar acciones multimedia de llamadas intermedias con Automatización de llamadas

La automatización de llamadas usa una interfaz de API REST para recibir solicitudes de acciones y proporcionar respuestas que notifiquen si la solicitud se ha enviado correctamente o no. Debido a la naturaleza asincrónica de las llamadas, la mayoría de las acciones tienen eventos correspondientes que se desencadenan cuando la acción se completa correctamente o se produce un error. En esta guía se describen las acciones disponibles para los desarrolladores durante las llamadas, como Enviar DTMF y Reconocimiento continuo de DTMF. Las acciones se acompañan con código de ejemplo sobre cómo invocar dicha acción.

Automatización de llamadas admite diversas acciones adicionales para administrar llamadas y grabar que no se incluyen en esta guía.

Nota:

Actualmente, Automatización de llamadas no interopera con Microsoft Teams. No se admiten acciones como realizar una llamada, redirigir una llamada a un usuario de Teams o reproducir audio para un usuario de Teams mediante Automatización de llamadas.

Como requisito previo, se recomienda leer los artículos siguientes a fin de sacar el máximo partido a esta guía:

1. Guía de conceptos de la automatización de llamadas que describe el modelo de programación de eventos de acción y las devoluciones de llamada de evento.
2. Obtenga información sobre los identificadores de usuario, como CommunicationUserIdentifier y PhoneNumberIdentifier, que se usan en esta guía.
3. Obtenga más información sobre cómo controlar y dirigir las llamadas con Automatización de llamadas, donde se muestra cómo trabajar con los conceptos básicos de tratar con una llamada.

Para todos los ejemplos de código, client es el objeto CallAutomationClient que se puede crear tal como se muestra y callConnection es el objeto CallConnection que se obtiene de la respuesta Answer o CreateCall. También se puede obtener de los eventos de devolución de llamada que recibe la aplicación.

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

Puede enviar tonos DTMF a un participante externo, lo que puede resultar útil cuando ya esté en una llamada y necesite invitar a otro participante que tenga un número de extensión o un menú IVR para navegar.

Nota:

Esto solo se admite para los participantes RTC externos y admite el envío de un máximo de 18 tonos a la vez.

SendDtmfAsync (método)

Envíe una lista de tonos DTMF a un 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)

Cuando la aplicación envía estos tonos DTMF, recibirá actualizaciones de eventos. Puede usar los eventos SendDtmfTonesCompleted y SendDtmfTonesFailed para crear lógica de negocios en la aplicación a fin de determinar los pasos siguientes.

Ejemplo del 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']);

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

Reconocimiento continuo de DTMF

Puede suscribirse para recibir tonos DTMF continuos a lo largo de la llamada. La aplicación recibe tonos DTMF a medida que el participante de destino presiona una tecla en su teclado. Estos tonos se envían a la aplicación uno por uno, a medida que el participante los presiona.

StartContinuousDtmfRecognitionAsync (método)

Comience a detectar los tonos DTMF enviados por un 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")

Cuando la aplicación ya no quiera recibir tonos DTMF del participante, puede usar el método StopContinuousDtmfRecognitionAsync para que Azure Communication Services sepa que debe dejar de detectar tonos DTMF.

StopContinuousDtmfRecognitionAsync

Deje de detectar los tonos DTMF enviados por un 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") 

La aplicación recibe actualizaciones de eventos cuando estas acciones se realizan correctamente o no. Puede usar estos eventos para crear lógica de negocios personalizada a fin de configurar el siguiente paso que debe llevar a cabo la aplicación cuando reciba estas actualizaciones de eventos.

ContinuousDtmfRecognitionToneReceived (evento)

Ejemplo de cómo puede controlar correctamente un tono DTMF detectado.

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

Azure Communication Services proporciona SequenceId como parte del evento ContinuousDtmfRecognitionToneReceived, que la aplicación puede usar para reconstruir el orden en el que el participante ha introducido los tonos DTMF.

ContinuousDtmfRecognitionFailed (evento)

Ejemplo de cómo se puede controlar cuando se produce un error en la detección de tonos DTMF.

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

ContinuousDtmfRecogntionStopped (evento)

Ejemplo de cómo controlar cuándo se ha detenido el reconocimiento continuo de DTMF, que podría deberse a que la aplicación ha invocado el evento StopContinuousDtmfRecognitionAsync o a que la llamada ha finalizado.

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

La acción de suspensión permite a los desarrolladores pausar temporalmente una conversación entre un participante y un sistema o agente. Esto puede ser útil en escenarios en los que el participante se debe transferir a otro agente o departamento, o bien cuando el agente necesita consultar a un supervisor en segundo plano antes de continuar con la conversación. Durante este tiempo, puede elegir reproducir un audio al participante que está en 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
)
'''

Anular retención

La acción de anulación de la suspensión permite a los desarrolladores reanudar una conversación entre un participante y un sistema o agente que previamente se haya puesto en pausa. Cuando el participante deje de estar en espera, podrá volver a escuchar al sistema o al agente.

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 audio (versión preliminar pública)

El streaming de audio le permite suscribirse a transmisiones de audio en tiempo real desde una llamada en curso. Para obtener instrucciones más detalladas sobre cómo empezar a trabajar con el streaming de audio e información sobre los eventos de devolución de llamada del streaming de audio, consulte esta página.

Transcripción en tiempo real (versión preliminar pública)

La transcripción en tiempo real le permite acceder a transcripciones en vivo para el audio de una llamada en curso. Para obtener instrucciones más detalladas sobre cómo empezar a trabajar con la transcripción en tiempo real e información sobre los eventos de devolución de llamada de la transcripción en tiempo real, consulte esta página.

Tabla de compatibilidad de acciones multimedia

En la tabla siguiente se muestra qué operaciones multimedia se pueden ejecutar o poner en cola si una operación anterior sigue en ejecución o en cola.

Operación existente	Llamada	Permitidas	No permitido
PlayToAll	Principal	PlayToAll, Recognize(Non-Group Call), PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition	Ninguno
Recognize(Llamada que no es de grupo)	Principal	PlayToAll, Recognize(Non-Group Call), PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition	Ninguno
Reproducir en	Sub	PlayToAll, Recognize(llamada que no es de grupo)	PlayTo, Recognize(llamada grupal), SendDTMF, StartContinuousDtmfRecognition
Recognize(Llamada de grupo)	Sub	PlayToAll, Recognize(llamada que no es de grupo)	PlayTo, Recognize(llamada grupal), SendDTMF, StartContinuousDtmfRecognition
SendDTMF	Sub	PlayToAll, Recognize(llamada que no es de grupo)	PlayTo, Recognize(llamada grupal), SendDTMF, StartContinuousDtmfRecognition
StartContinuousDtmfRecognition	Sub	PlayToAll, Recognize(llamada no grupal),PlayTo, Recognize(llamada grupal), SendDTMF, StartContinuousDtmfRecognition	Ninguno