Communication Services Calling SDK를 사용하여 Teams 사용자의 통화 관리

Azure Communication Services SDKS를 사용하여 통화를 관리하는 방법을 알아봅니다. 전화를 걸고, 참가자와 속성을 관리하는 방법을 알아봅니다.

필수 조건

• 활성 구독이 있는 Azure 계정. 체험 계정을 만듭니다.
• 배포된 Communication Services 리소스. Communication Services 리소스 만들기
• 호출 클라이언트를 사용하도록 설정하는 User Access Token입니다. User Access Token를 가져오는 방법에 대한 자세한 정보
• 선택 사항: 애플리케이션에 화상 통화 추가 시작에 대한 빠른 시작을 완료합니다.

SDK 설치

npm install 명령을 사용하여 JavaScript용 Azure Communication Services 통화 SDK 및 일반 SDK를 설치합니다.

npm install @azure/communication-common --save
npm install @azure/communication-calling --save

필수 개체 초기화

통화 스택을 시작하는 CallClient 인스턴스를 만듭니다. AzureLogger 인스턴스 및 setLogLevel 메서드를 사용하여 Calling SDK 로깅을 구성할 수 있습니다. getDeviceManager 메서드를 사용하여 운영 체제에 대한 deviceManager 액세스 권한을 얻을 수 있습니다.

그런 다음, createTeamsCallAgent 메서드를 사용하여 Teams 사용자의 수신 및 발신 통화를 관리하는 TeamsCallAgent 인스턴스를 비동기적으로 만듭니다. 이 메서드는 Teams 사용자의 액세스 토큰을 나타내는 인수로 CommunicationTokenCredential을 사용합니다.

const { CallClient } = require('@azure/communication-calling');
const { AzureCommunicationTokenCredential} = require('@azure/communication-common');
const { AzureLogger, setLogLevel } = require("@azure/logger");

// Set the logger's log level
setLogLevel('verbose');

// Redirect log output to wherever desired. To console, file, buffer, REST API, etc...
AzureLogger.log = (...args) => {
    console.log(...args); // Redirect log output to console
};

const userToken = '<USER_TOKEN>';
callClient = new CallClient();
const tokenCredential = new AzureCommunicationTokenCredential(userToken);
const teamsCallAgent = await callClient.createTeamsCallAgent(tokenCredential);
const deviceManager = await callClient.getDeviceManager();

전화 걸기

teamsCallAgent에서 startCall API를 사용하여 동기 일 대 일 또는 그룹 통화를 시작합니다. MicrosoftTeamsUserIdentifier 또는 PhoneNumberIdentifier를 매개 변수로 제공하여 통화 대상을 정의할 수 있습니다. 이 메서드는 통화 이벤트를 구독할 수 있게 해주는 TeamsCall 인스턴스를 반환합니다.

Teams 사용자에 대한 일 대 일 VoIP(Voice-over IP) 통화를 시작합니다.

const userCallee = { microsoftTeamsUserId: '<MICROSOFT_TEAMS_USER_ID>' };
const oneToOneCall = teamsCallAgent.startCall(userCallee);

E.164 전화 번호에 대한 일 대 일 전화 통화를 시작합니다.

const phoneCallee = { phoneNumber: '<PHONE_NUMBER_E164_FORMAT>' }
const oneToOneCall = teamsCallAgent.startCall(phoneCallee );

VoIP(Voice-over IP) 및 전화 번호를 사용하여 Teams 사용자에 대한 그룹 통화를 시작합니다.

const userCallee = { microsoftTeamsUserId: '<MICROSOFT_TEAMS_USER_ID>' }
const phoneCallee = { phoneNumber: '<PHONE_NUMBER_E164_FORMAT>'};
const groupCall = teamsCallAgent.startCall([userCallee, phoneCallee], { threadId: '<THREAD_ID>' });

통화에 참여

Teams 모임 참여

teamsCallAgent 인스턴스의 join 메서드를 사용하여 Teams 모임에 참가할 수 있습니다. Teams 사용자는 TeamsMeetingLinkLocator, TeamsMeetingCoordinatesLocator 또는 TeamsMeetingIdLocator를 제공하여 Teams 모임에 참가할 수 있습니다.

모임 URL을 사용하여 Teams 모임에 참가:

const meetingCall = teamsCallAgent.join({ meetingLink: '<MEETING_LINK>' });

스레드 ID, 주최자 ID, 테넌트 ID 및 메시지 ID를 조합하여 Teams 모임에 참가:

