통화 자동화를 사용하여 통화 중 미디어 작업을 제어하는 방법

통화 자동화는 REST API 인터페이스를 사용하여 작업 요청을 받고 요청이 성공적으로 제출되었는지 여부를 알리는 응답을 제공합니다. 통화의 비동기 특성으로 인해 대부분의 작업에는 작업이 성공적으로 완료되거나 실패할 때 트리거되는 해당 이벤트가 있습니다. 이 가이드에서는 DTMF 보내기 및 연속 DTMF 인식과 같은 통화 중에 개발자가 사용할 수 있는 작업에 대해 설명합니다. 작업에는 해당 작업을 호출하는 방법에 대한 샘플 코드가 함께 제공됩니다.

통화 자동화는 이 가이드에 포함되지 않은 통화 및 레코딩을 관리하는 기타 다양한 작업을 지원합니다.

참고 항목

통화 자동화는 현재 Microsoft Teams와 상호 운용되지 않습니다. 통화 자동화를 사용하여 Teams 사용자에게 전화를 걸거나 리디렉션하거나 Teams 사용자에게 오디오를 재생하는 등의 작업은 지원되지 않습니다.

이 가이드를 최대한 활용하려면 사전 요구 사항으로 아래 문서를 읽어보는 것이 좋습니다.

1. 통화 자동화 개념 가이드 - 작업-이벤트 프로그래밍 모델 및 이벤트 콜백에 대해 설명합니다.
2. 이 가이드에서 사용되는 사용자 식별자(예: CommunicationUserIdentifier 및 PhoneNumberIdentifier)에 대해 알아봅니다.
3. 통화 처리의 기본 사항을 처리하는 방법을 안내하는 통화 자동화를 사용하여 통화를 제어하고 조정하는 방법에 대해 자세히 알아보세요.

모든 코드 샘플에서 client는 표시된 대로 만들 수 있는 CallAutomationClient 개체이고, callConnection은 Answer 또는 CreateCall 응답에서 가져오는 CallConnection 개체입니다. 애플리케이션에서 받는 콜백 이벤트에서도 가져올 수 있습니다.

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

DTMF 보내기

외부 참가자에게 DTMF 버튼음을 보낼 수 있습니다. 이는 이미 통화 중이고 탐색할 내선 번호나 IVR 메뉴가 있는 다른 참가자를 초대해야 할 때 유용할 수 있습니다.

참고 항목

외부 PSTN 참가자에 대해서만 지원되며 한 번에 최대 18개의 버튼음을 보낼 수 있습니다.

SendDtmfAsync 메서드

외부 참가자에게 DTMF 버튼음 목록을 보냅니다.

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)

애플리케이션에서 이러한 DTMF 버튼음을 보내면 이벤트 업데이트가 수신됩니다. SendDtmfTonesCompleted 및 SendDtmfTonesFailed 이벤트를 사용하여 애플리케이션에서 비즈니스 논리를 만들어 다음 단계를 결정할 수 있습니다.

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

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

연속 DTMF 인식

통화 내내 연속 DTMF 버튼음을 수신하도록 구독할 수 있습니다. 대상 참가자가 키패드의 키를 누르면 애플리케이션이 DTMF 버튼음을 수신합니다. 이러한 버튼음은 참가자가 키를 누를 때 애플리케이션에 하나씩 전송됩니다.

StartContinuousDtmfRecognitionAsync 메서드

참가자가 보낸 DTMF 버튼음 감지를 시작합니다.

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

애플리케이션이 더 이상 참가자로부터 DTMF 버튼음을 수신하지 않으려는 경우 StopContinuousDtmfRecognitionAsync 메서드를 사용하여 Azure Communication Services에 DTMF 버튼음 감지를 중지하도록 알릴 수 있습니다.

StopContinuousDtmfRecognitionAsync

참가자가 보낸 DTMF 버튼음 감지를 중지합니다.

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

애플리케이션은 이러한 작업이 성공하거나 실패할 때 이벤트 업데이트를 받습니다. 이러한 이벤트를 사용하여 사용자 지정 비즈니스 논리를 빌드하고 애플리케이션이 이러한 이벤트 업데이트를 받을 때 수행해야 하는 다음 단계를 구성할 수 있습니다.

ContinuousDtmfRecognitionToneReceived 이벤트

DTMF 버튼음이 성공적으로 감지된 경우 처리할 수 있는 방법의 예입니다.

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는 애플리케이션에서 참가자가 DTMF 버튼음을 입력한 순서를 재구성하는 데 사용할 수 있는 ContinuousDtmfRecognitionToneReceived 이벤트의 일부로 SequenceId를 제공합니다.

ContinuousDtmfRecognitionFailed 이벤트

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 이벤트

연속 DTMF 인식이 중지된 경우를 처리하는 방법의 예는 애플리케이션이 StopContinuousDtmfRecognitionAsync 이벤트를 호출했거나 호출이 종료되었기 때문일 수 있습니다.

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