Управление действиями мультимедиа среднего вызова с помощью службы автоматизации вызовов

Статья
11/02/2024

Служба автоматизации вызовов использует интерфейс REST API для получения запросов на действия и предоставления ответов, чтобы сообщить, был ли запрос успешно отправлен или нет. Из-за асинхронного характера вызова большинство действий имеют соответствующие события, которые активируются при успешном завершении или сбое действия. В этом руководстве рассматриваются действия, доступные разработчикам во время звонков, таких как отправка DTMF и непрерывное распознавание DTMF. Действия сопровождаются примером кода по вызову указанного действия.

Служба автоматизации звонков поддерживает различные другие действия для управления вызовами и записью, которые не включены в это руководство.

Примечание.

Автоматизация вызовов в настоящее время не взаимодействует с Microsoft Teams. Такие действия, как выполнение, перенаправление вызова пользователю Teams или воспроизведение звука пользователю Teams с помощью службы автоматизации вызовов не поддерживается.

В качестве необходимых условий рекомендуется ознакомиться со следующими статьями, чтобы получить большую часть этого руководства:

Основные понятия службы автоматизации вызовов, описывающие модель программирования действий и обратные вызовы событий.
Сведения об идентификаторах пользователей, таких как CommunicationUserIdentifier и PhoneNumberIdentifier, используемых в этом руководстве.
Узнайте больше о том, как управлять вызовами и управлять ими с помощью службы автоматизации вызовов, которая учит вас работе с основами работы с вызовом.

Для всех примеров client кода используется объект CallAutomationClient, который можно создать, как показано, и callConnection является объектом CallConnection, полученным из ответа Answer или CreateCall. Вы также можете получить его из событий обратного вызова, полученных приложением.

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

Отправка DTMF

Вы можете отправлять тоны DTMF внешнему участнику, что может оказаться полезным, если вы уже находитесь на вызове и хотите пригласить другого участника, у которого есть номер расширения или меню IVR для перехода.

Примечание.

Это поддерживается только для внешних участников ТСОП и поддерживает отправку не более 18 тонов за раз.

Метод SendDtmfAsync

Отправьте список тонов DTMF внешнему участнику.

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)

Когда приложение отправляет эти тоны DTMF, вы получаете обновления событий. Вы можете использовать SendDtmfTonesCompleted события и SendDtmfTonesFailed события для создания бизнес-логики в приложении, чтобы определить следующие действия.

Пример события 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']);

Пример 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'])

Непрерывное распознавание DTMF

Вы можете подписаться на непрерывные тоны DTMF во время вызова. Приложение получает тон DTMF, так как целевой участник нажимает клавишу на клавиатуре. Эти тоны отправляются в приложение по одному, так как участник нажимает их.

Метод StartContinuousDtmfRecognitionAsync

Начните обнаруживать тоны DTMF, отправленные участником.

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

Если приложение больше не хочет получать от участника тон DTMF, вы можете использовать StopContinuousDtmfRecognitionAsync этот метод, чтобы сообщить Службы коммуникации Azure знать, чтобы остановить обнаружение тонов DTMF.

StopContinuousDtmfRecognitionAsync

Остановите обнаружение тонов DTMF, отправленных участником.

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

Приложение получает обновления событий при успешном выполнении или сбое этих действий. Эти события можно использовать для создания пользовательской бизнес-логики, чтобы настроить следующий шаг, который необходимо выполнить при получении этих обновлений событий.

Событие ContinuousDtmfRecognitionToneReceived

Пример успешного обнаружения тона DTMF.

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 предоставляет в SequenceId рамках ContinuousDtmfRecognitionToneReceived события, которое приложение может использовать для восстановления порядка, в котором участник вошел в тон DTMF.

Событие ContinuousDtmfRecognitionFailed

Пример того, как можно обрабатывать при сбое обнаружения тонов 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

Пример того, как обрабатывать при остановке непрерывного распознавания DTMF, это может быть связано с тем, что ваше приложение вызвало StopContinuousDtmfRecognitionAsync событие или завершилось вызов.

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

Удержание

Действие удержания позволяет разработчикам временно приостановить беседу между участником и системой или агентом. Это может быть полезно в сценариях, когда участнику необходимо передать другому агенту или отделу или когда агенту необходимо обратиться к руководителю в фоновом режиме, прежде чем продолжить беседу. В это время вы можете воспроизвести звук для участника, который находится на удержании.

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

Прекращение удержания

Действие отмены удержания позволяет разработчикам возобновить беседу между участником и системой или агентом, который ранее был приостановлен. Когда участник отключается, он сможет снова услышать систему или агент.

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

Потоковая передача звука (общедоступная предварительная версия)

Потоковая передача звука позволяет подписаться на потоки звука в режиме реального времени из текущего вызова. Дополнительные сведения о начале работы с потоковой передачей звука и сведениями о событиях обратного вызова потоковой передачи звука см . на этой странице.

Транскрибирование в режиме реального времени (общедоступная предварительная версия)

Транскрибирование в режиме реального времени позволяет получить доступ к динамическим транскрибированиям для звука текущего звонка. Дополнительные сведения о начале работы с транскрибированием в режиме реального времени и сведениями о событиях обратного вызова транскрибирования в режиме реального времени см . на этой странице.

Таблица совместимости действий мультимедиа

В следующей таблице показано, какие операции мультимедиа разрешены для запуска или очереди, если предыдущая операция по-прежнему выполняется или находится в очереди.

Существующая операция	Вызов ноги	Допустимо	Запрещено
PlayToAll	Главная	PlayToAll, Recognize(Non-Group Call), PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition	нет
Распознать (негрупповый вызов)	Главная	PlayToAll, Recognize(Non-Group Call), PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition	нет
Воспроизведение	Под	PlayToAll, Recognize(Non-Group Call)	PlayTo, Recognize(Групповой вызов), SendDTMF, StartContinuousDtmfRecognition
Распознать(групповой вызов)	Под	PlayToAll, Recognize(Non-Group Call)	PlayTo, Recognize(Групповой вызов), SendDTMF, StartContinuousDtmfRecognition
SendDTMF	Под	PlayToAll, Recognize(Non-Group Call)	PlayTo, Recognize(Групповой вызов), SendDTMF, StartContinuousDtmfRecognition
StartContinuousDtmfRecognition	Под	PlayToAll, Recognize(Non-Group Call),PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition	Нет

Поделиться через