Mediaacties voor middengesprekken beheren met Gespreksautomatisering

Aanroepautomatisering maakt gebruik van een REST API-interface voor het ontvangen van aanvragen voor acties en het verstrekken van antwoorden om te melden of de aanvraag is verzonden of niet. Vanwege de asynchrone aard van het aanroepen hebben de meeste acties overeenkomende gebeurtenissen die worden geactiveerd wanneer de actie is voltooid of mislukt. In deze handleiding worden de acties beschreven die beschikbaar zijn voor ontwikkelaars tijdens aanroepen, zoals DTMF en Continue DTMF-herkenning. Acties worden vergezeld van voorbeeldcode over het aanroepen van de genoemde actie.

Gespreksautomatisering ondersteunt verschillende andere acties voor het beheren van oproepen en opnemen die niet zijn opgenomen in deze handleiding.

Notitie

Gespreksautomatisering werkt momenteel niet samen met Microsoft Teams. Acties zoals het maken, omleiden van een oproep naar een Teams-gebruiker of het afspelen van audio naar een Teams-gebruiker met behulp van Gespreksautomatisering, worden niet ondersteund.

Als vereiste raden we u aan de onderstaande artikelen te lezen om optimaal gebruik te maken van deze handleiding:

1. Handleiding voor aanroepautomatiseringsconcepten waarin het programmeermodel voor actiegebeurtenissen en callbacks voor gebeurtenissen wordt beschreven.
2. Meer informatie over gebruikers-id's zoals CommunicationUserIdentifier en PhoneNumberIdentifier die in deze handleiding worden gebruikt.
3. Meer informatie over het beheren en sturen van gesprekken met Gespreksautomatisering, waarmee u de basisbeginselen van het omgaan met een gesprek leert.

Voor alle codevoorbeelden client is CallAutomationClient-object dat kan worden gemaakt zoals weergegeven en callConnection het CallConnection-object is verkregen uit Answer of CreateCall-antwoord. U kunt deze ook verkrijgen via callbackgebeurtenissen die door uw toepassing zijn ontvangen.

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 verzenden

U kunt DTMF-tonen verzenden naar een externe deelnemer, wat handig kan zijn wanneer u al in gesprek bent en een andere deelnemer moet uitnodigen die een toestelnummer of een IVR-menu heeft om te navigeren.

Notitie

Dit wordt alleen ondersteund voor externe PSTN-deelnemers en ondersteunt het verzenden van maximaal 18 tonen tegelijk.

Methode SendDtmfAsync

Verzend een lijst met DTMF-tonen naar een externe deelnemer.

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)

Wanneer uw toepassing deze DTMF-tonen verzendt, ontvangt u gebeurtenisupdates. U kunt de SendDtmfTonesCompleted en SendDtmfTonesFailed gebeurtenissen gebruiken om bedrijfslogica in uw toepassing te maken om de volgende stappen te bepalen.

Voorbeeld van sendDtmfTonesCompleted-gebeurtenis

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

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

Continue DTMF-herkenning

U kunt zich abonneren om doorlopende DTMF-tonen te ontvangen tijdens het gesprek. Uw toepassing ontvangt DTMF-tonen terwijl de beoogde deelnemer op een toets op het toetsenblok drukt. Deze tonen worden één voor één naar uw toepassing verzonden terwijl de deelnemer erop drukt.

Methode StartContinuousDtmfRecognitionAsync

Begin met het detecteren van DTMF-tonen die door een deelnemer zijn verzonden.

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

Wanneer uw toepassing geen DTMF-tonen meer van de deelnemer wil ontvangen, kunt u de StopContinuousDtmfRecognitionAsync methode gebruiken om Azure Communication Services te laten weten dat de DTMF-tonen niet meer worden gedetecteerd.

StopContinuousDtmfRecognitionAsync

Stop met het detecteren van DTMF-tonen die door de deelnemer zijn verzonden.

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

