Partager via

Comment transmettre des données contextuelles entre les appels

  • Article

Call Automation permet aux développeurs de transmettre des informations contextuelles personnalisées lors du routage des appels. Les développeurs peuvent transmettre des métadonnées sur l’appel, l’appelé ou toute autre information pertinente pour leur application ou leur logique métier. Cela permet aux entreprises de gérer et de router les appels entre les réseaux sans avoir à se soucier de perdre le contexte.

Le contexte de passage est pris en charge en spécifiant des en-têtes personnalisés. Il s’agit d’une liste facultative de paires clé-valeur qui peuvent être incluses dans le cadre d’actions AddParticipant ou Transfer. Le contexte peut être récupéré ultérieurement dans le cadre de la charge utile de l’événement IncomingCall.

Le contexte d’appel personnalisé est également transféré au protocole SIP, ce qui inclut à la fois les en-têtes personnalisés de forme libre ainsi que l’en-tête SIP UUI (d’utilisateur à utilisateur) standard. Lors du routage d’un appel entrant à partir de votre réseau de téléphonie, le jeu de données de votre SBC dans les en-têtes personnalisés et UUI est également inclus dans la charge utile de l’événement IncomingCall.

Toutes les données de contexte personnalisées sont opaques pour Call Automation ou les protocoles SIP et leur contenu n’est lié à aucune des fonctions de base.

Vous trouverez ci-dessous des exemples sur la prise en main des en-têtes de contexte personnalisés dans Call Automation.

Comme condition préalable, nous vous recommandons de lire ces articles 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.

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.

Paramètres techniques

Call Automation prend en charge jusqu’à 5 en-têtes SIP personnalisés et 1 000 en-têtes VOIP personnalisés. En outre, les développeurs peuvent inclure un en-tête utilisateur à utilisateur dédié dans le cadre de la liste des en-têtes SIP.

La clé d’en-tête SIP personnalisée doit commencer par un préfixe ‘X-MS-Custom-’ obligatoire. La longueur maximale d’une clé d’en-tête SIP est de 64 caractères, y compris le préfixe X-MS-Custom. La clé d’en-tête SIP peut être constituée de caractères alphanumériques et de quelques symboles sélectionnés, notamment ., !, %, *, _, +, ~, -. La longueur maximale de la valeur d’en-tête SIP est de 256 caractères. Les mêmes limitations s’appliquent lors de la configuration des en-têtes SIP sur votre SBC. La valeur d’en-tête SIP peut être constituée de caractères alphanumériques et de quelques symboles sélectionnés, notamment =, ;, ., !, %, *, _, +, ~, -.

La longueur maximale d’une clé d’en-tête VOIP est de 64 caractères. Ces en-têtes peuvent être envoyés sans préfixe ‘x-MS-Custom’. La longueur maximale de la valeur d’en-tête VOIP est de 1024 caractères.

Ajout d’un contexte personnalisé lors de l’invitation d’un participant

// Invite a communication services user and include one VOIP header
var addThisPerson = new CallInvite(new CommunicationUserIdentifier("<user_id>"));
addThisPerson.CustomCallingContext.AddVoip("myHeader", "myValue");
AddParticipantsResult result = await callConnection.AddParticipantAsync(addThisPerson);
// Invite a PSTN user and set UUI and custom SIP headers
var callerIdNumber = new PhoneNumberIdentifier("+16044561234"); 
var addThisPerson = new CallInvite(new PhoneNumberIdentifier("+16041234567"), callerIdNumber);

// Set custom UUI header. This key is sent on SIP protocol as User-to-User
addThisPerson.CustomCallingContext.AddSipUui("value");

// This provided key will be automatically prefixed with X-MS-Custom on SIP protocol, such as 'X-MS-Custom-{key}'
addThisPerson.CustomCallingContext.AddSipX("header1", "customSipHeaderValue1");
AddParticipantsResult result = await callConnection.AddParticipantAsync(addThisPerson);

Ajout d’un contexte personnalisé pendant le transfert d’appel

//Transfer to communication services user and include one VOIP header
var transferDestination = new CommunicationUserIdentifier("<user_id>"); 
var transferOption = new TransferToParticipantOptions(transferDestination);   
var transferOption = new TransferToParticipantOptions(transferDestination) {
    OperationContext = "<Your_context>",
    OperationCallbackUri = new Uri("<uri_endpoint>") // Sending event to a non-default endpoint.
};
transferOption.CustomCallingContext.AddVoip("customVoipHeader1", "customVoipHeaderValue1");
TransferCallToParticipantResult result = await callConnection.TransferCallToParticipantAsync(transferOption);

//Transfer a PSTN call to phone number and set UUI and custom SIP headers
var transferDestination = new PhoneNumberIdentifier("<target_phoneNumber>");
var transferOption = new TransferToParticipantOptions(transferDestination);
transferOption.CustomCallingContext.AddSipUui("uuivalue");
transferOption.CustomCallingContext.AddSipX("header1", "headerValue");
TransferCallToParticipantResult result = await callConnection.TransferCallToParticipantAsync(transferOption)

Lecture du contexte personnalisé à partir d’un événement d’appel entrant

AcsIncomingCallEventData incomingEvent = <incoming call event from Event Grid>;
// Retrieve incoming call custom context
AcsIncomingCallCustomContext callCustomContext = incomingEvent.CustomContext;

// Inspect dictionary with key/value pairs
var voipHeaders = callCustomContext.VoipHeaders;
var sipHeaders = callCustomContext.SipHeaders;

// Get SIP UUI header value
var userToUser = sipHeaders["user-To-User"]

// Proceed to answer or reject call as usual

Ressources supplémentaires