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

Artículo
11/06/2024

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:

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.
Obtenga información sobre los identificadores de usuario, como CommunicationUserIdentifier y PhoneNumberIdentifier, que se usan en esta guía.
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.

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

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

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

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.

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

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

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

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

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

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

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

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

Ejemplo de SendDtmfTonesFailed

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

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

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

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.

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

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

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

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

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.

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

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

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

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

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

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.

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

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

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

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.

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

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

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

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.

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

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

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

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.

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

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

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

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

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

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

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

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

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

const unholdOptions = { 
    operationContext: "unholdUserContext" 
}; 

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

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

# 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

Compartir a través de