const meetingCall = teamsCallAgent.join({ threadId: '<THREAD_ID>', organizerId: '<ORGANIZER_ID>', tenantId: '<TENANT_ID>', messageId: '<MESSAGE_ID>' });

모임 코드 및 암호를 사용하여 Teams 모임에 참가:

const meetingCall = teamsCallAgent.join({ meetingId: '<MEETING_CODE>', passcode: '<PASSCODE>'});

모임 ID 및 암호를 사용하여 Teams 모임에 참가:

개발자는 여러 가지 방법으로 참가자를 Teams 모임에 연결할 수 있습니다. 한 가지 방법은 모임 ID 및 암호를 사용하여 사용자가 디바이스 또는 애플리케이션에서 초대된 Teams 모임에 참가하는 것입니다. 모임에 참가하려면 항상 모임 ID와 암호를 모두 제공해야 합니다. 암호는 대/소문자를 구분합니다.

• 모임 ID 및 암호의 형식:

  • 모임 ID: 12자리
  • 암호: 6자

• 모임 ID와 암호를 얼마나 자주 새로 고쳐야 하나요?

  • 모임 ID와 암호는 한 번 만들어지면 변경되지 않습니다. 개발자는 두 가지 모두 새로 고칠 필요가 없습니다.
  • Teams 모임 주최자는 모임 ID 및 암호를 다시 생성할 수 없습니다.

• URL을 통해 참가하는 경우와 모임 ID와 암호를 통해 참가하는 경우 Teams 모임 환경에 차이가 있나요?

  • 아니요, 참가자는 Teams 모임 URL이나 모임 ID와 암호를 사용하여 Teams 모임에 참가하는 경우 동일한 환경을 갖게 됩니다.

• 개발자는 암호를 어떻게 저장하고 관리해야 하나요?

  • 모임 ID와 암호는 모임에 참가하기 위한 좌표입니다. 개발자는 이를 비밀로 취급하여 암호화해야 하며, 이를 저장하는 경우 액세스가 제어되는 환경에 있는지 확인해야 합니다.
  • 좌표가 노출되면 누구나 모임에 참가할 수 있게 되어 모임에 참가한 모든 사용자의 경험을 망칠 수 있습니다.

• 모임 ID 및 암호를 가져오는 방법은 무엇인가요?

  1. Graph API: Graph API를 사용하여 onlineMeeting 리소스에 대한 정보를 검색하고 joinMeetingIdSettings 속성에서 개체를 확인합니다.
  2. Teams: Teams 애플리케이션에서 Calendar 앱으로 이동하여 모임의 세부 정보를 엽니다. 온라인 모임에는 모임 정의에 모임 ID와 암호가 있습니다.
  3. Outlook: 일정 이벤트 또는 이메일 모임 초대에서 모임 ID 및 암호를 찾을 수 있습니다.
  4. 개발자는 SDK 호출을 통해 모임 ID 및 암호를 검색하거나 상세 콘솔 로그에서 검색할 수 없습니다.

• 모임 ID와 암호가 올바른지 어떻게 확인할 수 있나요?

  • MeetingId 및 암호 확인은 https://www.microsoft.com/en-us/microsoft-teams/join-a-meeting을 통해 수행할 수 있습니다.

Teams 수신 전화 받기

teamsCallAgent 인스턴스에서 incomingCall 이벤트를 구독하여 Teams 사용자에게 수신되는 전화를 등록할 수 있습니다. 이벤트에는 사용자가 수신 전화를 accept 또는 reject할 수 있게 해주는 TeamsIncomingCall 인스턴스가 있는 teamsIncomingCall 속성이 있습니다.

const incomingCallHandler = async (args: { teamsIncomingCall: TeamsIncomingCall }) => {
    const incomingCall = args.teamsIncomingCall;
    // Get Teams incoming call ID
    const incomingCallId = incomingCall.id;
    // Get information about this Call. This API is provided as a preview for developers
    // and may change based on feedback that we receive. Do not use this API in a production environment.
    // To use this API please use 'beta' release of Azure Communication Services Calling Web SDK
    const callInfo = incomingCall.info;
    // Get information about caller
    const callerInfo = incomingCall.callerInfo
    // Accept the call
    const teamsCall = await incomingCall.accept();
    // Reject the call
    incomingCall.reject();
    // Subscribe to callEnded event and get the call end reason
    incomingCall.on('callEnded', args => {
        console.log(args.callEndReason);
    });
    // callEndReason is also a property of IncomingCall
    var callEndReason = incomingCall.callEndReason;
};
teamsCallAgent.on('incomingCall', incomingCallHandler);

