So steuern Sie Medienaktionen während eines Anrufs mit der Anrufautomatisierung

Die Anrufautomatisierung verwendet eine REST-API-Schnittstelle, um Anforderungen für Aktionen zu empfangen und Antworten bereitzustellen, um darüber zu informieren, ob die Anforderung erfolgreich übermittelt wurde. Da Anrufe asynchron erfolgen, verfügen die meisten Aktionen über entsprechende Ereignisse, die ausgelöst werden, wenn die Aktion erfolgreich oder mit Fehlern abgeschlossen wird. In diesem Leitfaden werden die Aktionen behandelt, die Entwickler*innen während Anrufen zur Verfügung stehen, z. B. „DTMF senden“ und „Fortlaufende DTMF-Erkennung“. Den Aktionen ist ein Beispielcode beigefügt, der zeigt, wie die betreffende Aktion aufgerufen werden kann.

Die Anrufautomatisierung unterstützt verschiedene andere Aktionen zum Verwalten von Anrufe und Aufzeichnungen, die in diesem Leitfaden nicht enthalten sind.

Hinweis

Die Anrufautomatisierung kann derzeit nicht mit Microsoft Teams interagieren. Aktionen wie das Tätigen oder Umleiten eines Anrufs an Teams-Benutzer*innen oder das Wiedergeben von Audio für Teams-Benutzer*innen mithilfe der Anrufautomatisierung werden nicht unterstützt.

Als Voraussetzung wird empfohlen, die folgenden Artikel zu lesen, um diesen Leitfaden optimal nutzen zu können:

1. Im Leitfaden mit Konzepten der Anrufautomatisierung werden das Programmiermodell für Aktionen und Ereignisse sowie Ereignisrückrufe beschrieben.
2. Erfahren Sie mehr über Benutzerbezeichner wie CommunicationUserIdentifier und PhoneNumberIdentifier, die in diesem Leitfaden verwendet werden.
3. Erfahren Sie mehr darüber, wie Sie Anrufe mit der Anrufautomatisierung kontrollieren und steuern, wodurch Sie mehr über die Grundlagen des Umgangs mit einem Anruf erfahren.

Für alle Codebeispiele ist client das CallAutomationClient-Objekt, das wie gezeigt erstellt werden kann, und callConnection ist das CallConnection-Objekt, das aus der Antwort oder der CreateCall-Antwort abgerufen wird. Sie können es auch aus Rückrufereignissen abrufen, die von Ihrer Anwendung empfangen wurden.

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 senden

Sie können DTMF-Töne an einen externe*n Teilnehmer*in senden. Dies kann hilfreich sein, wenn Sie bereits an einem Anruf teilnehmen und eine*n andere*n Teilnehmer*in einladen müssen, der*die über eine Durchwahlnummer oder ein IVR-Menü verfügt, um zu navigieren.

Hinweis

Dies wird nur für externe PSTN-Teilnehmende unterstützt. Es können maximal 18 Tönen gleichzeitig gesendet werden.

SendDtmfAsync-Methode

Senden Sie eine Liste der DTMF-Töne an externe Teilnehmende.

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)

Wenn Ihre Anwendung diese DTMF-Töne sendet, erhalten Sie Ereignisupdates. Sie können die Geschäftslogik in Ihrer Anwendung mithilfe der Ereignisse SendDtmfTonesCompleted und SendDtmfTonesFailed erstellen, um die nächsten Schritte zu ermitteln.

Beispiel für ein SendDtmfTonesCompleted-Ereignis

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

Beispiel für 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']) 

Fortlaufende DTMF-Erkennung

Sie können den Empfang fortlaufender DTMF-Töne während des gesamten Anrufs abonnieren. Ihre Anwendung empfängt DTMF-Töne, wenn die anvisierten Teilnehmenden auf eine Taste auf der Wähltastatur drückt. Diese Töne werden nacheinander an Ihre Anwendung gesendet, während der*die Teilnehmer*in sie drückt.

StartContinuousDtmfRecognitionAsync-Methode

Beginnen Sie mit der Erkennung von DTMF-Tönen, die von Teilnehmenden gesendet werden.

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

Wenn Ihre Anwendung keine DTMF-Töne mehr von Teilnehmenden empfangen soll, können Sie die StopContinuousDtmfRecognitionAsync-Methode verwenden, um Azure Communication Services mitzuteilen, dass DTMF-Töne nicht mehr erkannt werden sollen.

StopContinuousDtmfRecognitionAsync

Beenden Sie die Erkennung von DTMF-Tönen, die von Teilnehmenden gesendet werden.

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

Ihre Anwendung empfängt Ereignisupdates, wenn diese Aktionen erfolgreich sind oder fehlschlagen. Sie können diese Ereignisse verwenden, um benutzerdefinierte Geschäftslogik zu erstellen, um den nächsten Schritt zu konfigurieren, den Ihre Anwendung ausführen muss, wenn sie diese Ereignisupdates empfängt.

ContinuousDtmfRecognitionToneReceived-Ereignis

