Använda ACS-anropande SDK för att skicka kontextuell användar-till-användarinformation (UUI)-data mellan anrop

  • Artikel

I den här artikeln får du lära dig hur du vidarebefordrar anpassad kontextuell information när du dirigerar anrop med Azure Communication Services Calling SDK:er. Med den här funktionen kan användare skicka metadata om anropet, anroparen eller annan information som är relevant för deras program eller affärslogik.

Azure Communication Services (ACS) WebJS SDK ger utvecklare tillgång till anpassade kontextuella data (ingår som en rubrik i det anropande objektet) när de dirigerar och dirigerar anrop från en person till en annan. Den här informationen, även kallad UUI-data (User-to-User Information) eller UUI-data för anropskontroll, är en liten del av data som infogas av ett program som initierar anropet. UUI-data är ogenomskinliga för slutanvändare som ringer ett anrop.

Sammanhangsbaserad information som stöds omfattar både anpassade sidhuvuden för frihandsformat och SIP-huvud (användar-till-användare) som standard. När du får ett inkommande samtal inkluderas även anpassade rubriker och UUI i inkommandeCall-nyttolasten.

Alla anpassade kontextdata är ogenomskinliga för anropande SDK- eller SIP-protokoll och dess innehåll är inte relaterat till några grundläggande funktioner.

Utvecklare kan skicka den här kontexten med hjälp av anpassade rubriker, som består av valfria nyckel/värde-par. Dessa par kan ingå i åtgärderna "AddParticipant" eller "Transfer" i den anropande SDK:t. När du har lagt till den kan du läsa datanyttolasten när anropet flyttas mellan slutpunkterna. Genom att effektivt leta upp dessa metadata och associera dem med anropet kan utvecklare undvika externa databassökningar och ha innehållsinformationen tillgänglig i anropsobjektet.

Den anpassade samtalskontexten kan överföras till SIP-slutpunkter med hjälp av SIP-protokollet. Den här överföringen innehåller både de anpassade rubrikerna och UUI-huvud (User-to-User Information). När ett inkommande samtal dirigeras från telefoninätverket inkluderas även data från sessionsgränskontrollanten (SBC) i de anpassade rubrikerna och UUI i incomingcall-händelsenyttolasten.

Det är viktigt att observera att alla anpassade kontextdata förblir transparenta för det anropande SDK:t och inte är relaterade till någon av SDK:ernas grundläggande funktioner när de används i SIP-protokoll. Här är en självstudiekurs som hjälper dig att lägga till anpassade kontextrubriker när du använder WebJS SDK.

Viktigt!

Om du vill använda möjligheten att skicka UUI-data (User-to-User Information) med hjälp av den anropande SDK:t måste du använda den anropande WebJS SDK GA eller den 1.29.1 offentliga förhandsversionen eller senare.

Tekniska parametrar

Anropande SDK har stöd för att lägga till upp till 5 anpassade SIP-huvuden och 1 000 anpassade VOIP-huvuden. Dessutom kan utvecklare inkludera en dedikerad användar-till-användare-rubrik som en del av SIP-rubriklistan.

Den maximala längden på en SIP-huvudnyckel är 64 tecken, inklusive prefixet X-MS-Custom. Observera att när SIP-huvudet läggs till lägger den anropande SDK:en automatiskt till prefixet "X-MS-Custom-" (som kan se om du inspekterar SIP-huvudet med paketkontroll).

SIP-huvudnyckeln kan bestå av alfanumeriska tecken och några markerade symboler som inkluderar ., !, %, *, _, +, ~, . - Den maximala längden på SIP-huvudvärdet är 256 tecken. Samma begränsningar gäller när du konfigurerar SIP-huvudena på din SBC. SIP-huvudvärdet kan bestå av alfanumeriska tecken och några markerade symboler som inkluderar =, ;, ., !, %, *, _, +, , ~, -.

Den maximala längden på en VOIP-huvudnyckel är 64 tecken. Den maximala längden på VOIP-rubrikvärdet är 1 024 tecken.

När du lägger till dessa anpassade rubriker som utvecklare kan du välja att endast lägga till SIP-huvuden, endast VoIP-huvuden eller båda kan inkluderas.

Kommentar

För närvarande stöds endast tillägg av anpassade rubriker för användar-till-användare-information när ett 1:1-anrop initieras. Det finns för närvarande inte stöd för att skicka rubriker för användar-till-användare-information i gruppanrop. Om du vill kringgå detta när du har startat 1:1-anropet kan du inkludera ytterligare deltagare samtidigt som du behåller användar-till-användarinformationen i anropen.

Mer information om API:et för anpassat kontextgränssnitt finns på resurssidan för API för anpassad kontext.

Ringa ett anrop med UUI-data (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',
    },
};
});

Läsa och parsa rubriker för användar-till-användare-information i ett anrop

Instansen callAgent genererar en incomingCall händelse när den inloggade identiteten tar emot ett inkommande samtal. Om du vill lyssna på den här händelsen och extrahera sammanhangsberoende information prenumererar du med något av följande alternativ:

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`);
        }
    }
});

Nästa steg