비디오 사용 및 사용 안 함

TeamsCall 인스턴스의 localVideoStreams 속성에서 로컬 비디오 스트림 컬렉션을 가져올 수 있습니다. 이 기능을 사용하도록 설정하면 컬렉션에 화면 공유 스트림과 카메라 동영상 피드가 포함됩니다. 원격 참가자의 비디오 스트림을 가져오려면 TeamsCall.remoteParticipants 속성을 조사하면 됩니다. 여기서 각 참가자는 videoStreams 속성에 비디오 스트림 컬렉션이 있습니다.

음소거 및 음소거 해제

TeamsCall 인스턴스에서 및 mute 및 unmute 비동기 API를 사용하여 Teams 사용자를 로컬로 음소거하거나 음소거를 해제할 수 있습니다. 로컬 음소거를 사용하면 다른 참가자에게 오디오가 전송되지 않습니다.

//mute local device
await call.mute();
//unmute local device
await call.unmute();

다른 참가자 음소거

다른 모든 참가자를 음소거하거나 특정 참가자를 음소거하려면 통화에 비동기 API muteAllRemoteParticipants를 사용하고 원격 참가자에 mute를 사용할 수 있습니다.

//mute all participants except yourself
await call.muteAllRemoteParticipants();

//mute a specific participant
await call.remoteParticipants[0].mute();

원격 참가자 관리

다른 통화 참가자는 remoteParticipants 속성 아래 TeamsCall 인스턴스에서 볼 수 있습니다. RemoteParticipant 개체의 컬렉션입니다. 통화의 다른 참가자를 나열, 추가 및 제거할 수 있습니다.

TeamsCall 개체에서 addParticipant 메서드를 호출하여 Teams 통화 또는 Teams 모임에 새 Teams 사용자 또는 전화 번호를 추가할 수 있습니다. 이 메서드는 MicrosoftTeamsUserIdentifier 또는 PhoneNumberIdentifier 식별자를 입력으로 사용하고, RemoteParticipant의 인스턴스를 동기적으로 반환하고, TeamsCall 인스턴스에서 remoteParticipantsUpdated 이벤트를 트리거합니다.

TeamsCall 인스턴스에서 removeParticipant 메서드를 비동기적으로 호출하여 Teams 통화 또는 Teams 모임에서 참가자를 제거할 수 있습니다. 이 메서드는 MicrosoftTeamsUserIdentifier 또는 PhoneNumberIdentifier 식별자를 입력으로 사용합니다. RemoteParticipant가 remoteParticipants 컬렉션에서 제거되면 메서드가 확인되고, TeamsCall 인스턴스의 remoteParticipantsUpdated 이벤트가 트리거됩니다.

다른 통화 참가자 나열:

const participants = call.remoteParticipants; // [remoteParticipant, remoteParticipant....]

Teams 통화 또는 Teams 모임에 Teams 사용자 및 전화 번호 추가:

const teamsUser = { microsoftTeamsUserId: '<MICROSOFT_TEAMS_USER_ID>' };
const phoneUser = { phoneNumber: '<PHONE_NUMBER_E164_FORMAT>' }
const remoteParticipant = call.addParticipant(teamsUser , { threadId: '<THREAD_ID>' });
const remoteParticipant2 = call.addParticipant(phoneUser , { threadId: '<THREAD_ID>' });

Teams 통화 또는 Teams 모임에서 Teams 사용자 및 전화 번호 제거:

const teamsUser = { microsoftTeamsUserId: '<MICROSOFT_TEAMS_USER_ID>' };
const phoneUser = { phoneNumber: '<PHONE_NUMBER_E164_FORMAT>' }
await call.removeParticipant(teamsUser);
await call.removeParticipant(phoneUser);

원격 참가자

원격 참가자는 진행 중인 Teams 통화 또는 Teams 모임에 연결된 엔드포인트를 나타냅니다. remoteParticipant 클래스에는 다음과 같은 속성 및 컬렉션 집합이 있습니다.

• identifier: CommunicationUserIdentifier, MicrosoftTeamsUserIdentifier, PhoneNumberIdentifier 또는 UnknownIdentifier 식별자 중 하나를 반환합니다.

const identifier = remoteParticipant.identifier;

• state: 원격 참가자의 상태를 나타내는 string을 반환합니다. 상태는 다음 값 중 하나일 수 있습니다.

일대일 또는 그룹 통화의 원격 참가자 상태:

