Uso dell'SDK di chiamata ACS per passare dati contestuali User-to-User Information (UUI) tra le chiamate
Questo articolo illustra come passare informazioni contestuali personalizzate durante il routing delle chiamate con gli SDK per chiamate di Servizi di comunicazione di Azure. Questa funzionalità consente agli utenti di passare metadati relativi alla chiamata, al destinatario della chiamata o a qualsiasi altra informazione rilevante per l'applicazione o la logica di business.
L'SDK WebJS di Servizi di comunicazione di Azure (ACS) offre agli sviluppatori la possibilità di includere dati contestuali personalizzati, inseriti come intestazione nell'oggetto di chiamata, durante l'indirizzamento e il routing delle chiamate da una persona all'altra. Queste informazioni, note anche come dati UUI (User-to-User Information) o dati UUI di controllo della chiamata, costituiscono una piccola parte di dati inseriti dall'applicazione che avvia la chiamata. I dati UUI sono opachi per gli utenti finali che effettuano la chiamata.
Le informazioni contestuali supportate includono sia le intestazioni di figure a mano libera personalizzate che l'intestazione SIP User-to-User Information (UUI) standard. Inoltre, quando si riceve una chiamata in arrivo, le intestazioni personalizzate e i dati UUI sono inclusi nel payload di incomingCall.
Tutti i dati contestuali personalizzati sono opachi per l'SDK di chiamata o i protocolli SIP e il relativo contenuto non è correlato a nessuna funzione di base.
Gli sviluppatori possono passare questo contesto usando intestazioni personalizzate, costituite da coppie chiave-valore facoltative. Queste coppie possono essere incluse nelle azioni ''AddParticipant'' o ''Transfer'' all'interno dell'SDK di chiamata. Una volta aggiunte, è possibile leggere il payload dei dati mentre la chiamata si sposta tra gli endpoint. Tramite la ricerca efficiente di questi metadati e la relativa associazione alla chiamata, gli sviluppatori possono evitare le ricerche nel database esterno e disporre delle informazioni sul contenuto all'interno dell'oggetto di chiamata.
Il contesto di chiamata personalizzato può essere trasmesso agli endpoint SIP usando il protocollo SIP. Questa trasmissione include sia le intestazioni personalizzate che l'intestazione SIP User-to-User Information (UUI) standard. Quando una chiamata in arrivo viene instradata dalla rete di telefonia, i dati del Session Border Controller (SBC) nelle intestazioni personalizzate e nell'UUI vengono inclusi anche nel payload dell'evento IncomingCall.
È importante notare che tutti i dati contestuali personalizzati rimangono trasparenti all'SDK di chiamata e non sono correlati a nessuna delle funzioni fondamentali dell'SDK durante l'utilizzo nei protocolli SIP. L'esercitazione seguente contiene informazioni utili relative all'aggiunta di intestazioni contestuali personalizzate durante l'utilizzo dell'SDK WebJS.
Importante
Per sfruttare la possibilità di passare i dati UUI (User-to-User Information) tramite l'SDK di chiamata, è necessario usare la versione disponibile a livello generale o di anteprima pubblica 1.29.1 dell'SDK di chiamata WebJS o versione successiva.
Parametri tecnici
L'SDK di chiamata supporta l'aggiunta di un massimo di 5 intestazioni SIP personalizzate e di 1000 intestazioni VOIP personalizzate. Inoltre, gli sviluppatori possono includere un'intestazione User-To-User dedicata come parte dell'elenco di intestazioni SIP.
La lunghezza massima di una chiave di intestazione SIP è di 64 caratteri, incluso il prefisso X-MS-Custom. Si noti che quando viene aggiunta l'intestazione SIP, l'SDK di chiamata aggiungerà automaticamente il prefisso "X-MS-Custom-", che può essere visualizzato se si esamina l'intestazione SIP con il controllo pacchetti.
La chiave di intestazione SIP può essere costituita da caratteri alfanumerici e da alcuni simboli selezionati, tra cui ., !, %, *, _, +, ~, -. La lunghezza massima del valore dell'intestazione SIP è di 256 caratteri. Le stesse limitazioni si applicano quando si configurano le intestazioni SIP nell’SBC. Il valore dell’intestazione SIP può essere costituito da caratteri alfanumerici e da alcuni simboli selezionati, tra cui =, ;, ., !, %, *, _, +, ~, -.
La lunghezza massima di una chiave di intestazione VOIP è di 64 caratteri. La lunghezza massima del valore dell'intestazione VOIP è di 1024 caratteri.
Quando si aggiungono queste intestazioni personalizzate, in qualità di sviluppatore è possibile scegliere di aggiungere solo intestazioni SIP, solo intestazioni VoIP o di includerle entrambe.
Nota
Attualmente, l'aggiunta di intestazioni User-to-User Information personalizzate è supportata solo quando si avvia una chiamata 1:1. Il passaggio di intestazioni User-to-User Information nelle chiamate di gruppo non è attualmente supportato. Per risolvere questo problema, dopo aver avviato la chiamata 1:1, è possibile includere altri partecipanti pur mantenendo i dati User-to-User Information all'interno delle chiamate.
Per informazioni dettagliate sull'API dell'interfaccia del contesto personalizzata, vedere la pagina risorsa API del contesto personalizzato.
Effettuare una chiamata con dati 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',
},
};
});
Leggere e analizzare le intestazioni User-to-User Information in una chiamata
L'istanza callAgent genera un evento incomingCall quando l'identità registrata riceve una chiamata in ingresso. Per ascoltare questo evento ed estrarre informazioni contestuali, abbonarsi scegliendo una delle opzioni seguenti:
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`);
}
}
});