Bagikan melalui

Mengelola panggilan untuk pengguna Teams dengan SDK panggilan Communication Services

  • Artikel

Pelajari cara mengelola panggilan dengan Azure Communication Services SDKS. Kami akan belajar cara melakukan panggilan, mengelola peserta dan properti mereka.

Prasyarat

Pasang SDK

Menggunakan perintah npm install untuk memasang panggilan Azure Communication Services dan SDK umum untuk JavaScript.

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

Menginisialisasi objek yang diperlukan

Buat CallClient instans untuk memulai tumpukan panggilan. Anda dapat mengonfigurasi pengelogan SDK panggilan dengan AzureLogger instans dan setLogLevel metode . Anda bisa mendapatkan akses ke deviceManager untuk sistem operasi dengan metode getDeviceManager.

Kemudian gunakan metode createTeamsCallAgent untuk membuat instans secara TeamsCallAgent asinkron yang akan mengelola panggilan masuk dan keluar untuk pengguna Teams. Metode ini mengambil CommunicationTokenCredential sebagai argumen yang mewakili token akses untuk pengguna 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();

Melakukan panggilan

Mulai panggilan satu-ke-satu atau grup yang sinkron dengan startCall API di teamsCallAgent. Anda dapat menyediakan MicrosoftTeamsUserIdentifier atau PhoneNumberIdentifier sebagai parameter untuk menentukan target panggilan. Metode ini mengembalikan instans TeamsCall yang memungkinkan Anda berlangganan peristiwa panggilan.

Catatan

Memulai panggilan grup dengan teamsCallAgent memerlukan obrolan threadId saat memanggil startCall metode. Instans yang dibuat TeamsCall memiliki properti threadId yang menangkap utas ini. SDK Panggilan Communication Services tidak membuat peserta dalam obrolan dan daftar panggilan tetap sinkron. Microsft mendorong pengembang untuk menjaga daftar nama tetap sinkron untuk pengalaman pengguna terbaik. Pelajari cara mengelola utas obrolan.

Mulai panggilan Voice-over IP (VoIP) satu ke satu ke pengguna Teams:

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

Mulai panggilan telepon satu-ke-satu ke nomor telepon E.164:

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

Mulai panggilan grup ke pengguna Teams dengan Voice-over IP (VoIP) dan nomor telepon:

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

Bergabung dalam panggilan

Bergabung dengan rapat Teams

Anda dapat bergabung dengan rapat Teams dengan metode join pada teamsCallAgent instans. Pengguna Teams dapat bergabung dalam rapat Teams dengan menyediakan TeamsMeetingLinkLocator, , TeamsMeetingCoordinatesLocatoratau TeamsMeetingIdLocator.

Bergabung dalam rapat Teams dengan URL rapat:

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

Bergabung dalam rapat Teams dengan kombinasi ID utas, ID penyelenggara, ID penyewa, dan ID pesan:

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

Bergabung dalam rapat Teams dengan kode rapat dan kode akses:

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

Bergabung dalam rapat Teams dengan ID rapat dan kode akses:

Pengembang dapat menggunakan beberapa cara untuk bergabung dalam rapat Teams. Salah satunya adalah ID rapat dan kode akses, yang memungkinkan orang untuk bergabung dalam rapat Teams tempat mereka diundang dari perangkat atau aplikasi. Anda selalu perlu memberikan ID rapat dan kode akses untuk bergabung dalam rapat. Kode sandi peka huruf besar/kecil.

  • Format ID rapat dan kode akses adalah:

    • ID Rapat: 12 digit.
    • Kode akses: 6 karakter

  • Seberapa sering Anda perlu me-refresh ID rapat & kode akses?

    • ID rapat dan kode akses tidak berubah setelah dibuat. Pengembang tidak perlu me-refresh keduanya untuk perubahan.
    • Penyelenggara rapat Teams tidak dapat meregenerasi ID rapat dan kode akses.

  • Apakah ada perbedaan dalam pengalaman rapat Teams jika pengguna bergabung melalui URL atau ID rapat & kode akses?

    • Tidak. Pengguna akan memiliki pengalaman pengguna yang sama jika mereka bergabung dalam rapat Teams melalui URL rapat Teams atau ID rapat & kode akses.

  • Bagaimana pengembang harus menyimpan dan mengelola kode akses?

    • ID rapat dan kode akses adalah koordinat untuk bergabung dalam rapat. Pengembang harus memperlakukannya sebagai rahasia, yang harus dienkripsi dan jika disimpan maka di belakang kontrol akses.
    • Jika koordinat terekspos, siapa pun dapat bergabung dalam rapat dan merusak pengalaman untuk semua orang dalam rapat.

  • Bagaimana cara mendapatkan ID rapat & kode akses ?

    1. Graph API: Gunakan Graph API untuk mengambil informasi tentang onlineMeeting sumber daya dan memeriksa objek di properti joinMeetingIdSettings.
    2. Teams: Di aplikasi Teams Anda, buka Calendar aplikasi dan buka detail rapat. Rapat online memiliki ID rapat dan kode akses dalam definisi rapat.
    3. Outlook: Anda bisa menemukan ID rapat & kode akses dalam acara kalender atau di undangan rapat email.
    4. Pengembang tidak dapat mengambil ID rapat & kode akses melalui panggilan SDK atau mengambilnya dari log konsol verbose.

  • Bagaimana cara memverifikasi ID rapat & kode akses yang benar?

