통화 전환

아티클
06/29/2024

통화 중에 통화를 다른 사람, 번호 또는 음성 메일로 전송할 수 있습니다. 방법을 알아보겠습니다.

필수 조건

활성 구독이 있는 Azure 계정. 체험 계정을 만듭니다.
배포된 Communication Services 리소스. Communication Services 리소스 만들기
호출 클라이언트를 사용하도록 설정하는 사용자 액세스 토큰입니다. 자세한 내용은 액세스 토큰 만들기 및 관리를 참조하세요.
선택 사항: 빠른 시작을 완료하여 애플리케이션에 음성 통화를 추가합니다.

SDK 설치

npm install 명령을 사용하여 다음과 같은 JavaScript용 Azure Communication Services Common 및 통화 SDK를 설치합니다.

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

필수 개체 초기화

대부분의 호출 작업에는 CallClient 인스턴스가 필요합니다. 새 CallClient 인스턴스를 만들 때 Logger 인스턴스와 같은 사용자 지정 옵션을 사용하여 이 새 인스턴스를 구성할 수 있습니다.

CallClient 인스턴스를 사용하면 createCallAgent를 호출하여 CallAgent 인스턴스를 만들 수 있습니다. 이 메서드는 CallAgent 인스턴스 개체를 비동기적으로 반환됩니다.

createCallAgent 메서드는 CommunicationTokenCredential을 인수로 사용합니다. 사용자 액세스 토큰이 허용됩니다.

CallClient 인스턴스에서 getDeviceManager 메서드를 사용하여 deviceManager에 액세스할 수 있습니다.

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 console, file, buffer, REST API, or whatever location you want
AzureLogger.log = (...args) => {
    console.log(...args); // Redirect log output to console
};

const userToken = '<USER_TOKEN>';
callClient = new CallClient(options);
const tokenCredential = new AzureCommunicationTokenCredential(userToken);
const callAgent = await callClient.createCallAgent(tokenCredential, {displayName: 'optional Azure Communication Services user name'});
const deviceManager = await callClient.getDeviceManager()

Microsoft 인프라에 대한 SDK 연결을 가장 잘 관리하는 방법

Call Agent 인스턴스는 통화를 관리하는 데 도움이 됩니다(통화 참여 또는 시작). 작동하려면 통화 SDK가 Microsoft 인프라에 연결하여 수신 전화에 대한 알림을 가져오고 기타 호출 세부 정보를 조정해야 합니다. 사용자의 Call Agent에는 두 가지 상태가 있을 수 있습니다.

연결됨 - Call Agent connectionStatue 값이 Connected이면 클라이언트 SDK가 연결되어 있고 Microsoft 인프라로부터 알림을 받을 수 있음을 의미합니다.

연결 끊김 - Disconnected의 Call Agent connectionStatue 값은 SDK가 제대로 연결되지 못하게 하는 문제가 있음을 나타냅니다. Call Agent를 다시 만들어야 합니다.

invalidToken: 토큰이 만료되었거나 유효하지 않은 경우 Call Agent 인스턴스가 이 오류와 함께 연결 끊기됩니다.
connectionIssue: Microsoft 인프라에 연결하는 클라이언트에 문제가 있는 경우 여러 번 다시 시도한 후 Call Agent에서 connectionIssue 오류를 노출합니다.

connectionState 속성의 현재 값을 검사하여 로컬 Call Agent가 Microsoft 인프라에 연결되어 있는지 확인할 수 있습니다. 활성 통화 중에 connectionStateChanged 이벤트를 수신 대기하여 Call Agent가 연결됨에서 연결 끊김 상태로 변경되는지 확인할 수 있습니다.

const connectionState = callAgentInstance.connectionState;
console.log(connectionState); // it may return either of 'Connected' | 'Disconnected'

const connectionStateCallback = (args) => {
    console.log(args); // it will return an object with oldState and newState, each of having a value of either of 'Connected' | 'Disconnected'
    // it will also return reason, either of 'invalidToken' | 'connectionIssue'
}
callAgentInstance.on('connectionStateChanged', connectionStateCallback);

통화 전송은 핵심 Call API의 확장 기능입니다. 먼저 통화 SDK에서 호출 기능을 가져와야 합니다.

import { Features} from "@azure/communication-calling";

그런 다음 통화 인스턴스에서 전송 기능 API 개체를 가져올 수 있습니다.

const callTransferApi = call.feature(Features.Transfer);

통화 전환에는 세 명의 당사자가 포함됩니다.

'전송자': 전송 요청을 시작한 사람입니다.
'피전송자': 이 사람의 통화가 전송됩니다.
'전송 대상': 통화가 이 사람에게 전송됩니다.

참가자에게 전송:

