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

2025-09-03

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

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

Note

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

Prerequisites

Ознакомьтесь со статьёй понятия автоматизации вызовов, которая описывает модель программирования с использованием событий и обратные вызовы событий.
Сведения об идентификаторах пользователей, таких как 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) сигналы внешнему участнику. Эта возможность может оказаться полезной, если вы уже на вызове и хотите пригласить другого участника, у которого есть номер расширения или использовать интерактивное меню голосового ответа.

Note

Эта функция поддерживается только для внешних участников в общедоступных телефонных сетях и поддерживает отправку не более 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 прекратить их обнаружение.

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

Событие ContinuousDtmfRecognitionStopped

Пример того, что делать при остановке непрерывного распознавания 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"])

Hold

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

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

Unhold

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

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

Потоковая передача звука

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

Транскрибирование в режиме реального времени

Используя транскрибирование в режиме реального времени, вы можете получить доступ к динамическим транскрибированиям для звука текущего звонка. Дополнительные сведения о начале работы с транскрибированием в режиме реального времени и сведениями о событиях обратного вызова транскрибирования в режиме реального времени см. в статье "Добавление транскрибирования в режиме реального времени" в приложение.

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

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

Существующая операция	Вызов ноги	Allowed	Disallowed
`PlayToAll`	Main	`PlayToAll` `Recognize(Non-Group Call)` `PlayTo` `Recognize(Group Call)` `SendDTMF` `StartContinuousDtmfRecognition`	`None`
`Recognize(Non-Group Call)`	Main	`PlayToAll` `Recognize(Non-Group Call)` `PlayTo` `Recognize(Group Call)` `SendDTMF` `StartContinuousDtmfRecognition`	`None`
`PlayTo`	Sub	`PlayToAll`, `Recognize(Non-Group Call)`	`PlayTo` `Recognize(Group Call)` `SendDTMF` `StartContinuousDtmfRecognition`
`Recognize(Group Call)`	Sub	`PlayToAll`, `Recognize(Non-Group Call)`	`PlayTo` `Recognize(Group Call)` `SendDTMF` `StartContinuousDtmfRecognition`
`SendDTMF`	Sub	`PlayToAll`, `Recognize(Non-Group Call)`	`PlayTo` `Recognize(Group Call)` `SendDTMF` `StartContinuousDtmfRecognition`
`StartContinuousDtmfRecognition`	Sub	`PlayToAll`, `Recognize(Non-Group Call)`,`PlayTo`, `Recognize(Group Call)`, `SendDTMF`,`StartContinuousDtmfRecognition`	`None`