Menerima panggilan masuk Teams

Anda dapat berlangganan incomingCall peristiwa pada teamsCallAgent instans untuk mendaftarkan panggilan masuk ke pengguna Teams. Kejadian ini memiliki teamsIncomingCall properti dengan TeamsIncomingCall instans yang memungkinkan Anda untuk accept atau reject panggilan masuk.

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

Mengaktifkan dan menonaktifkan video

Anda bisa mendapatkan koleksi streaming video lokal Anda dari properti localVideoStreams dalam TeamsCall instans. Jika diaktifkan, koleksi akan berisi aliran berbagi layar, dan umpan video kamera. Anda bisa mendapatkan streaming video peserta jarak jauh dengan memeriksa properti TeamsCall.remoteParticipants di mana setiap peserta memiliki kumpulan aliran video di properti videoStreams.

Mematikan suara dan menyalakan suara

Anda dapat menggunakan mute API asinkron dan unmute pada TeamsCall instans untuk mematikan suara atau menyalakan suara pengguna Teams secara lokal. Bisu lokal akan mencegah audio dikirim ke peserta lain.

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

Mematikan suara peserta lain

Untuk mematikan suara semua peserta lain atau mematikan suara peserta tertentu, Anda dapat menggunakan API muteAllRemoteParticipants asinkron pada panggilan dan mute pada peserta jarak jauh:

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

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

Catatan

API ini disediakan sebagai pratinjau untuk pengembang dan dapat berubah menurut umpan balik yang kami terima. Jangan gunakan API ini dalam lingkungan produksi. Untuk menggunakan api ini, silakan gunakan rilis 'beta' azure Communication Services Calling Web SDK

Kelola peserta jarak jauh

Peserta panggilan lain tersedia dalam instans di TeamsCall bawah properti remoteParticipants. Ini adalah kumpulan RemoteParticipant objek. Anda dapat mencantumkan, menambahkan, dan menghapus peserta lain dari panggilan.

Catatan

Menambahkan metode peserta memerlukan obrolan threadId. SDK Panggilan Communication Services tidak membuat peserta dalam obrolan dan daftar panggilan tetap sinkron. Microsft mendorong pengembang untuk menjaga daftar nama tetap sinkron untuk pengalaman pengguna terbaik. Pelajari cara mengelola utas obrolan.

Anda dapat menambahkan pengguna atau nomor telepon Teams baru ke panggilan Teams atau rapat Teams dengan memanggil metode addParticipant pada objek TeamsCall. Metode ini menerima pengidentifikasi MicrosoftTeamsUserIdentifier atau PhoneNumberIdentifier sebagai input dan mengembalikan instans RemoteParticipant dan memicu peristiwa remoteParticipantsUpdated pada TeamsCall instans secara sinkron.

Anda dapat menghapus peserta dari panggilan Teams atau rapat Teams dengan memanggil removeParticipant metode pada TeamsCall instans secara asinkron. Metode ini menerima pengidentifikasi MicrosoftTeamsUserIdentifier atau PhoneNumberIdentifier sebagai input. Metode ini diselesaikan ketika RemoteParticipant dihapus dari remoteParticipants koleksi, dan peristiwa remoteParticipantsUpdated pada TeamsCall instans dipicu.

Mencantumkan peserta panggilan lainnya:

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

Tambahkan pengguna dan nomor telepon Teams ke panggilan Teams atau rapat 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>' });

Hapus pengguna Teams dan nomor telepon dari panggilan Teams atau rapat Teams:

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

Peserta jarak jauh

Peserta jarak jauh mewakili titik akhir yang tersambung ke panggilan Teams atau rapat Teams yang sedang berlangsung. remoteParticipant Kelas ini memiliki sekumpulan properti dan koleksi berikut:

  • identifier: Mengembalikan salah satu pengidentifikasi berikut: CommunicationUserIdentifier, , MicrosoftTeamsUserIdentifier, PhoneNumberIdentifieratau UnknownIdentifier.
