Arama Otomasyonu ile arama ortası medya eylemlerini denetleme

Makale
11/02/2024

Çağrı Otomasyonu, eylemlere yönelik istekleri almak ve isteğin başarıyla gönderilip gönderilmediğini bildirmek üzere yanıtlar sağlamak için REST API arabirimi kullanır. Çağırmanın zaman uyumsuz yapısı nedeniyle çoğu eylem, eylem başarıyla tamamlandığında veya başarısız olduğunda tetiklenen ilgili olaylara sahiptir. Bu kılavuz, aramalar sırasında DTMF Gönderme ve Sürekli DTMF Tanıma gibi geliştiricilerin kullanabileceği eylemleri kapsar. Eylemlere, söz edilen eylemin nasıl çağrıldığını gösteren örnek kod eşlik eder.

Çağrı Otomasyonu, bu kılavuza dahil olmayan çağrıları ve kaydı yönetmek için diğer çeşitli eylemleri destekler.

Not

Çağrı Otomasyonu şu anda Microsoft Teams ile birlikte çalışmıyor. Arama Otomasyonu kullanarak Teams kullanıcısına arama yapma, aramayı yeniden yönlendirme veya Teams kullanıcısına ses çalma gibi eylemler desteklenmez.

Önkoşul olarak, bu kılavuzdan en iyi şekilde emin olmak için aşağıdaki makaleleri okumanızı öneririz:

Eylem-olay programlama modelini ve olay geri çağırmalarını açıklayan Çağrı Otomasyonu kavramları kılavuzu .
Bu kılavuzda kullanılan CommunicationUserIdentifier ve PhoneNumberIdentifier gibi kullanıcı tanımlayıcıları hakkında bilgi edinin.
Çağrı otomasyonu ile çağrıları denetleme ve yönlendirme hakkında daha fazla bilgi edinin. Bu, size bir çağrıyla ilgilenmenin temellerini öğretir.

Tüm kod örnekleri için, client gösterildiği gibi oluşturulabilen CallAutomationClient nesnesidir ve callConnection Answer veya CreateCall yanıtından alınan CallConnection nesnesidir. Ayrıca, uygulamanız tarafından alınan geri çağırma olaylarından da alabilirsiniz.

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 Gönderme

Bir dış katılımcıya DTMF tonları gönderebilirsiniz. Bu, zaten bir aramada olduğunuzda ve uzantı numarası veya IVR menüsü olan başka bir katılımcıyı gezinmeye davet etmeniz gerektiğinde yararlı olabilir.

Not

Bu yalnızca dış PSTN katılımcıları için desteklenir ve aynı anda en fazla 18 ton göndermeyi destekler.

SendDtmfAsync Yöntemi

Dış katılımcıya DTMF tonlarının listesini gönderin.

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)

Uygulamanız bu DTMF tonlarını gönderdiğinde olay güncelleştirmeleri alırsınız. Sonraki adımları belirlemek üzere uygulamanızda iş mantığı oluşturmak için ve SendDtmfTonesFailed olaylarını kullanabilirsinizSendDtmfTonesCompleted.

SendDtmfTonesCompleted olayı örneği

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 örneği

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

Sürekli DTMF Tanıma

Arama boyunca sürekli DTMF tonları almak için abone olabilirsiniz. Hedeflenen katılımcı tuş takımındaki bir tuşa bastığında uygulamanız DTMF tonlarını alır. Bu tonlar, katılımcı bunlara bastığında uygulamanıza tek tek gönderilir.

StartContinuousDtmfRecognitionAsync Yöntemi

Katılımcı tarafından gönderilen DTMF tonlarını algılamaya başlayın.

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

Uygulamanız artık katılımcıdan DTMF tonları almak istediğinde, Azure İletişim Hizmetleri DTMF tonlarını algılamayı durdurmasını bildirmek için yöntemini kullanabilirsinizStopContinuousDtmfRecognitionAsync.

StopContinuousDtmfRecognitionAsync

Katılımcı tarafından gönderilen DTMF tonlarını algılamayı durdurun.

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

