Så här styr du medieåtgärder mitt i anropet med Samtalsautomation

Artikel
11/02/2024

Call Automation använder ett REST API-gränssnitt för att ta emot begäranden om åtgärder och ge svar för att meddela om begäran har skickats eller inte. På grund av anropets asynkrona karaktär har de flesta åtgärder motsvarande händelser som utlöses när åtgärden slutförs eller misslyckas. Den här guiden beskriver de åtgärder som är tillgängliga för utvecklare under anrop, till exempel Skicka DTMF och Kontinuerlig DTMF-igenkänning. Åtgärder åtföljs av exempelkod om hur du anropar åtgärden.

Samtalsautomation stöder olika andra åtgärder för att hantera anrop och inspelning som inte ingår i den här guiden.

Kommentar

Samtalsautomation samverkar för närvarande inte med Microsoft Teams. Åtgärder som att göra, omdirigera ett anrop till en Teams-användare eller spela upp ljud till en Teams-användare med hjälp av Samtalsautomation stöds inte.

Som en förutsättning rekommenderar vi att du läser artiklarna nedan för att få ut det mesta av den här guiden:

Guide för att anropa Automation-begrepp som beskriver programmeringsmodellen för åtgärdshändelser och återanrop till händelser.
Lär dig mer om användaridentifierare som CommunicationUserIdentifier och PhoneNumberIdentifier som används i den här guiden.
Läs mer om hur du styr och styr samtal med Call Automation, som lär dig hur du hanterar grunderna i att hantera ett samtal.

För alla kodexempel client är Det CallAutomationClient-objekt som kan skapas som det visas och callConnection är CallConnection-objektet som hämtas från Svar eller CreateCall-svar. Du kan också hämta den från motringningshändelser som tas emot av ditt program.

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

Skicka DTMF

Du kan skicka DTMF-toner till en extern deltagare, vilket kan vara användbart när du redan är i ett samtal och behöver bjuda in en annan deltagare som har ett tilläggsnummer eller en IVR-meny för att navigera.

Kommentar

Detta stöds endast för externa PSTN-deltagare och stöder sändning av högst 18 toner i taget.

SendDtmfAsync-metod

Skicka en lista med DTMF-toner till en extern deltagare.

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)

När ditt program skickar dessa DTMF-toner får du händelseuppdateringar. Du kan använda SendDtmfTonesCompleted händelserna och SendDtmfTonesFailed för att skapa affärslogik i ditt program för att fastställa nästa steg.

Exempel på SendDtmfTonesCompleted-händelse

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

Exempel på 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'])

Kontinuerlig DTMF-igenkänning

Du kan prenumerera för att få kontinuerliga DTMF-toner under hela samtalet. Ditt program får DTMF-toner när den målinriktade deltagaren trycker på en nyckel på deras knappsats. Dessa toner skickas till ditt program en i taget när deltagaren trycker på dem.

StartContinuousDtmfRecognitionAsync-metod

Börja identifiera DTMF-toner som skickats av en deltagare.

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

När ditt program inte längre vill ta emot DTMF-toner från deltagaren längre kan du använda StopContinuousDtmfRecognitionAsync metoden för att låta Azure Communication Services veta för att sluta identifiera DTMF-toner.

StopContinuousDtmfRecognitionAsync

Sluta identifiera DTMF-toner som skickats av deltagaren.

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

Programmet får händelseuppdateringar när dessa åtgärder antingen lyckas eller misslyckas. Du kan använda dessa händelser för att skapa anpassad affärslogik för att konfigurera nästa steg som programmet måste ta när det tar emot dessa händelseuppdateringar.

ContinuousDtmfRecognitionToneReceived-händelse

Exempel på hur du kan hantera en DTMF-ton har identifierats.

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 ger dig en som en SequenceId del av ContinuousDtmfRecognitionToneReceived händelsen, som ditt program kan använda för att rekonstruera den ordning som deltagaren angav DTMF-toner i.

ContinuousDtmfRecognitionFailed-händelse

Exempel på hur du kan hantera när DTMF-tonidentifiering misslyckas.

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

ContinuousDtmfRecogntionStopad händelse

Exempel på hur du hanterar när den kontinuerliga DTMF-igenkänningen har stoppats kan bero på att programmet anropade StopContinuousDtmfRecognitionAsync händelsen eller att anropet har avslutats.

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

Behåll

Med undantagsåtgärden kan utvecklare tillfälligt pausa en konversation mellan en deltagare och ett system eller en agent. Detta kan vara användbart i scenarier där deltagaren måste överföras till en annan agent eller avdelning eller när agenten behöver konsultera en övervakare i bakgrunden innan konversationen fortsätter. Under den här tiden kan du välja att spela upp ljud till deltagaren som är pausade.

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

Ta bort källskatt

Åtgärden unhold gör att utvecklare kan återuppta en konversation mellan en deltagare och ett system eller en agent som tidigare pausats. När deltagaren tas ur tjänst kommer de att kunna höra systemet eller agenten igen.

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

Ljuduppspelning (offentlig förhandsversion)

Med ljudströmning kan du prenumerera på realtidsljudströmmar från ett pågående samtal. Mer detaljerad vägledning om hur du kommer igång med ljudströmning och information om återanropshändelser för ljudströmning finns på den här sidan.

Transkription i realtid (offentlig förhandsversion)

Med transkription i realtid kan du få åtkomst till live-transkriptioner för ljudet från ett pågående samtal. Mer detaljerad vägledning om hur du kommer igång med transkription i realtid och information om återanropshändelser för transkription i realtid finns på den här sidan.

Kompatibilitetstabell för medieåtgärder

I följande tabell visas vilka medieåtgärder som tillåts köra/köa om en tidigare åtgärd fortfarande körs/köas.

Befintlig åtgärd	Ring upp ben	Tillåtet	Tillåts inte
PlayToAll	Huvud	PlayToAll, Recognize(Non-Group Call), PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition	Ingen
Recognize(Non-Group Call)	Huvud	PlayToAll, Recognize(Non-Group Call), PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition	Ingen
PlayTo	Sub	PlayToAll, Recognize(Non-Group Call)	PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition
Recognize(Group Call)	Sub	PlayToAll, Recognize(Non-Group Call)	PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition
SendDTMF	Sub	PlayToAll, Recognize(Non-Group Call)	PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition
StartContinuousDtmfRecognition	Sub	PlayToAll, Recognize(Non-Group Call),PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition	Ingen

Dela via