De ACS-aanroepende SDK gebruiken om contextuele UUI-gegevens (User-to-User Information) door te geven tussen aanroepen
In dit artikel leert u hoe u aangepaste contextuele informatie doorgeeft bij het routeren van oproepen met Azure Communication Services-aanroep-SDK's. Met deze mogelijkheid kunnen gebruikers metagegevens doorgeven over de aanroep, aanroepen of andere informatie die relevant is voor hun toepassing of bedrijfslogica.
De WebJS SDK van Azure Communication Services (ACS) biedt ontwikkelaars aangepaste contextuele gegevens (opgenomen als koptekst voor het aanroepende object) bij het doorsturen en doorsturen van oproepen van de ene persoon naar de andere. Deze informatie, ook wel UUI-gegevens (User-to-User Information) of UUI-gegevens (Call Control Control) genoemd, is een klein stukje gegevens dat wordt ingevoegd door een toepassing die de aanroep initieert. De UUI-gegevens zijn ondoorzichtig voor eindgebruikers die bellen.
Contextuele informatie die wordt ondersteund, omvat zowel aangepaste freeform-headers als de standaard UUI SIP-header (User-to-User Information). Ook wanneer u een inkomende oproep ontvangt, worden de aangepaste headers en UUI opgenomen in de incomingCall-nettolading.
Alle aangepaste contextgegevens zijn ondoorzichtig voor het aanroepen van SDK- of SIP-protocollen en de inhoud ervan is niet gerelateerd aan alle basisfuncties.
Ontwikkelaars kunnen deze context doorgeven met behulp van aangepaste headers, die bestaan uit optionele sleutel-waardeparen. Deze paren kunnen worden opgenomen in de acties AddParticipant of Transfer binnen de aanroepende SDK. Zodra deze is toegevoegd, kunt u de nettolading van de gegevens lezen terwijl de aanroep tussen eindpunten wordt verplaatst. Door deze metagegevens efficiënt op te zoeken en deze te koppelen aan de aanroep, kunnen ontwikkelaars externe databasezoekacties voorkomen en de inhoudsgegevens direct beschikbaar hebben in het aanroepobject.
De aangepaste oproepcontext kan worden verzonden naar SIP-eindpunten met behulp van het SIP-protocol. Deze overdracht omvat zowel de aangepaste headers als de standaard UUI SIP-header (User-to-User Information). Wanneer een inkomende oproep wordt gerouteerd vanuit uw telefonienetwerk, worden de gegevens van uw Session Border Controller (SBC) in de aangepaste headers en UUI ook opgenomen in de nettolading van de IncomingCall-gebeurtenis.
Het is belangrijk te weten dat alle aangepaste contextgegevens transparant blijven voor de aanroepende SDK en niet gerelateerd zijn aan een van de fundamentele functies van de SDK wanneer ze worden gebruikt in SIP-protocollen. Hier volgt een zelfstudie om u te helpen bij het toevoegen van aangepaste contextheaders wanneer u de WebJS SDK gebruikt.
Belangrijk
Als u de mogelijkheid wilt gebruiken om UUI-gegevens (User-to-User Information) door te geven met behulp van de aanroepende SDK, moet u de aanroepende WebJS SDK GA of openbare preview-versie 1.29.1 of hoger gebruiken.
Technische parameters
De aanroepende SDK ondersteunt het toevoegen van maximaal 5 aangepaste SIP-headers en 1000 aangepaste VOIP-headers. Daarnaast kunnen ontwikkelaars een speciale user-to-user-header opnemen als onderdeel van de SIP-headerslijst.
De maximale lengte van een SIP-headersleutel is 64 tekens, inclusief het X-MS-Custom-voorvoegsel. Houd er rekening mee dat wanneer de SIP-header wordt toegevoegd, de aanroepende SDK automatisch het voorvoegsel 'X-MS-Custom-' toevoegt (die kan worden weergegeven als u de SIP-header inspecteert met pakketcontrole).
De SIP-headersleutel kan bestaan uit alfanumerieke tekens en enkele geselecteerde symbolen, waaronder ., , !%, *, _, , +, ~. - De maximale lengte van de SIP-headerwaarde is 256 tekens. Dezelfde beperkingen gelden voor het configureren van de SIP-headers op uw SBC. De SIP-headerwaarde kan bestaan uit alfanumerieke tekens en enkele geselecteerde symbolen, waaronder =, , ;., !, , %, , _*, , , +, , ~. -
De maximale lengte van een VOIP-headersleutel is 64 tekens. De maximale lengte van VOIP-headerwaarde is 1024 tekens.
Wanneer u deze aangepaste headers toevoegt als ontwikkelaar, kunt u ervoor kiezen om alleen SIP-headers toe te voegen, kunnen alleen VoIP-headers of beide worden opgenomen.
Notitie
Op dit moment wordt het toevoegen van aangepaste headers voor gebruikersgegevens alleen ondersteund bij het initiëren van een 1:1-aanroep. Het doorgeven van headers van gebruikers-naar-gebruikersgegevens in groepsaanroepen wordt momenteel niet ondersteund. Als u dit wilt omzeilen na het starten van de oproep van 1:1, kunt u extra deelnemers opnemen terwijl u de gebruikers-naar-gebruikersgegevens in de oproepen onderhoudt.
Raadpleeg de resourcepagina van de aangepaste context-API voor meer informatie over de aangepaste contextinterface-API .
Een gesprek met UUI-gegevens (User-to-User Information) plaatsen
// 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',
},
};
});
Headers van gebruikers-naar-gebruikersgegevens lezen en parseren in een gesprek
Het callAgent exemplaar verzendt een incomingCall gebeurtenis wanneer de aangemelde identiteit een inkomende oproep ontvangt. Als u naar deze gebeurtenis wilt luisteren en contextuele informatie wilt extraheren, abonneert u zich met behulp van een van de volgende opties:
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`);
}
}
});