Řízení akcí médií uprostřed volání pomocí automatizace volání

Automatizace volání používá rozhraní REST API k příjmu požadavků na akce a poskytnutí odpovědí, které upozorňují, jestli byl požadavek úspěšně odeslán nebo ne. Vzhledem k asynchronní povaze volání má většina akcí odpovídající události, které se aktivují, když se akce úspěšně dokončí nebo selže. Tato příručka popisuje akce dostupné vývojářům během volání, jako je odesílání DTMF a průběžné rozpoznávání DTMF. Akce jsou doprovázeny ukázkovým kódem o tom, jak vyvolat zmíněné akce.

Automatizace volání podporuje různé další akce pro správu hovorů a nahrávání, které nejsou součástí této příručky.

Poznámka:

Automatizace hovorů v současné době nespolupracuje s Microsoft Teams. Akce, jako je provádění, přesměrování hovoru na uživatele Teams nebo přehrávání zvuku na uživatele Teams pomocí automatizace hovorů se nepodporuje.

Jako předpoklad doporučujeme přečíst si následující články, které vám povedou na maximum z tohoto průvodce:

1. Průvodce koncepty automatizace volání, který popisuje programovací model akcí a zpětné volání událostí.
2. Seznamte se s identifikátory uživatelů, jako jsou CommunicationUserIdentifier a PhoneNumberIdentifier používané v této příručce.
3. Přečtěte si další informace o tom, jak řídit a řídit volání pomocí automatizace volání, která vás naučí o práci se základy práce s voláním.

Pro všechny ukázky kódu je CallAutomationClient objekt, client který lze vytvořit, jak je znázorněno a callConnection je CallConnection objekt získaný z odpovědi Answer nebo CreateCall. Můžete ho také získat z událostí zpětného volání přijatých vaší aplikací.

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

Odeslat DTMF

Můžete posílat tóny DTMF externímu účastníkovi, což může být užitečné, když už jste na hovoru a potřebujete pozvat jiného účastníka, který má číslo linky nebo nabídku IVR pro navigaci.

Poznámka:

To se podporuje jenom u externích účastníků veřejné telefonní sítě a podporuje odesílání maximálně 18 tónů najednou.

SendDtmfAsync – metoda

Pošlete externímu účastníkovi seznam tónů DTMF.

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)

Když vaše aplikace odešle tyto tóny DTMF, obdržíte aktualizace událostí. Pomocí událostí a SendDtmfTonesFailed událostí můžete SendDtmfTonesCompleted ve své aplikaci vytvořit obchodní logiku a určit další kroky.

Příklad události 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']);

Příklad 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']) 

Průběžné rozpoznávání DTMF

Můžete se přihlásit k odběru nepřetržitých tónů DTMF během hovoru. Vaše aplikace obdrží tóny DTMF, protože cílový účastník stiskne na klávesu na klávesnici. Tyto tóny se posílají do aplikace jeden po druhém, protože je účastník stiskne.

StartContinuousDtmfRecognitionAsync – metoda

Začněte zjišťovat tóny DTMF odeslané účastníkem.

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

Pokud už vaše aplikace nechce od účastníka přijímat tóny DTMF, můžete pomocí StopContinuousDtmfRecognitionAsync této metody dát službě Azure Communication Services vědět, aby se zastavilo zjišťování tónů DTMF.

StopContinuousDtmfRecognitionAsync

Přestaňte zjišťovat tóny DTMF odeslané účastníkem.

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

Když tyto akce proběhnou úspěšně nebo selžou, vaše aplikace obdrží aktualizace událostí. Tyto události můžete použít k vytvoření vlastní obchodní logiky pro konfiguraci dalšího kroku, který vaše aplikace potřebuje, když obdrží tyto aktualizace událostí.

Událost ContinuousDtmfRecognitionToneReceived

Příklad úspěšného zjištění tónu 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'])  

Služba Azure Communication Services poskytuje SequenceId v rámci ContinuousDtmfRecognitionToneReceived události, kterou vaše aplikace může použít k rekonstrukci pořadí, ve kterém účastník vstoupil do tónů DTMF.

Událost ContinuousDtmfRecognitionFailed

Příklad, jak můžete zpracovat, když detekce tónu DTMF selže.

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

Událost ContinuousDtmfRecogntionStopped

Příklad, jak zpracovat, když je zastaveno průběžné rozpoznávání DTMF, může to být proto, že aplikace vyvolala StopContinuousDtmfRecognitionAsync událost nebo protože volání skončilo.

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

Hold

Akce blokování umožňuje vývojářům dočasně pozastavit konverzaci mezi účastníkem a systémem nebo agentem. To může být užitečné ve scénářích, kdy je nutné převést účastníka na jiného agenta nebo oddělení nebo v případě, že agent musí před pokračováním konverzace konzultovat vedoucího na pozadí. Během této doby se můžete rozhodnout přehrát zvuk účastníkovi, který je přidržený.

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

Nezdržovat

Akce nezdržování umožňuje vývojářům pokračovat v konverzaci mezi účastníkem a systémem nebo agentem, který byl dříve pozastaven. Když se účastník oddrží, bude moct znovu slyšet systém nebo agenta.

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

Streamování zvuku (Public Preview)

Streamování zvuku umožňuje přihlásit se k odběru zvukových streamů v reálném čase z probíhajícího hovoru. Podrobnější pokyny, jak začít se streamováním zvuku a informacemi o událostech zpětného volání streamování zvuku, najdete na této stránce.

Přepis v reálném čase (Public Preview)

Přepis v reálném čase umožňuje přístup k živým přepisům zvuku probíhajícího hovoru. Podrobnější pokyny k tomu, jak začít s přepisem v reálném čase a informacemi o událostech zpětného volání přepisu v reálném čase, najdete na této stránce.

Tabulka kompatibility akcí médií

Následující tabulka ukazuje, jaké operace médií se můžou spouštět nebo zařadit do fronty, pokud je předchozí operace stále spuštěná nebo zařazená do fronty.

Existující operace	Volat nohu	Povoleno	Zakázané
PlayToAll	Hlavní	PlayToAll, Recognize(Non-Group Call), PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition	Nic
Recognize (neskupovaný hovor)	Hlavní	PlayToAll, Recognize(Non-Group Call), PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition	Nic
PlayTo	Sub	PlayToAll, Recognize (neskupovací volání)	PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition
Recognize(skupinový hovor)	Sub	PlayToAll, Recognize (neskupovací volání)	PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition
SendDTMF	Sub	PlayToAll, Recognize (neskupovací volání)	PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition
StartContinuousDtmfRecognition	Sub	PlayToAll, Recognize(Non-Group Call),PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition	Žádné