Cara mengontrol tindakan media tengah panggilan dengan Automasi Panggilan

Artikel
11/02/2024

Automasi Panggilan menggunakan antarmuka REST API untuk menerima permintaan tindakan dan memberikan respons untuk memberi tahu apakah permintaan berhasil dikirimkan atau tidak. Karena sifat panggilan asinkron, sebagian besar tindakan memiliki peristiwa yang sesuai yang dipicu ketika tindakan berhasil diselesaikan atau gagal. Panduan ini mencakup tindakan yang tersedia untuk pengembang selama panggilan, seperti Kirim DTMF dan Pengenalan DTMF Berkelanjutan. Tindakan disertai dengan kode sampel tentang cara memanggil tindakan yang dikatakan.

Automation Panggilan mendukung berbagai tindakan lain untuk mengelola panggilan dan rekaman yang tidak disertakan dalam panduan ini.

Catatan

Automasi Panggilan saat ini tidak beroperasi dengan Microsoft Teams. Tindakan seperti membuat, mengalihkan panggilan ke pengguna Teams atau memutar audio ke pengguna Teams menggunakan Automasi Panggilan tidak didukung.

Sebagai prasyarat, kami sarankan Anda untuk membaca artikel di bawah ini untuk memanfaatkan panduan ini:

Panduan konsep Call Automation yang menjelaskan model pemrograman peristiwa tindakan dan panggilan balik peristiwa.
Pelajari tentang pengidentifikasi pengguna seperti CommunicationUserIdentifier dan PhoneNumberIdentifier yang digunakan dalam panduan ini.
Pelajari selengkapnya tentang cara mengontrol dan mengarahkan panggilan dengan Call Automation, yang mengajarkan Anda tentang berurusan dengan dasar-dasar menangani panggilan.

Untuk semua sampel kode, client adalah objek CallAutomationClient yang dapat dibuat seperti yang ditunjukkan dan callConnection merupakan objek CallConnection yang diperoleh dari respons Answer atau CreateCall. Anda juga dapat memperolehnya dari peristiwa panggilan balik yang diterima oleh aplikasi Anda.

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

Kirim DTMF

Anda dapat mengirim nada DTMF ke peserta eksternal, yang mungkin berguna ketika Anda sudah melakukan panggilan dan perlu mengundang peserta lain yang memiliki nomor ekstensi atau menu IVR untuk menavigasi.

Catatan

Ini hanya didukung untuk peserta PSTN eksternal dan mendukung pengiriman maksimum 18 nada sekaligus.

Metode SendDtmfAsync

Kirim daftar nada DTMF ke peserta eksternal.

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)

Saat aplikasi Anda mengirim nada DTMF ini, Anda menerima pembaruan peristiwa. Anda dapat menggunakan SendDtmfTonesCompleted peristiwa dan SendDtmfTonesFailed untuk membuat logika bisnis di aplikasi Anda untuk menentukan langkah-langkah berikutnya.

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

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

Pengenalan DTMF Berkelanjutan

Anda dapat berlangganan untuk menerima nada DTMF berkelanjutan sepanjang panggilan. Aplikasi Anda menerima nada DTMF saat peserta yang ditargetkan menekan tombol di keypad mereka. Nada ini dikirim ke aplikasi Anda satu per satu saat peserta menekannya.

Metode StartContinuousDtmfRecognitionAsync

Mulai mendeteksi nada DTMF yang dikirim oleh peserta.

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

Ketika aplikasi Anda tidak lagi ingin menerima nada DTMF dari peserta lagi, Anda dapat menggunakan StopContinuousDtmfRecognitionAsync metode untuk memberi tahu Azure Communication Services untuk berhenti mendeteksi nada DTMF.

StopContinuousDtmfRecognitionAsync

Berhenti mendeteksi nada DTMF yang dikirim oleh peserta.

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

Aplikasi Anda menerima pembaruan peristiwa ketika tindakan ini berhasil atau gagal. Anda dapat menggunakan peristiwa ini untuk membangun logika bisnis kustom untuk mengonfigurasi langkah berikutnya yang perlu diambil aplikasi Anda saat menerima pembaruan peristiwa ini.

Kejadian ContinuousDtmfRecognitionToneReceived

Contoh bagaimana Anda dapat menangani nada DTMF yang berhasil terdeteksi.

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 Communication Services memberi Anda SequenceId sebagai bagian ContinuousDtmfRecognitionToneReceived dari peristiwa, yang dapat digunakan aplikasi Anda untuk merekonstruksi urutan peserta memasukkan nada DTMF.

Kejadian ContinuousDtmfRecognitionFailed

Contoh bagaimana Anda dapat menangani ketika deteksi nada DTMF gagal.

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

Kejadian ContinuousDtmfRecogntionStopped

Contoh cara menangani ketika pengenalan DTMF berkelanjutan telah berhenti, ini bisa jadi karena aplikasi Anda memanggil StopContinuousDtmfRecognitionAsync peristiwa atau karena panggilan telah berakhir.

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

Pegang

Tindakan penahanan memungkinkan pengembang untuk menjeda sementara percakapan antara peserta dan sistem atau agen. Ini dapat berguna dalam skenario di mana peserta perlu ditransfer ke agen atau departemen lain atau ketika agen perlu berkonsultasi dengan supervisor di latar belakang sebelum melanjutkan percakapan. Selama waktu ini Anda dapat memilih untuk memutar audio ke peserta yang sedang ditangguhkan.

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

Batalkan tahan

Tindakan yang tidak dikunci memungkinkan pengembang untuk melanjutkan percakapan antara peserta dan sistem atau agen yang sebelumnya dijeda. Ketika peserta diambil dari penahanan, mereka akan dapat mendengar sistem atau agen lagi.

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

Streaming audio (pratinjau publik)

Streaming audio memungkinkan Anda berlangganan aliran audio real time dari panggilan yang sedang berlangsung. Untuk panduan selengkapnya tentang cara memulai streaming audio dan informasi tentang peristiwa panggilan balik streaming audio, lihat halaman ini.

Transkripsi real time (pratinjau publik)

Transkripsi real time memungkinkan Anda mengakses transkripsi langsung untuk audio panggilan yang sedang berlangsung. Untuk panduan selengkapnya tentang cara memulai transkripsi real time dan informasi tentang peristiwa panggilan balik transkripsi real time, lihat halaman ini.

Tabel Kompatibilitas Tindakan Media

Tabel berikut mengilustrasikan operasi media apa yang diizinkan untuk dijalankan/diantrekan jika operasi sebelumnya masih berjalan/diantrekan.

Operasi yang Ada	Kaki Panggilan	Diizinkan	Batasan
PlayToAll	Utama	PlayToAll, Recognize(Panggilan Non-Grup), PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition	Tidak
Recognize(Panggilan Non-Grup)	Utama	PlayToAll, Recognize(Panggilan Non-Grup), PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition	Tidak
PlayTo	Sub	PlayToAll, Recognize(Panggilan Non-Grup)	PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition
Kenali(Panggilan Grup)	Sub	PlayToAll, Recognize(Panggilan Non-Grup)	PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition
SendDTMF	Sub	PlayToAll, Recognize(Panggilan Non-Grup)	PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition
StartContinuousDtmfRecognition	Sub	PlayToAll, Recognize(Panggilan Non-Grup),PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition	Tidak ada

Bagikan melalui