Jak kontrolować akcje multimediów w połowie wywołania za pomocą usługi Call Automation

Artykuł
11/02/2024

Usługa Call Automation używa interfejsu API REST do odbierania żądań dotyczących akcji i dostarczania odpowiedzi w celu powiadomienia o tym, czy żądanie zostało pomyślnie przesłane, czy nie. Ze względu na asynchroniczny charakter wywoływania większość akcji ma odpowiednie zdarzenia, które są wyzwalane po pomyślnym zakończeniu akcji lub niepomyślnie. W tym przewodniku opisano akcje dostępne dla deweloperów podczas wywołań, takie jak Wysyłanie dtMF i ciągłe rozpoznawanie DTMF. Do akcji dołączony jest przykładowy kod dotyczący sposobu wywoływania tej akcji.

Usługa Call Automation obsługuje różne inne akcje do zarządzania wywołaniami i nagrywaniem, które nie są zawarte w tym przewodniku.

Uwaga

Obecnie usługa Call Automation nie współdziała z usługą Microsoft Teams. Akcje takie jak tworzenie, przekierowywanie wywołania do użytkownika usługi Teams lub odtwarzanie dźwięku użytkownikowi usługi Teams przy użyciu usługi Call Automation nie jest obsługiwane.

W ramach wymagań wstępnych zalecamy przeczytanie poniższych artykułów, aby jak najlepiej wykorzystać ten przewodnik:

Przewodnik pojęć związanych z usługą Call Automation opisujący model programowania zdarzeń akcji i wywołania zwrotne zdarzeń.
Dowiedz się więcej o identyfikatorach użytkowników, takich jak CommunicationUserIdentifier i PhoneNumberIdentifier używanych w tym przewodniku.
Dowiedz się więcej o sposobie kontrolowania i kierowania wywołaniami za pomocą usługi Call Automation, która uczy cię o radzeniu sobie z podstawami radzenia sobie z wywołaniem.

W przypadku wszystkich przykładów kodu obiekt CallAutomationClient, client który można utworzyć, jak pokazano, i callConnection jest obiektem CallConnection uzyskanym z odpowiedzi Answer lub CreateCall. Można go również uzyskać z zdarzeń wywołania zwrotnego odebranych przez aplikację.

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

Wyślij DTMF

Możesz wysłać ton DTMF do zewnętrznego uczestnika, co może być przydatne, gdy jesteś już na wezwanie i musisz zaprosić innego uczestnika, który ma numer rozszerzenia lub menu IVR, aby przejść.

Uwaga

Jest to obsługiwane tylko dla zewnętrznych uczestników PSTN i obsługuje wysyłanie maksymalnie 18 ton jednocześnie.

SendDtmfAsync, metoda

Wyślij listę tonów DTMF do uczestnika zewnętrznego.

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)

Gdy aplikacja wysyła te dźwięki DTMF, otrzymujesz aktualizacje zdarzeń. Zdarzenia i SendDtmfTonesFailed umożliwiają SendDtmfTonesCompleted tworzenie logiki biznesowej w aplikacji w celu określenia następnych kroków.

Przykład zdarzenia 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']);

Przykład 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'])

Ciągłe rozpoznawanie DTMF

Możesz subskrybować odbieranie ciągłych tonów DTMF w całym wywołaniu. Aplikacja otrzymuje ton DTMF, gdy docelowy uczestnik naciska na na klawiaturze. Te odcienie są wysyłane do aplikacji jeden po drugim, ponieważ uczestnik naciska na nie.

StartContinuousDtmfRecognitionAsync, metoda

Rozpocznij wykrywanie tonów DTMF wysłanych przez uczestnika.

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

Gdy aplikacja nie chce już otrzymywać od uczestnika tonów DTMF, możesz użyć StopContinuousDtmfRecognitionAsync metody , aby poinformować usługi Azure Communication Services, aby zatrzymać wykrywanie tonów DTMF.

StopContinuousDtmfRecognitionAsync