Uygulamanız, bu eylemler başarılı veya başarısız olduğunda olay güncelleştirmelerini alır. Uygulamanızın bu olay güncelleştirmelerini aldığında gerçekleştirmesi gereken bir sonraki adımı yapılandırmak üzere özel iş mantığı oluşturmak için bu olayları kullanabilirsiniz.

ContinuousDtmfRecognitionToneReceived Olayı

Algılanan bir DTMF tonunun nasıl işleneceğini gösteren örnek.

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 İletişim Hizmetleri, size etkinliğin ContinuousDtmfRecognitionToneReceived bir parçası olarak, uygulamanızın katılımcının DTMF tonlarına girme sırasını yeniden oluşturmak için kullanabileceği bir SequenceId sağlar.

ContinuousDtmfRecognitionFailed Olayı

DTMF ton algılaması başarısız olduğunda nasıl işleyebileceğinize örnek.

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 Olayı

Sürekli DTMF tanıma durdurulduğunda nasıl işleneceğini gösteren örnek, bunun nedeni uygulamanızın olayı çağırması veya çağrının StopContinuousDtmfRecognitionAsync sona ermiş olması olabilir.

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

Basılı Tutma

Ayrı tutma eylemi, geliştiricilerin bir katılımcı ile sistem veya aracı arasındaki konuşmayı geçici olarak duraklatmasını sağlar. Bu, katılımcının başka bir aracıya veya departmana aktarılması gereken senaryolarda veya temsilcinin konuşmaya devam etmeden önce arka planda bir gözetmene danışması gerektiğinde yararlı olabilir. Bu süre boyunca, beklemedeki katılımcıya ses çalmayı seçebilirsiniz.

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

Beklet

Korumayı kaldırma eylemi, geliştiricilerin daha önce duraklatılmış olan bir katılımcı ile sistem veya aracı arasındaki konuşmayı sürdürmesine olanak tanır. Katılımcı beklemeden kaldırıldığında sistemi veya aracıyı yeniden duyabilecektir.

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

Ses akışı (genel önizleme)

Ses akışı, devam eden bir aramadan gerçek zamanlı ses akışlarına abone olmanıza olanak tanır. Ses akışını kullanmaya başlama hakkında daha ayrıntılı yönergeler ve ses akışı geri çağırma olayları hakkında bilgi için bu sayfaya bakın.

Gerçek zamanlı transkripsiyon (genel önizleme)

Gerçek zamanlı transkripsiyon, devam eden bir aramanın sesi için canlı transkripsiyonlara erişmenizi sağlar. Gerçek zamanlı transkripsiyonu kullanmaya başlama hakkında daha ayrıntılı yönergeler ve gerçek zamanlı transkripsiyon geri çağırma olayları hakkında bilgi için bu sayfaya bakın.

Medya Eylemi Uyumluluk Tablosu

Aşağıdaki tabloda, önceki bir işlem çalışmaya/kuyruğa alınmaya devam ediyorsa hangi medya işlemlerinin çalıştırılmasına/kuyruğa alınmaya izin verilip verilmediğini göstermektedir.

Mevcut İşlem	Bacağını Ara	İzin Verilir	İzin verilmiyor
PlayToAll	Ana	PlayToAll, Recognize(Non-Group Call), PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition	Hiçbiri
Tanıma(Grup Dışı Arama)	Ana	PlayToAll, Recognize(Non-Group Call), PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition	Hiçbiri
PlayTo	Alt	PlayToAll, Recognize(Grup Dışı Çağrı)	PlayTo, Recognize(Grup Çağrısı), SendDTMF, StartContinuousDtmfRecognition
Tanıma(Grup Araması)	Alt	PlayToAll, Recognize(Grup Dışı Çağrı)	PlayTo, Recognize(Grup Çağrısı), SendDTMF, StartContinuousDtmfRecognition
SendDTMF	Alt	PlayToAll, Recognize(Grup Dışı Çağrı)	PlayTo, Recognize(Grup Çağrısı), SendDTMF, StartContinuousDtmfRecognition
StartContinuousDtmfRecognition	Alt	PlayToAll, Recognize(Non-Group Call),PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition	Hiçbiri

Aracılığıyla paylaş