Utilisation du SDK d’appel ACS pour passer des données UUI (User-to-User Information) contextuelles entre les appels
Dans cet article, vous allez apprendre à transmettre des informations contextuelles personnalisées lors du routage des appels avec des kits SDK Azure Communication Services Calling. Cette fonctionnalité permet aux utilisateurs de transmettre des métadonnées sur l’appel, l’appelé ou toute autre information pertinente pour leur application ou leur logique métier.
Le SDK WebJS Azure Communication Services (ACS) permet aux développeurs d’inclure des données contextuelles personnalisées (en tant qu’en-tête sur l’objet de l’appel) lorsque les appels sont dirigés et routés d’une personne à une autre. Ces informations, également appelées données UUI (User-to-User Information) ou données UUI de contrôle d’appel, constituent une petite partie des données insérées par une application qui démarre l’appel. Les données UUI sont opaques pour les utilisateurs finaux qui effectuent un appel.
Les informations contextuelles prises en charge incluent à la fois des en-têtes personnalisés de forme libre et l’en-tête SIP UUI (User-to-User Information) standard. De plus, lorsque vous recevez un appel entrant, les en-têtes personnalisés et les UUI sont inclus dans la charge utile incomingCall.
Toutes les données de contexte personnalisées sont opaques pour le SDK Calling ou les protocoles SIP et leur contenu n’est lié à aucune des fonctions de base.
Les développeurs peuvent passer ce contexte à l’aide d’en-têtes personnalisés, qui se composent de paires clé-valeur facultatives. Ces paires peuvent être incluses dans les actions « AddParticipant » ou « Transfer » dans le SDK d’appel. Une fois qu’elles ont été ajoutées, vous pouvez lire la charge utile des données à mesure que l’appel se déplace d’un point de terminaison à un autre. En recherchant efficacement ces métadonnées et en les associant à l’appel, les développeurs peuvent éviter les recherches de bases de données externes et disposer rapidement des informations de contenu dans l’objet de l’appel.
Le contexte d’appel personnalisé peut être transmis aux points de terminaison SIP à l’aide du protocole SIP. Cette transmission inclut à la fois les en-têtes personnalisés et l’en-tête SIP UUI (User-to-User Information) standard. Lorsqu’un appel entrant est routé à partir de votre réseau de téléphonie, les données de votre SBC (Session Border Controller) dans les en-têtes personnalisés et les UUI sont également incluses dans la charge utile de l’événement IncomingCall.
Il est important de noter que toutes les données de contexte personnalisées restent transparentes pour le SDK d’appel et qu’elles ne sont liées à aucune des fonctions fondamentales du SDK lorsqu’elles sont utilisées dans les protocoles SIP. Voici un tutoriel qui vous aide à ajouter des en-têtes de contexte personnalisés lorsque vous utilisez le SDK WebJS.
Important
Pour utiliser la capacité à transmettre les données UUI (User-to-User Information) à l’aide du SDK d’appel, vous devez utiliser la version GA ou la préversion publique 1.29.1 ou ultérieure du SDK WebJS d’appel.
Paramètres techniques
Le SDK d’appel permet d’ajouter 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 longueur maximale d’une clé d’en-tête SIP est de 64 caractères, y compris le préfixe X-MS-Custom. Notez que lorsque l’en-tête SIP est ajouté, le SDK d’appel ajoute automatiquement le préfixe ‘X-MS-Custom-’ (que vous pouvez voir si vous inspectez l’en-tête SIP avec l’inspecteur de paquets).
La clé d’en-tête SIP peut être constituée de caractères alphanumériques et d’une sélection de quelques symboles, 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 d’une sélection de quelques symboles, notamment =, ;, ., !, %, *, _, +, ~, -.
La longueur maximale d’une clé d’en-tête VOIP est de 64 caractères. La longueur maximale de la valeur d’en-tête VOIP est de 1024 caractères.
Lorsque vous ajoutez ces en-têtes personnalisés, en tant que développeur, vous pouvez choisir d’ajouter uniquement des en-têtes SIP, uniquement des en-têtes VoIP, ou les deux.
Remarque
Actuellement, l’ajout d’en-têtes UUI (User-to-User Information) personnalisés est uniquement pris en charge lors du démarrage d’un appel 1 à 1. Actuellement, la transmission d’en-têtes UUI (User-to-User Information) dans les appels de groupe n’est pas prise en charge. Pour contourner ce problème après avoir démarré l’appel 1 à 1, vous pouvez inclure des participants supplémentaires tout en conservant les informations UUI dans les appels.
Pour plus d’informations sur l’API d’interface de contexte personnalisé, consultez la page Ressource d’API de contexte personnalisé.
Placer un appel avec les données UUI (User-to-User Information)
// Setting custom context UUI Headers
const callOptions = {
customContext: {
voipHeaders: [
{key: 'voip-key-1', value: 'voip-value-1'},
{key: 'voip-key-2', value: 'voip-value-2'}
],
sipHeaders: [
{key: 'sip-key-1', value: 'sip-value-1'},
{key: 'sip-key-2', value: 'sip-value-2'}
],
userToUser: 'userToUserHeader',
},
};
});
Lire et analyser les en-têtes UUI (User-to-User Information) dans un appel
L’instance de callAgent émet un événement incomingCall quand l’identité connectée reçoit un appel entrant. Pour écouter cet événement et extraire des informations contextuelles, abonnez-vous en utilisant l’une de ces options :
let info = '';
callAgent.on("incomingCall", (args) => {
const incomingCall = args.incomingCall;
if (incomingCall.customContext) {
if (incomingCall.customContext.userToUser) {
info += `userToUser: '${incomingCall.customContext.userToUser}'\n`;
}
if (incomingCall.customContext.sipHeaders) {
incomingCall.customContext.sipHeaders.forEach(header => info += `sip: ${header.key}: '${header.value}'\n`);
}
if (incomingCall.customContext.voipHeaders) {
incomingCall.customContext.voipHeaders.forEach(header => info += `voip: ${header.key}: '${header.value}'\n`);
}
}
});