'전송자'와 '피전송자' 사이에 이미 연결된 통화가 있습니다. '전송자'가 '피전송자'와의 통화를 '전송 대상'으로 전송하기로 결정합니다.
'전송자'가 transfer API를 호출합니다.
전송 대상은 들어오는 호출을 받습니다.

현재 통화를 전송하려면 transfer API를 사용하면 됩니다. transfer는 사용자가 disableForwardingAndUnanswered 플래그를 설정할 수 있는 transferCallOptions 옵션을 허용합니다.

disableForwardingAndUnanswered = false: '전송 대상'이 전송 통화에 응답하지 않으면 전송은 '전송 대상' 착신 전환 및 응답 없음 설정을 따릅니다.
disableForwardingAndUnanswered = true: '전송 대상'이 전송 통화에 응답하지 않으면 전송 시도가 종료됩니다.

// transfer target can be an Azure Communication Services user
const id = { communicationUserId: <ACS_USER_ID> };

// call transfer API
const transfer = callTransferApi.transfer({targetParticipant: id});

통화로 전환:

'전송자'와 '피전송자' 사이에 이미 연결된 통화가 있습니다.
전송자와 전송 대상 사이에 이미 연결된 통화가 있습니다.
전송자는 피전송자가 있는 통화를 전송 대상이 있는 통화로 전달하기로 결정합니다.
'전송자'가 transfer API를 호출합니다.
전송 대상은 들어오는 호출을 받습니다.

현재 통화를 전송하려면 transfer API를 사용하면 됩니다.

// transfer to the target call specifying the call id
const id = { targetCallId: <CALL_ID> };

// call transfer API
const transfer = callTransferApi.transfer({ targetCallId: <CALL_ID> });

transfer API를 사용하면 stateChanged를 구독할 수 있습니다. 전송 state 및 error 속성도 함께 제공됩니다.

// transfer state
const transferState = transfer.state; // None | Transferring | Transferred | Failed

// to check the transfer failure reason
const transferError = transfer.error; // transfer error code that describes the failure if a transfer request failed

전송자는 transferAccepted 이벤트를 수신 대기할 수 있습니다. 이 이벤트의 수신기에는 전송자와 전송 대상 간의 새 전송 호출의 호출 개체를 포함하는 TransferEventArgs가 있습니다.

// Transferee can subscribe to the transferAccepted event
callTransferApi.on('transferAccepted', args => {
    const newTransferCall =  args.targetCall;
});

전송자는 전송 상태 변경 이벤트를 구독할 수 있습니다. 피전송자에 대한 통화가 전송 대상과 성공적으로 연결된 경우 전송자는 피전송자과의 원래 통화를 끊을 수 있습니다.

transfer.on('stateChanged', () => {
   if (transfer.state === 'Transferred') {
       call.hangUp();
   }
});

음성 메일로 전송:

전송자과 피전송자 사이에 연결된 통화가 있습니다.
대상 참가자 음성 메일의 Teams 사용자 ID가 알려져 있습니다.
전송자는 대상 참가자의 Teams 사용자 ID를 사용하여 피전송자와의 통화를 대상 참가자의 음성 메일로 전송하기로 결정합니다.
'전송자'가 transfer API를 호출합니다.
피전송자가 이전 요청을 받습니다.

현재 통화를 전송하려면 transfer API를 사용하면 됩니다.

// transfer to the target participant voicemail specified by their Teams User Identifier
const id: MicrosoftTeamsUserIdentifier = { microsoftTeamsUserId: userId}

// call transfer API
const transfer = callTransferApi.transfer({ targetParticipantVoicemail: id });

transfer API를 사용하면 stateChanged를 구독할 수 있습니다. 전송 state 및 error 속성도 함께 제공됩니다.

// transfer state
const transferState = transfer.state; // None | Transferring | Transferred | Failed

// to check the transfer failure reason
const transferError = transfer.error; // transfer error code that describes the failure if a transfer request failed

전송자는 transferAccepted 이벤트를 수신 대기할 수 있습니다. 이 이벤트의 수신기에는 피전송자와 대상 참가자 음성 메일 간의 새 전송 통화의 통화 개체가 포함된 TransferEventArgs가 있습니다.

// Transferee can subscribe to the transferAccepted event
callTransferApi.on('transferAccepted', args => {
    const newTransferCall =  args.targetCall;
});

전송자는 전송 상태 변경 이벤트를 구독할 수 있습니다. 피전송자와의 통화가 대상 참가자 음성 메일과 성공적으로 연결된 경우, 전송자는 피전송자와의 원래 통화를 끊을 수 있습니다.

transfer.on('stateChanged', () => {
   if (transfer.state === 'Transferred') {
       call.hangUp();
   }
});

다음을 통해 공유