Použití sady SDK volající služby ACS k předání kontextových dat user-to-user information (UUI) mezi voláními
V tomto článku se dozvíte, jak předat vlastní kontextové informace při směrování volání pomocí sad SDK pro volání azure Communication Services. Tato funkce umožňuje uživatelům předávat metadata o volání, volané nebo jakékoli jiné informace, které jsou relevantní pro svou aplikaci nebo obchodní logiku.
Sada Azure Communication Services (ACS) WebJS SDK poskytuje vývojářům, kteří při směrování a směrování volání z jedné osoby do jiného zahrnou vlastní kontextová data (zahrnutá jako hlavička volajícího objektu). Tyto informace, označované také jako data user-to-user information (UUI) nebo data řízení volání UUI, jsou malá část dat vložená aplikací, která volání iniciuje. Data UUI jsou pro koncové uživatele volání neprůhlásná.
Podporované kontextové informace zahrnují vlastní hlavičky volného formátu i standardní hlavičku SIP (User-to-User Information). Při příjmu příchozího volání se vlastní hlavičky a UUI také zahrnou do datové části incomingCall.
Všechna vlastní kontextová data jsou neprůzná pro volání protokolů SDK nebo SIP a jejich obsah nesouvisí s žádnými základními funkcemi.
Vývojáři můžou tento kontext předat pomocí vlastních hlaviček, které se skládají z volitelných párů klíč-hodnota. Tyto páry lze zahrnout do akcí AddParticipant nebo Transfer v rámci volající sady SDK. Po přidání můžete datovou část číst, když se volání pohybuje mezi koncovými body. Díky efektivnímu vyhledání těchto metadat a jeho přidružení k volání můžou vývojáři zabránit vyhledávání externích databází a mít snadno dostupné informace o obsahu v rámci objektu volání.
Kontext vlastního volání lze přenést do koncových bodů SIP pomocí protokolu SIP. Tento přenos zahrnuje jak vlastní hlavičky, tak standardní hlavičku SIP (User-to-User Information). Pokud je příchozí volání směrováno z telefonní sítě, data z vašeho řadiče pro ohraničení relace (SBC) ve vlastních hlavičkách a UUI jsou také zahrnuta v datové části příchozího volání.
Je důležité si uvědomit, že všechna vlastní kontextová data zůstávají pro volající sadu SDK transparentní a nesouvisí se základními funkcemi sady SDK při použití v protokolech SIP. Tady je kurz, který vám pomůže při přidávání vlastních hlaviček kontextu při použití sady WebJS SDK.
Důležité
Pokud chcete použít možnost předávat data user-to-user information (UUI) pomocí volající sady SDK, musíte použít volání sady WebJS SDK GA nebo verze Public Preview 1.29.1 nebo novější.
Technické parametry
Volající sada SDK podporuje přidání až 5 vlastních hlaviček SIP a 1000 vlastních hlaviček VOIP. Vývojáři mohou navíc jako součást seznamu hlaviček SIP zahrnout vyhrazenou hlavičku User-To-User.
Maximální délka klíče hlavičky SIP je 64 znaků včetně předpony X-MS-Custom. Vzhledem k tomu, že když je hlavička SIP přidána volající sdk, automaticky přidá předponu X-MS-Custom-(což se může zobrazit, pokud zkontrolujete hlavičku SIP pomocí inspektoru paketů).
Klíč záhlaví SIP se může skládat z alfanumerických znaků a několika vybraných symbolů, mezi které patří , , , , _*, +, ~. -%!. Maximální délka hodnoty hlavičky SIP je 256 znaků. Stejná omezení platí při konfiguraci hlaviček SIP ve vašem SBC. Hodnota záhlaví SIP se může skládat z alfanumerických znaků a několika vybraných symbolů, mezi které patří , , , , +. ~-!_%*.;=
Maximální délka klíče hlavičky VOIP je 64 znaků. Maximální délka hodnoty záhlaví VOIP je 1024 znaků.
Při přidávání těchto vlastních hlaviček jako vývojáři se můžete rozhodnout přidat pouze hlavičky SIP, můžete zahrnout jenom hlavičky VoIP nebo obojí.
Poznámka:
V současné době je přidání vlastních hlaviček User-to-User Information podporováno pouze při zahájení volání 1:1. Předávání hlaviček User-to-User Information ve volání skupiny se v současné době nepodporuje. Pokud chcete tento problém obejít po zahájení hovoru ve 1:1, můžete zahrnout další účastníky při zachování informací o uživatel-uživatel v rámci volání.
Podrobnosti o rozhraní API vlastního kontextového rozhraní najdete na stránce prostředku vlastního kontextového rozhraní API.
Volání s daty user-to-user information (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',
},
};
});
Čtení a analýza hlaviček User-to-User Information ve volání
Instance callAgent vygeneruje incomingCall událost, když přihlášená identita přijme příchozí hovor. Pokud chcete naslouchat této události a extrahovat kontextové informace, přihlaste se k odběru pomocí jedné z těchto možností:
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`);
}
}
});