Beispiel, wie Sie einen erfolgreich erkannten DTMF-Ton behandeln können.

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 bietet Ihnen eine SequenceId als Teil des ContinuousDtmfRecognitionToneReceived-Ereignisses, mit der Ihre Anwendung die Reihenfolge rekonstruieren kann, in der Teilnehmende die DTMF-Töne eingegeben haben.

ContinuousDtmfRecognitionFailed-Ereignis

Beispiel, wie Sie vorgehen können, wenn die DTMF-Tonerkennung fehlschlägt.

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-Ereignis

Beispiel für die Behandlung, wenn die kontinuierliche DTMF-Erkennung gestoppt wurde, sei es, weil Ihre Anwendung das StopContinuousDtmfRecognitionAsync-Ereignis aufgerufen hat oder weil der Anruf beendet wurde.

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

Halten

Mit der Aktion „Halten“ können Entwickler*innen vorübergehend eine Unterhaltung zwischen Teilnehmenden und einem System oder Agent anhalten. Dies kann hilfreich sein, wenn Teilnehmende an einen anderen Agenten oder eine andere Abteilung übertragen werden müssen oder wenn der Agent einen Vorgesetzten im Hintergrund konsultieren muss, bevor er die Unterhaltung fortsetzt. Während dieser Zeit können Sie den wartenden Teilnehmenden Audio vorspielen.

csharp

// 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);
*/

java

// 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);
*/

JavaScript

// 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);
*/

Python

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

Nicht halten

Mit der Aktion „Nicht halten“ können Entwickler*innen eine Unterhaltung zwischen Teilnehmenden und einem System oder Agent fortsetzen, die zuvor angehalten wurde. Wenn die Teilnehmenden nicht mehr warten müssen, können sie das System oder den Agenten wieder hören.

csharp

var unHoldOptions = new UnholdOptions(target) 
{ 
    OperationContext = "UnHoldPstnParticipant" 
}; 

// Option 1
var UnHoldParticipant = await callMedia.UnholdAsync(unHoldOptions);

/* 
// Option 2
var UnHoldParticipant = await callMedia.UnholdAsync(target);
*/

java

// Option 1
client.getCallConnection(callConnectionId).getCallMedia().unholdWithResponse(target, "unholdPstnParticipant", Context.NONE);

/* 
// Option 2
client.getCallConnection(callConnectionId).getCallMedia().unhold(target);
*/

JavaScript

const unholdOptions = { 
    operationContext: "unholdUserContext" 
}; 

// Option 1
await callMedia.unhold(target);

/* 
// Option 2
await callMedia.unhold(target, unholdOptions);
*/

Python

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

Audio-Streaming (Public Preview)

Mit dem Audio-Streaming können Sie Audiodatenströme aus einem laufenden Anruf in Echtzeit abonnieren. Ausführlichere Anleitungen zu den ersten Schritten mit Audio-Streaming und Informationen zu Audio-Streaming-Rückrufereignissen finden Sie auf dieser Seite.

Echtzeittranskription (Public Preview)

Mithilfe der Echtzeittranskription können Sie auf Livetranskriptionen für das Audio eines laufenden Anrufs zugreifen. Ausführlichere Anleitungen für die ersten Schritte mit der Echtzeittranskription und Informationen zu Echtzeittranskriptions-Rückrufereignissen finden Sie auf dieser Seite.

Kompatibilitätstabelle für Medienaktionen

In der folgenden Tabelle wird veranschaulicht, welche Medienvorgänge ausgeführt/in die Warteschlange gestellt werden dürfen, wenn ein vorheriger Vorgang noch ausgeführt wird/in der Warteschlange steht.

Vorhandener Vorgang	Bein anrufen	Zulässig	Unzulässig
PlayToAll	Main	PlayToAll, Erkennen(Anruf von außerhalb der Gruppe), PlayTo, Erkennen (Gruppenanruf), SendDTMF, StartContinuousDtmfRecognition	Keine
Erkennen(Anruf von außerhalb der Gruppe)	Main	PlayToAll, Erkennen(Anruf von außerhalb der Gruppe), PlayTo, Erkennen (Gruppenanruf), SendDTMF, StartContinuousDtmfRecognition	Keine
PlayTo	Sub	PlayToAll, Erkennen(Anruf von außerhalb der Gruppe)	PlayTo, Erkennen(Gruppenanruf), SendDTMF, StartContinuousDtmfRecognition
Erkennen(Gruppenanruf)	Sub	PlayToAll, Erkennen(Anruf von außerhalb der Gruppe)	PlayTo, Erkennen(Gruppenanruf), SendDTMF, StartContinuousDtmfRecognition
SendDTMF	Sub	PlayToAll, Erkennen(Anruf von außerhalb der Gruppe)	PlayTo, Erkennen(Gruppenanruf), SendDTMF, StartContinuousDtmfRecognition
StartContinuousDtmfRecognition	Sub	PlayToAll, Erkennen(Anruf von außerhalb der Gruppe), PlayTo, Erkennen(Gruppenanruf), SendDTMF, StartContinuousDtmfRecognition	Keine