Zatrzymaj wykrywanie tonów DTMF wysłanych przez uczestnika.

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

Aplikacja odbiera aktualizacje zdarzeń, gdy te akcje kończą się powodzeniem lub niepowodzeniem. Za pomocą tych zdarzeń można utworzyć niestandardową logikę biznesową w celu skonfigurowania następnego kroku, który aplikacja musi wykonać po odebraniu tych aktualizacji zdarzeń.

ContinuousDtmfRecognitionToneReceived Event

Przykład pomyślnego wykrycia tonu 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'])

Usługi Azure Communication Services udostępniają w SequenceId ramach ContinuousDtmfRecognitionToneReceived zdarzenia, którego aplikacja może użyć do odtworzenia kolejności, w której uczestnik wprowadził ton DTMF.

ContinuousDtmfRecognitionFailed Event

Przykład sposobu obsługi wykrywania tonu DTMF kończy się niepowodzeniem.

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

Zdarzenie ContinuousDtmfRecogntionStopped

Przykład sposobu obsługi zatrzymania ciągłego rozpoznawania DTMF może to być spowodowane tym, że aplikacja wywołała StopContinuousDtmfRecognitionAsync zdarzenie lub wywołanie zostało zakończone.

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

Hold

Akcja blokady umożliwia deweloperom tymczasowe wstrzymanie konwersacji między uczestnikiem a systemem lub agentem. Może to być przydatne w scenariuszach, w których uczestnik musi zostać przeniesiony do innego agenta lub działu lub gdy agent musi skonsultować się z przełożonym w tle przed kontynuowaniem rozmowy. W tym czasie możesz wybrać odtwarzanie dźwięku uczestnikowi, który jest wstrzymany.

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

Wstrzymanie

Akcja wstrzymania umożliwia deweloperom wznowienie rozmowy między uczestnikiem a systemem lub agentem, który został wcześniej wstrzymany. Gdy uczestnik zostanie zdjęty z blokady, będzie mógł ponownie usłyszeć system lub agenta.

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

Przesyłanie strumieniowe audio (publiczna wersja zapoznawcza)

Przesyłanie strumieniowe audio umożliwia subskrybowanie strumieni audio w czasie rzeczywistym z trwającego połączenia. Aby uzyskać bardziej szczegółowe wskazówki dotyczące rozpoczynania pracy z przesyłaniem strumieniowym audio i informacjami o zdarzeniach wywołania zwrotnego przesyłania strumieniowego audio, zobacz tę stronę.

Transkrypcja w czasie rzeczywistym (publiczna wersja zapoznawcza)

Transkrypcja w czasie rzeczywistym umożliwia dostęp do transkrypcji na żywo dla dźwięku trwającego połączenia. Aby uzyskać bardziej szczegółowe wskazówki dotyczące rozpoczynania pracy z transkrypcją w czasie rzeczywistym i informacji o zdarzeniach zwrotnych transkrypcji w czasie rzeczywistym, zobacz tę stronę.

Tabela zgodności akcji multimediów

W poniższej tabeli przedstawiono, jakie operacje multimediów mogą być uruchamiane/kolejkowane, jeśli poprzednia operacja nadal jest uruchomiona/w kolejce.

Istniejąca operacja	Odwołuj nogę	Dozwolone	Niedozwolone
PlayToAll	Główne	PlayToAll, Recognize(Non-Group Call), PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition	Brak
Recognize(wywołanie niegrupowe)	Główne	PlayToAll, Recognize(Non-Group Call), PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition	Brak
PlayTo	Sub	PlayToAll, Recognize(wywołanie niegrupowe)	PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition
Recognize(Wywołanie grupy)	Sub	PlayToAll, Recognize(wywołanie niegrupowe)	PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition
SendDTMF	Sub	PlayToAll, Recognize(wywołanie niegrupowe)	PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition
StartContinuousDtmfRecognition	Sub	PlayToAll, Recognize(Non-Group Call),PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition	Brak

Udostępnij za pośrednictwem