const identifier = remoteParticipant.identifier;
  • state: Mengembalikan string yang mewakili status peserta jarak jauh. Status dapat memiliki salah satu nilai berikut:
Nilai status Kapan Deskripsi
Idle Status awal Ini adalah status pertama peserta
Connecting Setelah Idle Status transisi saat peserta tersambung ke panggilan.
Ringing Setelah Connecting Peserta menerima incomingCall pemberitahuan atau klien Teams berdering
Connected Setelah Ringing, Connecting, EarlyMedia atau InLobby Peserta menerima undangan panggilan atau bergabung dalam panggilan. Media mengalir ke arah peserta.
Hold Setelah Connected Peserta dalam panggilan telah ditangguhkan.
EarlyMedia Setelah Connecting Media diputar sebelum peserta tersambung ke panggilan
InLobby Setelah Ringing, Connecting atau EarlyMedia Peserta berada di lobi rapat Teams.
Disconnected Status akhir Peserta terputus dari panggilan. Jika peserta jarak jauh kehilangan konektivitas jaringan, statusnya berubah menjadi Disconnected setelah dua menit.

Status peserta jarak jauh dalam panggilan satu-ke-satu atau grup: Diagram of remote participant's call states for one-to-one or group calls.

Status peserta jarak jauh dalam rapat Teams: Diagram of remote participant's call states for Teams meetings.

const state = remoteParticipant.state;
  • callEndReason: Mengembalikan objek yang berisi informasi tambahan tentang alasan panggilan berakhir. Properti code mengembalikan angka yang terkait dengan alasannya, dan subCode mengembalikan angka yang terkait dengan kode dan alasannya. Anda dapat menemukan informasi selengkapnya tentang kode kesalahan.
const callEndReason = remoteParticipant.callEndReason;
const callEndReasonCode = callEndReason.code
const callEndReasonSubCode = callEndReason.subCode
  • isMuted: Mengembalikan Boolean nilai yang mewakili status bisu lokal.
const isMuted = remoteParticipant.isMuted;
  • isSpeaking: Mengembalikan nilai yang Boolean mewakili status audio tidak kosong yang dikirim.
const isSpeaking = remoteParticipant.isSpeaking;
  • videoStreams: Mengembalikan kumpulan RemoteVideoStream objek yang dikirim oleh peserta.
const videoStreams = remoteParticipant.videoStreams; // [RemoteVideoStream, ...]
  • displayName: Mengembalikan nama tampilan yang string mewakili. SDK panggilan Communication Services tidak menetapkan nilai ini untuk pengguna Teams.
const displayName = remoteParticipant.displayName;

Call

  • id: Mengembalikan string yang mewakili pengidentifikasi panggilan unik.
const callId = call.id;

• info: Mengembalikan informasi tentang panggilan:

Catatan

API ini disediakan sebagai pratinjau untuk pengembang dan dapat berubah menurut umpan balik yang kami terima. Jangan gunakan API ini dalam lingkungan produksi. Untuk menggunakan API ini, silakan gunakan rilis 'beta' azure Communication Services Calling Web SDK

• info: Mengembalikan objek yang berisi informasi tentang panggilan. Properti threadId adalah string yang mewakili ID utas obrolan yang ditampilkan di klien Teams.

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

• remoteParticipants: Mengembalikan kumpulan remoteParticipant objek yang mewakili peserta lain dalam panggilan Teams atau rapat Teams.

const remoteParticipants = call.remoteParticipants;

• callerInfo: Mengembalikan CallerInfo objek jika ini adalah panggilan masuk. Properti identifier dapat berupa salah satu objek CommunicationUserIdentifierberikut , , MicrosoftTeamsUserIdentifier, PhoneNumberIdentifieratau UnknownIdentifier. Properti displayName adalah string yang mewakili nama yang akan ditampilkan jika diatur.

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

• state: Mengembalikan string yang mewakili status panggilan. Properti bisa memiliki salah satu nilai berikut ini:

