Come controllare le azioni multimediali mid-call con l'automazione delle chiamate

Articolo
11/02/2024

L'automazione delle chiamate usa un'interfaccia API REST per ricevere richieste di azioni e fornire risposte per notificare se la richiesta è stata inviata o meno correttamente. A causa della natura asincrona della chiamata, la maggior parte delle azioni ha eventi corrispondenti che vengono attivati quando l'azione viene completata correttamente o ha esito negativo. Questa guida illustra le azioni disponibili per gli sviluppatori durante le chiamate, ad esempio Invia DTMF e Riconoscimento DTMF continuo. Le azioni sono accompagnate da un codice di esempio su come richiamare l'azione in corso.

L'automazione delle chiamate supporta varie altre azioni per gestire le chiamate e la registrazione che non sono incluse in questa guida.

Nota

L'automazione delle chiamate attualmente non interagisce con Microsoft Teams. Azioni come l'esecuzione, il reindirizzamento di una chiamata a un utente di Teams o la riproduzione di audio a un utente di Teams tramite Automazione chiamate non sono supportate.

Come prerequisito, è consigliabile leggere questi articoli per sfruttare al meglio questa guida:

Guida concettuale relativa all'automazione delle chiamate che descrive il modello di programmazione degli eventi action-event e i callback degli eventi.
Informazioni sugli identificatori utente come CommunicationUserIdentifier e PhoneNumberIdentifier usati in questa guida.
Altre informazioni su come controllare e gestire le chiamate con Automazione chiamate, che illustra le nozioni di base relative alla gestione di una chiamata.

Per tutti gli esempi di codice, client è l'oggetto CallAutomationClient che può essere creato come illustrato e callConnection è l'oggetto CallConnection ottenuto dalla risposta Answer o CreateCall. È anche possibile ottenerlo dagli eventi di callback ricevuti dall'applicazione.

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

Inviare DTMF

È possibile inviare toni DTMF a un partecipante esterno, il che può essere utile quando si è già in una chiamata e si deve invitare un altro partecipante che ha un numero di interno o un menu IVR per spostarsi.

Nota

Questa opzione è supportata solo per i partecipanti PSTN esterni e supporta l'invio di un massimo di 18 toni alla volta.

Metodo SendDtmfAsync

Inviare un elenco di toni DTMF a un partecipante esterno.

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)

Quando l'applicazione invia questi toni DTMF, si ricevono gli aggiornamenti degli eventi. È possibile usare gli eventi SendDtmfTonesCompleted e SendDtmfTonesFailed per creare logica di business nell'applicazione per determinare i passaggi successivi.

Esempio di evento SendDtmfTonesCompleted

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

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

Riconoscimento DTMF continuo

È possibile iscriversi per ricevere toni DTMF continui durante la chiamata. L'applicazione riceve toni DTMF quando il partecipante di destinazione preme un tasto sul tastierino. Tali toni vengono inviati all'applicazione uno alla volta, man mano che il partecipante li preme.

Metodo StartContinuousDtmfRecognitionAsync

Iniziare a rilevare i toni DTMF inviati da un partecipante.

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

Quando l'applicazione non vuole più ricevere toni DTMF dal partecipante, è possibile usare il metodo StopContinuousDtmfRecognitionAsync per informare Servizi di comunicazione di Azure di interrompere il rilevamento dei toni DTMF.

StopContinuousDtmfRecognitionAsync

Interrompere il rilevamento dei toni DTMF inviati dal partecipante.

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

L'applicazione riceve gli aggiornamenti degli eventi quando queste azioni hanno esito positivo o negativo. È possibile usare questi eventi per compilare logica di business personalizzata per configurare il passaggio successivo che l'applicazione deve eseguire quando riceve questi aggiornamenti degli eventi.

ContinuousDtmfRecognitionToneReceived

Esempio di come è possibile gestire correttamente un tono DTMF rilevato correttamente.

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

Servizi di comunicazione di Azure fornisce SequenceId quale parte dell'evento ContinuousDtmfRecognitionToneReceived, che l'applicazione può usare per ricostruire l'ordine in cui il partecipante ha immesso i toni DTMF.

Evento ContinuousDtmfRecognitionFailed

Esempio di come è possibile eseguire la gestione quando il rilevamento del tono DTMF ha esito negativo.

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

Evento ContinuousDtmfRecogntionStopped

Esempio di come effettuare la gestione quando il riconoscimento DTMF continuo è stato arrestato, ciò potrebbe essere dovuto al fatto che l'applicazione ha richiamato l'evento StopContinuousDtmfRecognitionAsync o che la chiamata è terminata.

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

Pausa

L'azione di messa in attesa consente agli sviluppatori di sospendere temporaneamente una conversazione tra un partecipante e un sistema o un agente. Ciò può essere utile negli scenari in cui il partecipante deve essere trasferito a un altro agente o reparto o quando l'agente deve consultare un supervisore in background prima di continuare la conversazione. Durante questo periodo è possibile scegliere di riprodurre l'audio al partecipante che è in attesa.

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

Riprendere chiamata

L'azione di annullamento della messa in attesa consente agli sviluppatori di riprendere una conversazione tra un partecipante e un sistema o un agente sospesa in precedenza. Quando per il partecipante viene annullata la messa in attesa, lo stesso sarà in grado di ascoltare di nuovo il sistema o l'agente.

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

Streaming audio (anteprima pubblica)

Lo streaming audio consente di sottoscrivere flussi audio in tempo reale da una chiamata in corso. Per indicazioni più dettagliate su come iniziare a usare lo streaming audio e informazioni sugli eventi di callback di streaming audio, vedere questa pagina.

Trascrizione in tempo reale (anteprima pubblica)

La trascrizione in tempo reale consente di accedere alle trascrizioni in tempo reale per l'audio di una chiamata in corso. Per indicazioni più dettagliate su come iniziare a usare la trascrizione in tempo reale e informazioni sugli eventi di callback della trascrizione in tempo reale, vedere questa pagina.

Tabella di compatibilità delle azioni multimediali

Nella tabella seguente vengono illustrate le operazioni multimediali consentite per l'esecuzione o la coda se un'operazione precedente è ancora in esecuzione o in coda.

Operazione esistente	Call Leg	Consentito	Non consentito
PlayToAll	Principale	PlayToAll, Recognize(Non-Group Call), PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition	None
Recognize(Chiamata non di gruppo)	Principale	PlayToAll, Recognize(Non-Group Call), PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition	None
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	Nessuno

Condividi tramite