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

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:

1. Przewodnik pojęć związanych z usługą Call Automation opisujący model programowania zdarzeń akcji i wywołania zwrotne zdarzeń.
2. Dowiedz się więcej o identyfikatorach użytkowników, takich jak CommunicationUserIdentifier i Telefon NumberIdentifier używanych w tym przewodniku.
3. 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.

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

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

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.

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)

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

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

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

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 klawisz 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.

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

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.

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

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.

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

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.

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

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.

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