使用通訊服務通話 SDK 來管理 Teams 使用者的通話

了解如何使用 Azure 通訊服務 SDK 來管理通話。 我們將了解如何撥打電話，如何管理其參與者和屬性。

必要條件

• 具有有效訂用帳戶的 Azure 帳戶。 免費建立帳戶。
• 已部署通訊服務資源。 建立通訊服務資源。
• 用來啟用通話用戶端的 User Access Token。 如需如何取得 User Access Token 的詳細資訊
• 選擇性：完成開始將視訊通話新增至應用程式的快速入門

安裝 SDK

使用 npm install 命令安裝適用於 JavaScript 的 Azure 通訊服務通話 SDK 和通用 SDK。

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

初始化必要的物件

建立 CallClient 執行個體以起始呼叫堆疊。 您可以使用 AzureLogger 執行個體和 setLogLevel 方法，來設定通話 SDK 的記錄。 您可以使用方法 getDeviceManager，來取得作業系統的 deviceManager 存取權。

然後使用方法 createTeamsCallAgent，以非同步方式建立 TeamsCallAgent 執行個體，藉此管理 Teams 使用者接收及撥出的通話。 方法會採用 CommunicationTokenCredential 作為引數，以此代表 Teams 使用者的存取權杖。

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 使用者撥打一對一的 IP 語音傳輸 (VoIP) 通話：

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 );

使用 IP 語音傳輸 (VoIP) 服務和電話號碼，向 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>' });

使用對話識別碼、召集人識別碼、租用戶識別碼，以及訊息識別碼的組合來加入 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>'});

使用會議識別碼和密碼加入 Teams 會議：

開發人員可以透過多種方式將參與者連線到 Teams 會議。 其中一種方式是使用會議識別碼和密碼，讓人員能夠從裝置或應用程式加入其受邀參加的 Teams 會議。 一律需同時提供會議識別碼和密碼，才能加入會議。 密碼區分大小寫。

• 會議識別碼和密碼的格式：

  • 會議識別碼：12 位數字。
  • 密碼：6 個字元

• 會議識別碼和密碼多久需更新一次？

  • 會議識別碼和密碼在建立後即不會變更。 開發人員不需要重新整理任何一項。
  • Teams 會議召集人無法重新產生會議識別碼和密碼。

• 如果人員透過 URL 或會議識別碼和密碼加入 Teams 會議，在體驗上是否有任何差異？

  • 否，如果參與者使用 Teams 會議 URL 或會議識別碼和密碼加入 Teams 會議，則會有相同的體驗。

• 開發人員應如何儲存及管理密碼？

  • 會議識別碼和密碼是加入會議的座標。 開發人員應將其視為應予以加密的秘密，若已儲存，請確定它們位於存取控制的環境中。
  • 如果公開座標，任何人都可以加入會議，這會破壞每個與會者的體驗。

• 如何取得會議識別碼和密碼？

  1. 圖形 API：使用圖形 API 擷取 onlineMeeting 資源的相關資訊，並檢查屬性 joinMeetingIdSettings 中的物件。
  2. Teams：在您的 Teams 應用程式中，移至 Calendar 應用程式並開啟會議的詳細資料。 線上會議在會議定義中具有會議識別碼和密碼。
  3. Outlook：您可以在行事曆活動或電子郵件會議邀請中找到會議識別碼和密碼。
  4. 開發人員無法透過通話 SDK 來擷取會議識別碼和密碼，或是從詳細資訊控制台記錄擷取。

• 如何確認會議識別碼和密碼是否正確？

  • MeetingId 和密碼驗證可透過下列途徑完成：https://www.microsoft.com/en-us/microsoft-teams/join-a-meeting。

接收 Teams 來電

您可以訂閱 teamsCallAgent 執行個體上的 incomingCall 事件，來向 Teams 使用者註冊來電。 事件具有 teamsIncomingCall 屬性以及 TeamsIncomingCall 執行個體，可讓您 accept 或 reject 來電。

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 不會針對 Teams 使用者設定這個值。