Uw toepassing ontvangt gebeurtenisupdates wanneer deze acties slagen of mislukken. U kunt deze gebeurtenissen gebruiken om aangepaste bedrijfslogica te bouwen om de volgende stap te configureren die uw toepassing moet uitvoeren wanneer deze gebeurtenisupdates worden ontvangen.

ContinuousDtmfRecognitionToneReceived-gebeurtenis

Voorbeeld van hoe u een DTMF-toon kunt verwerken die is gedetecteerd.

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 biedt u een SequenceId onderdeel van het ContinuousDtmfRecognitionToneReceived evenement, dat uw toepassing kan gebruiken om de volgorde te reconstrueren waarin de deelnemer de DTMF-tonen heeft ingevoerd.

Gebeurtenis ContinuousDtmfRecognitionFailed

Voorbeeld van hoe u kunt omgaan met het detecteren van DTMF-toon.

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

Voorbeeld van het afhandelen wanneer continue DTMF-herkenning is gestopt, kan dit komen doordat de toepassing de StopContinuousDtmfRecognitionAsync gebeurtenis heeft aangeroepen of omdat de aanroep is beëindigd.

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

Houden

Met de bewaringsactie kunnen ontwikkelaars een gesprek tussen een deelnemer en een systeem of agent tijdelijk onderbreken. Dit kan handig zijn in scenario's waarin de deelnemer moet worden overgebracht naar een andere agent of afdeling of wanneer de agent een supervisor op de achtergrond moet raadplegen voordat het gesprek wordt voortgezet. Gedurende deze periode kunt u ervoor kiezen om audio af te spelen voor de deelnemer die in de wachtstand staat.

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

Uit de wacht halen

Met deze actie kunnen ontwikkelaars een gesprek hervatten tussen een deelnemer en een systeem of agent die eerder is onderbroken. Wanneer de deelnemer uit de wachtstand is gehaald, kunnen ze het systeem of de agent opnieuw horen.

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

Audiostreaming (openbare preview)

Met audiostreaming kunt u zich abonneren op realtime audiostreams vanuit een doorlopend gesprek. Zie deze pagina voor meer gedetailleerde richtlijnen over hoe u aan de slag gaat met audiostreaming en informatie over callback-gebeurtenissen voor audiostreaming.

Realtime transcriptie (openbare preview)

Met realtime transcriptie hebt u toegang tot livetranscripties voor de audio van een doorlopend gesprek. Zie deze pagina voor meer gedetailleerde richtlijnen over hoe u aan de slag gaat met realtimetranscriptie en informatie over callbackgebeurtenissen voor realtimetranscriptie.

Compatibiliteitstabel mediaactie

De volgende tabel illustreert de mediabewerkingen die mogen worden uitgevoerd/wachtrij als een vorige bewerking nog steeds wordt uitgevoerd/in de wachtrij wordt geplaatst.

Bestaande bewerking	Been bellen	Toegestaan	Niet toegestaan
PlayToAll	Hoofd	PlayToAll, Recognize(niet-groepsoproep), PlayTo, Recognize(groepsoproep), SendDTMF, StartContinuousDtmfRecognition	Geen
Recognize (niet-groepsoproep)	Hoofd	PlayToAll, Recognize(niet-groepsoproep), PlayTo, Recognize(groepsoproep), SendDTMF, StartContinuousDtmfRecognition	Geen
PlayTo	Sub	PlayToAll, Recognize(niet-groepsoproep)	PlayTo, Recognize(Groepsoproep), SendDTMF, StartContinuousDtmfRecognition
Recognize(Groepsoproep)	Sub	PlayToAll, Recognize(niet-groepsoproep)	PlayTo, Recognize(Groepsoproep), SendDTMF, StartContinuousDtmfRecognition
SendDTMF	Sub	PlayToAll, Recognize(niet-groepsoproep)	PlayTo, Recognize(Groepsoproep), SendDTMF, StartContinuousDtmfRecognition
StartContinuousDtmfRecognition	Sub	PlayToAll, Recognize(niet-groepsoproep),PlayTo, Recognize(groepsoproep), SendDTMF, StartContinuousDtmfRecognition	Geen