Teams 모임의 원격 참가자 상태:

const state = remoteParticipant.state;

• callEndReason: 통화가 종료된 이유에 대한 추가 정보가 포함된 개체를 반환합니다. code 속성은 이유와 연결된 숫자를 반환하고, subCode는 코드 및 이유와 연결된 숫자를 반환합니다. 오류 코드에 대한 자세한 내용은 통화 종료 응답 코드 문제 해결을 참조하세요.

const callEndReason = remoteParticipant.callEndReason;
const callEndReasonCode = callEndReason.code
const callEndReasonSubCode = callEndReason.subCode

• isMuted: 로컬 음소거 상태를 나타내는 Boolean 값을 반환합니다.

const isMuted = remoteParticipant.isMuted;

• isSpeaking: 전송 중인 비어 있지 않은 오디오의 상태를 나타내는 Boolean 값을 반환합니다.

const isSpeaking = remoteParticipant.isSpeaking;

• videoStreams: 참가자가 보낸 RemoteVideoStream 개체의 컬렉션을 반환합니다.

const videoStreams = remoteParticipant.videoStreams; // [RemoteVideoStream, ...]

• displayName: 표시 이름을 나타내는 string을 반환합니다. SDK를 호출하는 Communication Services는 Teams 사용자에게 이 값을 설정하지 않습니다.

const displayName = remoteParticipant.displayName;

통화

• id: 고유한 통화 식별자를 나타내는 문자열을 반환합니다.

const callId = call.id;

• info: 통화에 대한 정보를 반환합니다.

• info: 통화에 대한 정보를 포함하는 개체를 반환합니다. threadId 속성은 Teams 클라이언트에 표시된 채팅의 스레드 ID를 나타내는 문자열입니다.

const callInfo = call.info;
const threadId = call.info.threadId;

• remoteParticipants: Teams 통화 또는 Teams 모임에서 다른 참가자를 나타내는 remoteParticipant 개체의 컬렉션을 반환합니다.

const remoteParticipants = call.remoteParticipants;

• callerInfo: 수신 통화에 대한 CallerInfo 개체를 반환합니다. identifier 속성은 CommunicationUserIdentifier, MicrosoftTeamsUserIdentifier, PhoneNumberIdentifier 또는 UnknownIdentifier 개체 중 하나일 수 있습니다. displayName 속성은 설정된 경우 표시할 이름을 나타내는 문자열입니다.

const callerIdentity = call.callerInfo.identifier;
const callerIdentity = call.callerInfo.displayName;

• state: 통화 상태를 나타내는 문자열을 반환합니다. 이 속성 값은 다음 중 하나일 수 있습니다.

일대일 또는 그룹 통화의 상태:

Teams 모임의 상태:

const callState = call.state;

• callEndReason: 종료된 통화에 대한 추가 정보가 포함된 CallEndReason 개체를 반환합니다. code 속성은 이유와 연결된 숫자를 반환하고, subCode는 코드 및 이유와 연결된 숫자를 반환합니다. 오류 코드에 대한 자세한 내용은 통화 종료 응답 코드 문제 해결을 참조하세요.

const callEndReason = call.callEndReason;
const callEndReasonCode = callEndReason.code
const callEndReasonSubCode = callEndReason.subCode

• direction: 통화의 방향을 나타내는 string을 반환합니다. 속성 값은 'Incoming' 또는 Outgoing 중 하나일 수 있습니다.

const isIncoming = call.direction == 'Incoming';
const isOutgoing = call.direction == 'Outgoing';

• isMuted: 로컬 음소거 상태를 나타내는 Boolean 값을 반환합니다.

const muted = call.isMuted;

• isScreenSharingOn: 화면 공유 스트림을 다른 참가자에게 보내는 경우 Boolean 값 true를 반환합니다.

const isScreenSharingOn = call.isScreenSharingOn;

• localVideoStreams: 원격 참가자에게 전송되는 비디오 스트림을 나타내는 LocalVideoStream 개체 컬렉션을 반환합니다.

const localVideoStreams = call.localVideoStreams;

채팅 스레드 관리

채팅 ID를 제공하는 것은 그룹 통화를 하고 기존 통화에 참가자를 추가하기 위한 선택 사항입니다. 연결된 채팅 및 통화에는 별도의 참가자 목록이 있습니다. 최상의 사용자 경험을 보장하고 정보 장벽 요구 사항을 충족하려면 참가자를 통화에 추가하기 전에 해당 사용자를 채팅에 추가합니다. 채팅에 사용자를 추가하지 않고 통화에 추가하면 정보 장벽이 설정된 경우 예외가 발생할 수 있습니다.

