Przekazywanie danych kontekstowych informacji o użytkowniku do użytkownika (UUI) między wywołaniami za pomocą zestawu SDK wywołującego usługę ACS
Z tego artykułu dowiesz się, jak przekazywać niestandardowe informacje kontekstowe podczas routingu wywołań za pomocą zestawów SDK wywołujących usługi Azure Communication Services. Ta funkcja umożliwia użytkownikom przekazywanie metadanych dotyczących wywołania, wywoływania lub innych informacji istotnych dla ich aplikacji lub logiki biznesowej.
Zestaw SDK usług Azure Communication Services (ACS) WebJS udostępnia deweloperom dołączanie niestandardowych danych kontekstowych (dołączonych jako nagłówek do obiektu wywołującego) podczas kierowania i routingu wywołań od jednej osoby do innej. Te informacje, nazywane również danymi interfejsu użytkownika (User-to-User Information) lub danymi interfejsu użytkownika sterowania wywołaniami, są małym elementem danych wstawionym przez aplikację inicjującą wywołanie. Dane interfejsu użytkownika są nieprzezroczyste dla użytkowników końcowych wykonujących wywołanie.
Obsługiwane informacje kontekstowe obejmują zarówno nagłówki niestandardowe freeform, jak i standardowy nagłówek SIP user-to-User Information (UUI). Ponadto w przypadku odbierania wywołania przychodzącego nagłówki niestandardowe i interfejs użytkownika są uwzględniane w ładunku przychodzącymCall.
Wszystkie niestandardowe dane kontekstowe są nieprzezroczyste do wywoływania zestawu SDK lub protokołów SIP, a jego zawartość nie jest powiązana z żadnymi podstawowymi funkcjami.
Deweloperzy mogą przekazywać ten kontekst przy użyciu nagłówków niestandardowych, które składają się z opcjonalnych par klucz-wartość. Te pary można uwzględnić w akcjach "AddParticipant" lub "Transfer" w wywołującym zestawie SDK. Po dodaniu można odczytać ładunek danych, gdy wywołanie przechodzi między punktami końcowymi. Efektywnie wyszukując te metadane i kojarząc je z wywołaniem, deweloperzy mogą unikać wyszukiwania zewnętrznej bazy danych i łatwo udostępniać informacje o zawartości w obiekcie wywołania.
Niestandardowy kontekst wywołania można przesyłać do punktów końcowych SIP przy użyciu protokołu SIP. Ta transmisja obejmuje zarówno nagłówki niestandardowe, jak i standardowy nagłówek SIP User-to-User Information (UUI). Gdy połączenie przychodzące jest kierowane z sieci telefonii, dane z kontrolera granic sesji (SBC) w nagłówkach niestandardowych i interfejsie użytkownika są również uwzględniane w ładunku zdarzenia IncomingCall.
Należy pamiętać, że wszystkie dane kontekstowe niestandardowe pozostają niewidoczne dla zestawu SDK wywołującego i nie są powiązane z żadnymi podstawowymi funkcjami zestawu SDK w przypadku użycia w protokołach SIP. Oto samouczek ułatwiający dodawanie niestandardowych nagłówków kontekstu podczas korzystania z zestawu WebJS SDK.
Ważne
Aby użyć możliwości przekazywania danych informacji o użytkowniku do użytkownika (UUI) przy użyciu zestawu SDK wywołującego, należy użyć wywołującego zestawu SDK usługi WebJS ogólnie dostępnej lub publicznej wersji 1.29.1 zapoznawczej lub nowszej.
Parametry techniczne
Zestaw SDK wywołujący obsługuje dodawanie do 5 niestandardowych nagłówków SIP i 1000 niestandardowych nagłówków VOIP. Ponadto deweloperzy mogą dołączać dedykowany nagłówek User-To-User jako część listy nagłówków SIP.
Maksymalna długość klucza nagłówka SIP wynosi 64 znaki, w tym prefiks X-MS-Custom. Należy pamiętać, że po dodaniu nagłówka SIP zestaw SDK wywołania automatycznie doda prefiks "X-MS-Custom-" (który może być widoczny w przypadku inspekcji nagłówka SIP za pomocą inspektora pakietów).
Klucz nagłówka SIP może składać się z znaków alfanumerycznych i kilku wybranych symboli, takich jak ., , !, +*%_~. - Maksymalna długość wartości nagłówka SIP wynosi 256 znaków. Te same ograniczenia mają zastosowanie podczas konfigurowania nagłówków SIP na SBC. Wartość nagłówka SIP może składać się z znaków alfanumerycznych i kilku wybranych symboli, takich jak =, , ;, *%+!_., . ~-
Maksymalna długość klucza nagłówka VOIP wynosi 64 znaki. Maksymalna długość wartości nagłówka VOIP to 1024 znaki.
Podczas dodawania tych niestandardowych nagłówków jako dewelopera możesz dodać tylko nagłówki SIP, tylko nagłówki VoIP lub oba te nagłówki można uwzględnić.
Uwaga
Obecnie dodawanie niestandardowych nagłówków informacje o użytkowniku do użytkownika jest obsługiwane tylko podczas inicjowania wywołania 1:1. Przekazywanie nagłówków Informacje o użytkowniku do użytkownika w wywołaniach grup nie jest obecnie obsługiwane. Aby obejść ten proces po rozpoczęciu połączenia 1:1, możesz dołączyć dodatkowych uczestników przy zachowaniu informacji użytkownika do użytkownika w ramach wywołań.
Aby uzyskać szczegółowe informacje na temat niestandardowego interfejsu API kontekstu, zapoznaj się ze stroną zasobu niestandardowego interfejsu API kontekstu.
Umieszczanie wywołania przy użyciu danych interfejsu użytkownika (UUI)
// 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',
},
};
});
Odczytywanie i analizowanie nagłówków informacji o użytkowniku do użytkownika w wywołaniu
Wystąpienie callAgent emituje incomingCall zdarzenie, gdy tożsamość zalogowana odbiera połączenie przychodzące. Aby nasłuchiwać tego zdarzenia i wyodrębnić informacje kontekstowe, subskrybuj przy użyciu jednej z następujących opcji:
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`);
}
}
});