ACS 호출 SDK를 사용하여 호출 간에 컨텍스트 UUI(사용자 간 정보) 데이터 전달
이 문서에서는 Azure Communication Services 통화 SDK를 사용하여 호출을 라우팅할 때 사용자 지정 상황 정보를 전달하는 방법을 알아봅니다. 이 기능을 통해 사용자는 통화, 수신자 또는 애플리케이션이나 비즈니스 논리와 관련된 기타 정보에 대한 메타데이터를 전달할 수 있습니다.
ACS(Azure Communication Services) WebJS SDK는 개발자에게 한 사람에서 다른 사용자로의 호출을 지시하고 라우팅할 때 사용자 지정 컨텍스트 데이터(호출 개체의 헤더로 포함)를 포함할 수 있도록 합니다. UUI(사용자-사용자 정보) 데이터 또는 호출 제어 UUI 데이터라고도 하는 이 정보는 호출을 시작하는 애플리케이션에서 삽입한 작은 데이터 조각입니다. UUI 데이터는 최종 사용자가 전화를 걸 때 불투명합니다.
지원되는 상황별 정보에는 자유 형식 사용자 지정 헤더와 표준 UUI(사용자 간 정보) SIP 헤더가 모두 포함됩니다. 또한 인바운드 전화를 받으면 사용자 지정 헤더와 UUI가 수신 전화 페이로드에 포함됩니다.
모든 사용자 지정 컨텍스트 데이터는 통화 SDK 또는 SIP 프로토콜에 대해 불투명하며 해당 콘텐츠는 기본 함수와 관련이 없습니다.
개발자는 선택적 키-값 쌍으로 구성된 사용자 지정 헤더를 사용하여 이 컨텍스트를 전달할 수 있습니다. 이러한 쌍은 호출 SDK 내의 'AddParticipant' 또는 'Transfer' 작업에 포함될 수 있습니다. 추가된 후에는 엔드포인트 간에 호출이 이동함에 따라 데이터 페이로드를 읽을 수 있습니다. 개발자는 이 메타데이터를 효율적으로 조회하고 호출과 연결하여 외부 데이터베이스 조회를 방지하고 호출 개체 내에서 콘텐츠 정보를 쉽게 사용할 수 있도록 할 수 있습니다.
사용자 지정 호출 컨텍스트는 SIP 프로토콜을 사용하여 SIP 엔드포인트로 전송될 수 있습니다. 이 전송에는 사용자 지정 헤더와 표준 UUI(사용자-사용자 정보) SIP 헤더가 모두 포함됩니다. 전화 통신 네트워크에서 인바운드 호출이 라우팅되면 사용자 지정 헤더 및 UUI의 SBC(Session Border Controller)의 데이터도 IncomingCall 이벤트 페이로드에 포함됩니다.
모든 사용자 지정 컨텍스트 데이터는 호출 SDK에 투명하게 유지되며 SIP 프로토콜에서 사용되는 경우 SDK의 기본 함수와 관련이 없습니다. WebJS SDK를 사용할 때 사용자 지정 컨텍스트 헤더를 추가하는 데 도움이 되는 자습서는 다음과 같습니다.
Important
호출 SDK를 사용하여 UUI(사용자-사용자 정보) 데이터를 전달하는 기능을 사용하려면 호출하는 WebJS SDK GA 또는 공개 미리 보기 버전 1.29.1 이상을 사용해야 합니다.
기술 매개 변수
호출 SDK는 최대 5개의 사용자 지정 SIP 헤더와 1000개의 사용자 지정 VOIP 헤더를 추가할 수 있도록 지원합니다. 또한 개발자는 SIP 헤더 목록의 일부로 전용 사용자 간 헤더를 포함할 수 있습니다.
SIP 헤더 키의 최대 길이는 X-MS-Custom 접두사를 포함하여 64자입니다. SIP 헤더가 추가되면 호출 SDK는 'X-MS-Custom-' 접두사를 자동으로 추가합니다(패킷 검사기를 사용하여 SIP 헤더를 검사하는 경우 확인할 수 있음).
SIP 헤더 키는 영숫자 문자와 ., !, %, *, _, +, ~, -를 포함하여 몇 가지 선택한 기호로 구성할 수 있습니다. SIP 헤더 값의 최대 길이는 256자입니다. SBC에서 SIP 헤더를 구성할 때도 동일한 제한 사항이 적용됩니다. SIP 헤더 값은 영숫자 문자와 =, ;, ., !, %, *, _, +, ~, -를 포함하여 몇 가지 선택한 기호로 구성할 수 있습니다.
VOIP 헤더 키의 최대 길이는 64자입니다. VOIP 헤더 값의 최대 길이는 1024자입니다.
이러한 사용자 지정 헤더를 개발자로 추가할 때 SIP 헤더만 추가하도록 선택할 수 있으며 VoIP 헤더 또는 둘 다만 포함할 수 있습니다.
참고 항목
현재 사용자 지정 사용자 대 사용자 정보 헤더 추가는 1:1 호출을 시작할 때만 지원됩니다. 그룹 호출에서 사용자-사용자 정보 헤더 전달은 현재 지원되지 않습니다. 1:1 호출을 시작한 후 이 작업을 수행하려면 통화 내에서 사용자 간 정보를 유지하면서 추가 참가자를 포함할 수 있습니다.
사용자 지정 컨텍스트 인터페이스 API에 대한 자세한 내용은 사용자 지정 컨텍스트 API 리소스 페이지를 참조하세요.
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',
},
};
});
통화에서 사용자-사용자 정보 헤더 읽기 및 구문 분석
callAgent 인스턴스는 로그인된 ID가 전화를 받을 때 incomingCall 이벤트를 내보냅니다. 이 이벤트를 수신 대기하고 상황별 정보를 추출하려면 다음 옵션 중 하나를 사용하여 구독합니다.
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`);
}
}
});