Alice가 Bob에게 전화를 걸고, Alice가 Charlie를 추가하고, 3분 후에 Alice가 통화에서 Charlie를 제거하는 다음 시나리오를 고려해 보세요.

1. Alice, Bob 및 Charlie 간에 채팅 스레드를 만듭니다. 나중을 위해 채팅 threadId를 유지합니다.
2. Alice가 TeamsCallAgent 인스턴스에서 startCall 메서드를 사용하여 Bob과 Charlie에게 전화를 겁니다.
3. 멤버를 추가하는 채팅 Graph API를 사용하여 threadId를 통해 채팅 스레드에 Dan을 추가합니다.
4. Alice가 call의 addParticipant 메서드를 사용하여 Dan을 통화에 추가하고 threadId를 지정합니다.
5. Alice가 call의 removeParticipant 메서드를 사용하여 통화에서 Dan을 제거하고 threadId를 지정합니다.
6. 멤버를 제거하는 채팅 Graph API를 사용하여 threadId를 통해 채팅 스레드에서 Dan을 제거합니다.

Teams 사용자가 통화 녹음/녹화를 중지하면 스레드와 연결된 채팅에 대한 녹음/녹화가 시작됩니다. 제공된 채팅 ID는 Teams 클라이언트의 Teams 사용자 환경에 영향을 줍니다.

채팅 ID 관리에 대한 권장 사항:

• 다른 전화 참가자를 추가하여 1:1 전화 통화 에스컬레이션:
  • 메서드 addParticipant 를 사용하면 선택적 매개 변수 스레드 ID를 제공할 수 있습니다. 매개 변수가 제공되지 않으면 새 그룹 채팅이 만들어지고 모든 참가자가 통화 및 채팅 참가자 목록에 추가됩니다. 매개 변수가 제공되면 Teams 사용자는 Teams 앱에서 이 그룹 채팅과 관련된 지속적인 통화를 볼 수 있습니다. Graph API를 통해 새 그룹 채팅을 만들 수 있습니다.

    addParticipant(participant: MicrosoftTeamsUserIdentifier | PhoneNumberIdentifier | MicrosoftTeamsAppIdentifier | UnknownIdentifier)
    

• 단일 Microsoft 365 사용자 및 여러 전화 참가자를 사용하여 그룹 통화를 시작합니다.
  • 메서드 startCall API를 사용하면 여러 참가자와 그룹 호출을 시작하고 필요에 따라 스레드 ID를 제공할 수 있습니다. 매개 변수가 제공되지 않으면 새 그룹 채팅이 만들어지고 모든 Microsoft 365 참가자가 통화 및 채팅 참가자 목록에 추가됩니다. 매개 변수가 제공되면 Teams 사용자는 Teams 앱에서 이 그룹 채팅과 관련된 지속적인 통화를 볼 수 있습니다. Graph API를 통해 새 그룹 채팅을 만들 수 있습니다.

    startCall(MicrosoftTeamsUserIdentifier | PhoneNumberIdentifier | MicrosoftTeamsAppIdentifier | UnknownIdentifier)[])
    

  • Graph API를 사용하여 Teams 사용자로만 기존 채팅 ID를 가져오거나 참가자와 함께 새 그룹 채팅을 만듭니다. Teams 사용자 ID 및 "00000000-00000-0000-0000000000000".
• 2명 이상의 Microsoft 365 사용자로 그룹 통화 시작:
  • (선택적 방법) ACS Calling SDK를 사용하여 2명 이상의 Microsoft 365 사용자와 그룹 통화를 할 때 SDK는 기본적으로 스레드를 자동으로 만듭니다.

    startCall(MicrosoftTeamsUserIdentifier | PhoneNumberIdentifier | MicrosoftTeamsAppIdentifier | UnknownIdentifier)[])
    

  • 원하는 경우 개발자는 고유한 스레드 ID를 제공하여 그룹 호출을 시작하거나 참가자를 추가할 수 있습니다. 이 경우 ACS 통화 SDK는 지정된 스레드 ID를 사용하여 그룹 호출을 만듭니다. 채팅 스레드는 Teams 사용자를 위해 만들어지고 이 스레드는 Teams 앱의 사용자에 대한 그룹 호출과 연결됩니다. 이렇게 하면 통화 중에 채팅할 수 있습니다. Graph API를 통해 채팅 스레드 관리를 수행할 수 있습니다.