Как управлять мультимедиа-действиями во время вызова с помощью автоматизации вызовов

2025-04-01

Служба автоматизации вызовов использует интерфейс 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 тоны.

Событие Ошибка Непрерывного Распознавания DTMF

Пример того, как можно обрабатывать ситуацию, когда обнаружение тонов 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"],
    )

Событие остановки непрерывного распознавания DTMF

Пример того, как действовать в случае остановки непрерывного распознавания 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 stopped: 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, Распознать(не групповой вызов), PlayTo, Распознать(групповой вызов), Отправить DTMF, Начать непрерывное распознавание DTMF	нет
Распознать (негрупповый вызов)	Главная	PlayToAll, Распознать(Не групповый вызов), PlayTo, Распознать(Групповой вызов), ОтправитьDTMF, НачатьНепрерывноеРаспознаваниеDtmf	нет
Воспроизведение	Под	Воспроизведение для всех, Распознать (не групповый звонок)	PlayTo, Recognize (Групповой вызов), Отправить DTMF, Начать непрерывное распознавание DTMF
Распознать (Групповой вызов)	Под	PlayToAll, Распознать (Не групповой вызов)	PlayTo, Recognize(Групповой вызов), Отправить DTMF, Начать непрерывное распознавание DTMF (StartContinuousDtmfRecognition)
SendDTMF	Под	PlayToAll, Распознать (Не групповый вызов)	PlayTo, Распознать(Групповой вызов), Отправить DTMF, Начать непрерывное распознавание DTMF
StartContinuousDtmfRecognition	Под	PlayToAll, Recognize(обычный вызов), PlayTo, Recognize(групповой вызов), SendDTMF, StartContinuousDtmfRecognition	нет