const displayName = remoteParticipant.displayName;

通話

• id：傳回字串，該字串代表唯一呼叫識別碼。

const callId = call.id;

• info：傳回通話的相關資訊：

• info：傳回的物件包含通話相關資訊。 屬性 threadId 是字串，代表 Teams 用戶端中顯示的聊天對話識別碼。

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

• remoteParticipants：傳回 remoteParticipant 物件集合，代表 Teams 通話或 Teams 會議中的其他參與者。

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，代表通話的方向。 屬性可以有下列其中一個值：「連入」或 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;

管理聊天對話

提供聊天標識碼是選擇性的，可用於進行群組通話，並將參與者新增至現有的通話。 相關聯的聊天和通話有個別的參與者清單。 將參與者新增至通話之前，請將使用者新增至聊天，以提供最佳使用者體驗，並滿足資訊屏障需求。 若未將使用者新增至聊天就將使用者新增至通話，在設定了資訊屏障時，可能會引發例外狀況。

請參閱下列案例，其中 Alice 撥打電話給 Bob，接著 Alice 會新增 Charlie，3 分鐘之後，Alice 會從通話中移除 Charlie。

1. 建立 Alice、Bob 和 Charlie 之間的聊天對話。 請保留聊天 threadId 以供稍後使用。
2. Alice 使用 TeamsCallAgent 執行個體上的 startCall 方法，來撥打電話給 Bob 和 Charlie。
3. 若要透過 threadId 來將 Dan 新增至聊天對話，請使用聊天圖形 API 以新增成員
4. Alice 使用 call 上的 addParticipant 方法來將 Dan 新增至通話，並指定 threadId
5. Alice 使用 call 上的 removeParticipant 方法來將 Dan 從通話中移除，並指定 threadId
6. 若要透過 threadId 來將 Dan 從聊天對話中移除，請使用聊天圖形 API 以移除成員

如果 Teams 使用者停止通話錄音，錄製內容會存入與對話相關聯的聊天中。 提供的聊天識別碼會影響 Teams 用戶端中 Teams 使用者的體驗。

管理聊天識別碼的建議：

• 新增另一個電話參與者，以擴大 1：1 通話：
  • 方法 addParticipant 可讓您提供選擇性參數聊天標識碼。 如果未提供 參數，則會建立新的群組聊天，並將所有參與者新增至通話和聊天參與者清單。 如果提供 參數，則Teams用戶可以在Teams應用程式中看到與此群組聊天相關聯的持續通話。 您可以透過 Graph API 建立新的群組聊天。

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

• 使用單一Microsoft 365 使用者和多個電話參與者啟動群組通話：
  • 方法 startCall API 可讓您啟動與多個參與者的群組呼叫，並選擇性地提供聊天標識碼。 如果未提供 參數，則會建立新的群組聊天，並將所有Microsoft 365 個參與者新增至通話和聊天參與者清單。 如果提供 參數，則Teams用戶可以在Teams應用程式中看到與此群組聊天相關聯的持續通話。 您可以透過 Graph API 建立新的群組聊天。

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

  • 使用 Graph API 取得只有 Teams 使用者作為參與者的現有聊天標識碼，或建立與參與者的新群組聊天：Teams 使用者標識碼和 “000000-0000-0000-0000-000000000000000”。
• 使用超過 2 個Microsoft 365 使用者開始群組通話：
  • （選擇方式）使用ACS通話 SDK 與超過 2 個Microsoft 365 位使用者進行群組通話時，SDK 預設會自動建立線程。

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

  • 如有需要，開發人員可以提供唯一的聊天標識符來啟動群組通話或新增參與者。 在此情況下，ACS 通話 SDK 會使用指定的聊天標識碼來建立群組通話。 系統會為 Teams 使用者建立聊天對話，且此對話與 Teams 應用程式中使用者的群組通話相關聯。 這可讓他們在通話期間聊天。 聊天對話管理可透過 圖形 API 完成