Nilai status Kapan Deskripsi
None Status awal Status awal panggilan.
Connecting Setelah None Status saat panggilan Teams atau rapat Teams ditempatkan, bergabung, atau diterima.
Ringing Setelah Connecting Peserta jarak jauh menerima incomingCall acara atau klien Teams berdering.
EarlyMedia Setelah Ringing atau Connecting Media diputar sebelum panggilan tersambung.
Connected Setelah Ringing, EarlyMedia, InLobby, LocalHold dan RemoteHold Panggilan tersambung. Media mengalir antara titik akhir lokal dan peserta jarak jauh.
LocalHold Setelah Connected Panggilan ditangguhkan oleh peserta lokal. Tidak ada media yang mengalir antara titik akhir lokal dan peserta jarak jauh.
RemoteHold Setelah Connected Panggilan ditangguhkan oleh peserta jarak jauh. Tidak ada media yang mengalir antara titik akhir lokal dan peserta jarak jauh.
InLobby Setelah Ringing atau Connecting Peserta jarak jauh berada di lobi rapat Teams. Tidak ada media yang mengalir antara titik akhir lokal dan peserta jarak jauh.
Disconnecting Setelah status apa pun Status transisi sebelum panggilan masuk ke status Disconnected .
Disconnected Status akhir Status akhir panggilan. Jika koneksi jaringan terputus, statusnya berubah menjadi Disconnected setelah dua menit.

Status untuk panggilan satu-ke-satu atau grup: Diagram with call's states for one-to-one or group calls.

Status untuk rapat Teams: Diagram with call's states for Teams meetings.

const callState = call.state;

• callEndReason: Mengembalikan objek CallEndReason yang berisi informasi tambahan tentang panggilan berakhir. Properti code mengembalikan angka yang terkait dengan alasannya, dan subCode mengembalikan angka yang terkait dengan kode dan alasannya. Anda dapat menemukan informasi selengkapnya tentang kode kesalahan

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

• direction: Mengembalikan yang string mewakili arah panggilan. Properti dapat memiliki salah satu nilai berikut: "Masuk' atau Outgoing.

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

• isMuted: Mengembalikan Boolean nilai yang mewakili status bisu lokal.

const muted = call.isMuted;

• isScreenSharingOn: Mengembalikan Boolean nilai true jika Anda mengirim aliran berbagi layar ke peserta lain.

const isScreenSharingOn = call.isScreenSharingOn;

• localVideoStreams: Mengembalikan kumpulan LocalVideoStream objek, mewakili aliran video yang dikirim ke peserta jarak jauh.

const localVideoStreams = call.localVideoStreams;

Mengelola utas obrolan

Menyediakan ID obrolan adalah wajib untuk melakukan panggilan grup dan menambahkan peserta ke panggilan yang ada. Obrolan dan panggilan terkait memiliki daftar peserta terpisah. Sebelum menambahkan peserta ke panggilan, tambahkan pengguna ke obrolan untuk memberikan pengalaman pengguna terbaik dan memenuhi persyaratan penghalang informasi. Menambahkan pengguna ke panggilan tanpa menambahkan pengguna ke obrolan dapat mengakibatkan pengecualian jika hambatan informasi disiapkan.

Pertimbangkan skenario berikut, di mana Alice melakukan panggilan ke Bob, lalu Alice menambahkan Charlie, dan 3 menit kemudian, Alice menghapus Charlie dari panggilan.

  1. Buat utas obrolan antara Alice, Bob dan Charlie. Terus chatting threadId untuk nanti.
  2. Alice memanggil Bob dan Charlie menggunakan startCall metode pada TeamsCallAgent instans.
  3. Menambahkan Dan ke utas obrolan dengan threadId menggunakan Chat Graph API untuk menambahkan anggota
  4. Alice menambahkan Dan ke panggilan menggunakan addParticipant metode pada call dan menentukan threadId
  5. Alice menghapus Dan dari panggilan menggunakan removeParticipant metode pada call dan menentukan threadId
  6. Menghapus Dan dari utas obrolan dengan threadId menggunakan Chat Graph API untuk menghapus anggota

Jika pengguna Teams berhenti merekam panggilan, rekaman ditempatkan ke dalam obrolan yang terkait dengan utas. ID obrolan yang disediakan memengaruhi pengalaman pengguna Teams di klien Teams.

Rekomendasi untuk manajemen ID obrolan:

  • Eskalasi panggilan telepon 1:1 dengan menambahkan peserta telepon lain: Gunakan Graph API untuk mendapatkan ID obrolan yang ada hanya dengan pengguna Teams sebagai peserta atau membuat obrolan grup baru dengan peserta: ID pengguna Teams dan "000000000-0000-0000-0000-00000000000000000000000000000000000000000000000000000
  • Panggilan grup dengan pengguna Teams tunggal dan beberapa peserta telepon: Gunakan Graph API untuk mendapatkan ID obrolan yang ada hanya dengan pengguna Teams sebagai peserta atau buat obrolan grup baru dengan peserta: ID pengguna Teams dan "00000000-0000-0000-0000-0000000000000000"
  • Panggilan grup dengan lebih dari 2 pengguna Teams: Gunakan Graph API untuk mendapatkan atau membuat obrolan grup dengan pengguna Teams