Comment contrôler les actions multimédias en milieu d’appel avec Call Automation

Article
11/06/2024

Call Automation utilise une interface d’API REST pour recevoir des requêtes d’actions et fournir des réponses pour indiquer si la requête a été envoyée avec succès ou non. Pour la plupart des actions, des événements correspondants sont déclenchés lorsque l’action se termine correctement ou échoue, et ce, en raison de la nature asynchrone de l’appel. Ce guide décrit les actions disponibles pour les développeurs pendant les appels, telles que l’envoi et la reconnaissance continue de DTMF. Les actions sont accompagnées d’exemples de code montrant comment les appeler.

Call Automation prend en charge diverses autres actions pour gérer les appels et l’enregistrement, qui ne sont pas incluses dans ce guide.

Remarque

Call Automation n’est actuellement pas interopérable avec Microsoft Teams. Les actions telles que la création ou la redirection d’un appel vers un utilisateur Teams, ou la lecture audio vers un utilisateur Teams à l’aide de Call Automation ne sont pas prises en charge.

Comme condition préalable, nous vous recommandons de lire les articles ci-dessous pour tirer le meilleur parti de ce guide :

Guide des concepts de Call Automation, qui décrit le modèle de programmation d’événements d’action et les rappels d’événements.
Découvrez les identificateurs d’utilisateur comme CommunicationUserIdentifier et PhoneNumberIdentifier utilisés dans ce guide.
Découvrez davantage comment contrôler et diriger les appels avec Call Automation, qui vous apprend les principes fondamentaux de gestion des appels.

Pour tous les exemples de code, client est l’objet CallAutomationClient qui peut être créé comme indiqué, et callConnection est l’objet CallConnection obtenu à partir de la réponse Answer ou CreateCall. Vous pouvez également l’obtenir à partir d’événements de rappel reçus par votre application.

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

Envoyer DTMF

Vous pouvez envoyer des tonalités DTMF à un participant externe, ce qui peut être utile lorsque vous êtes déjà en cours d’appel et que vous devez inviter un autre participant disposant d’un numéro d’extension ou d’un menu RVI à parcourir.

Remarque

Cela est uniquement pris en charge pour les participants RTC externes et permet l’envoi d’un maximum de 18 tonalités simultanées.

Méthode SendDtmfAsync

Envoyez une liste de tonalités DTMF à un participant externe.

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)

Lorsque votre application envoie ces tonalités DTMF, vous recevez des mises à jour d’événements. Vous pouvez utiliser les événements SendDtmfTonesCompleted et SendDtmfTonesFailed pour créer une logique métier dans votre application afin de déterminer les étapes suivantes.

Exemple d’événement 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']);

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

Reconnaissance de DTMF en continu

Vous pouvez vous abonner pour recevoir des tonalités DTMF en continu tout au long de l’appel. Votre application reçoit des tonalités DTMF lorsque le participant ciblé appuie sur une touche sur son pavé numérique. Ces tonalités sont envoyées à votre application une par une au fur et à mesure que le participant appuie sur des touches.

Méthode StartContinuousDtmfRecognitionAsync

Commencez à détecter les tonalités DTMF envoyées par un participant.

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

Lorsque votre application ne souhaite plus recevoir les tonalités DTMF du participant, vous pouvez utiliser la méthode StopContinuousDtmfRecognitionAsync pour informer Azure Communication Services de cesser de détecter les tonalités DTMF.

StopContinuousDtmfRecognitionAsync

Arrêtez la détection des tonalités DTMF envoyées par le participant.

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

Votre application reçoit les mises à jour des événements lorsque ces actions réussissent ou échouent. Vous pouvez utiliser ces événements pour créer une logique métier personnalisée afin de configurer le comportement de votre application quand elle reçoit ces mises à jour d’événements.

Événement ContinuousDtmfRecognitionToneReceived

Exemple montrant comment vous pouvez gérer une tonalité DTMF détectée avec succès.

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 vous fournit un SequenceId avec l’événement ContinuousDtmfRecognitionToneReceived, que votre application peut utiliser pour reconstruire l’ordre dans lequel le participant a entré les tonalités DTMF.

Événement ContinuousDtmfRecognitionFailed

Exemple montrant comment vous pouvez gérer l’échec de la détection de tonalité DTMF.

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

Événement ContinuousDtmfRecogntionStopped

Exemple montrant comment gérer l’arrêt de la reconnaissance DTMF continue, peut être dû au fait que votre application a appelé l’événement StopContinuousDtmfRecognitionAsync ou que l’appel s’est terminé.

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

Hold

L’action de mise en attente permet aux développeurs de suspendre temporairement une conversation entre un participant et un système ou un agent. Cela peut être utile dans les scénarios où le participant doit être redirigé vers un autre agent ou service ou lorsque l’agent doit consulter un superviseur en arrière-plan avant de poursuivre la conversation. Pendant ce temps, vous pouvez lire un audio au participant qui est en attente.

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

Libérer

L’action de récupération d’appel permet aux développeurs de reprendre une conversation entre un participant et un système ou un agent qui a été précédemment mise en attente. Lorsque le participant est repris, il sera en mesure d’entendre à nouveau le système ou l’agent.

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

Diffusion audio (préversion publique)

La diffusion audio vous permet de vous abonner à des flux audio en temps réel à partir d’un appel en cours. Pour obtenir des instructions plus détaillées sur la prise en main de la diffusion audio et des informations sur les événements de rappel de diffusion audio, consultez cette page.

Transcription en temps réel (préversion publique)

La transcription en temps réel vous permet d’accéder aux transcriptions en direct pour l’audio d’un appel en cours. Pour obtenir des conseils plus détaillés sur la prise en main de la transcription en temps réel et des informations sur les événements de rappel de transcription en temps réel, consultez cette page.

Tableau de compatibilité des actions médias

Le tableau suivant illustre les opérations multimédias autorisées à s’exécuter/file d’attente si une opération précédente est toujours en cours d’exécution/mise en file d’attente.

Opération existante	Jambe d’appel	Autorisé	Disallowed
PlayToAll	Principal	PlayToAll, Recognize(Non-Group Call), PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition	Aucune
Recognize(Non-Group Call)	Principal	PlayToAll, Recognize(Non-Group Call), PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition	Aucune
PlayTo	Sub	PlayToAll, Recognize(Appel non de groupe)	PlayTo, Recognize(Appel de groupe), SendDTMF, StartContinuousDtmfRecognition
Recognize(Appel de groupe)	Sub	PlayToAll, Recognize(Appel non de groupe)	PlayTo, Recognize(Appel de groupe), SendDTMF, StartContinuousDtmfRecognition
SendDTMF	Sub	PlayToAll, Recognize(Appel non de groupe)	PlayTo, Recognize(Appel de groupe), SendDTMF, StartContinuousDtmfRecognition
StartContinuousDtmfRecognition	Sub	PlayToAll, Recognize(Non-Group Call), PlayTo, Recognize(Group Call), SendDTMF, StartContinuousDtmfRecognition	Aucune

Partager via