İletişim Hizmetleri çağrı SDK'sı ile Teams kullanıcıları için çağrıları yönetme

Azure İletişim Hizmetleri SDKS ile çağrıları yönetmeyi öğrenin. Arama yapmayı, katılımcılarını ve özelliklerini yönetmeyi öğreneceğiz.

Önkoşullar

• Etkin aboneliği olan bir Azure hesabı. Ücretsiz hesap oluşturun.
• Dağıtılan bir İletişim Hizmetleri kaynağı. İletişim Hizmetleri kaynağı oluşturun.
• Çağrı istemcisini etkinleştirmek için A User Access Token . Alma hakkında daha fazla bilgi için User Access Token
• İsteğe bağlı: Uygulamanıza görüntülü arama eklemeye başlamak için hızlı başlangıcı tamamlayın

SDK’yı yükleyin

npm install JavaScript için Azure İletişim Hizmetleri çağrısını ve yaygın SDK'ları yüklemek için komutunu kullanın.

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

Gerekli nesneleri başlatma

Çağrı yığınını başlatmak için bir CallClient örnek oluşturun. Çağrı SDK'sının günlüğe kaydedilmesini AzureLogger örneği ve setLogLevel yöntemiyle yapılandırabilirsiniz. yöntemiyle getDeviceManagerişletim sistemi için öğesine erişebilirsinizdeviceManager.

Ardından yöntemini createTeamsCallAgent kullanarak Bir Teams kullanıcısı için gelen ve giden çağrıları yönetecek bir örneği zaman uyumsuz olarak TeamsCallAgent oluşturun. yöntemi, Teams kullanıcısı için erişim belirtecini temsil eden bir bağımsız değişken olarak alırCommunicationTokenCredential.

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

Arama yerleştirme

üzerinde teamsCallAgentAPI ile startCall zaman uyumlu bire bir veya grup çağrısı başlatın. Çağrının hedefini tanımlamak için veya parametresi olarak sağlayabilirsiniz MicrosoftTeamsUserIdentifier PhoneNumberIdentifier . yöntemi, çağrı olaylarına abone olmanıza olanak tanıyan örneği döndürür TeamsCall .

Teams kullanıcısına bire bir Seslendirme IP'sini (VoIP) başlatın:

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

E.164 telefon numarasına bire bir telefon araması başlatın:

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

Voice-over IP (VoIP) ve telefon numarası ile Teams kullanıcısına grup araması başlatın:

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

Aramaya katılma

Teams toplantısına katılma

Teams toplantılarına örnekteki yöntemiyle join teamsCallAgent katılabilirsiniz. Teams kullanıcıları, bir TeamsMeetingLinkLocator, TeamsMeetingCoordinatesLocatorveya TeamsMeetingIdLocatorsağlayarak Teams toplantısına katılabilir.

Toplantı URL'si ile Teams toplantısına katılın:

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

İş parçacığı kimliği, düzenleyici kimliği, kiracı kimliği ve ileti kimliği birleşimiyle Teams toplantısına katılın:

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

Toplantı kodu ve geçiş koduyla Teams toplantısına katılın:

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

Toplantı kimliği ve geçiş koduyla Teams toplantısına katılın:

Geliştiriciler, katılımcıları teams toplantısına birden çok yolla bağlayabilir. Bunun bir yolu, kişilerin bir cihazdan veya uygulamadan davet edildikleri Teams toplantısına katılmasını sağlayan bir toplantı kimliği ve geçiş kodu kullanmaktır. Toplantıya katılmak için her zaman hem toplantı kimliğini hem de geçiş kodunu sağlamanız gerekir. Geçiş kodu büyük/küçük harfe duyarlıdır.

• Toplantı kimliğinin ve geçiş kodunun biçimi:

  • Toplantı kimliği: 12 basamak.
  • Geçiş kodu: 6 karakter

• Toplantı kimliğini ve geçiş kodunu ne sıklıkta yenilemeniz gerekir?

  • Toplantı kimliği ve geçiş kodu oluşturulduktan sonra değişmez. Geliştiricilerin ikisini de yenilemesi gerekmez.
  • Teams toplantı düzenleyicisi, toplantı kimliğini ve geçiş kodunu yeniden oluşturamaz.

• Bir kişinin URL veya toplantı kimliği ve geçiş kodu aracılığıyla katılması durumunda Teams toplantı deneyiminde herhangi bir fark var mı?

  • Hayır, katılımcılar Teams toplantısı URL'sini veya toplantı kimliğini ve geçiş kodunu kullanarak teams toplantısına katılırlarsa aynı deneyime sahip olur.

• Geliştiriciler geçiş kodlarını nasıl depolamalı ve yönetmelidir?

  • Toplantı kimliği ve geçiş kodu, toplantıya katılma koordinatlarıdır. Geliştiriciler bunları şifrelenmesi gereken gizli diziler olarak ele almalıdır ve depolanırsa erişim denetimli bir ortamda olduklarından emin olun.
  • Koordinatlar açığa çıkarsa, herkes toplantıya katılabilir ve toplantıdaki herkesin deneyimini mahvedebilir.

• Toplantı kimliği ve geçiş kodu nasıl alınabilir?

  1. Graph API: Kaynak hakkındaki onlineMeeting bilgileri almak ve özelliğindeki joinMeetingIdSettingsnesneyi denetlemek için Graph API'sini kullanın.
  2. Teams: Teams uygulamanızda uygulamaya gidin Calendar ve toplantının ayrıntılarını açın. Çevrimiçi toplantılar, toplantının tanımında toplantı kimliğine ve geçiş koduna sahiptir.
  3. Outlook: Toplantı kimliğini ve geçiş kodunu takvim olaylarında veya e-posta toplantı davetlerinde bulabilirsiniz.
  4. Geliştiriciler, çağrı SDK'sı aracılığıyla toplantı kimliğini ve geçiş kodunu alamaz veya ayrıntılı konsol günlüklerinden alamaz.

• Toplantı kimliğinin ve geçiş kodunun doğru olduğunu nasıl doğrulayabilirim?

  • MeetingId ve geçiş kodu doğrulaması şu şekilde yapılabilir: https://www.microsoft.com/en-us/microsoft-teams/join-a-meeting.

Teams gelen aramasını alma

Teams kullanıcısına incomingCall gelen aramaları kaydetmek için örnekteki etkinliğe teamsCallAgent abone olabilirsiniz. Olay, size veya reject gelen çağrıya accept izin veren örneğe sahip TeamsIncomingCall bir teamsIncomingCall özelliğe sahiptir.

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

Video etkinleştirme ve devre dışı bırakma

Örnekteki özelliğinden localVideoStreams TeamsCall yerel video akışı koleksiyonunuzu alabilirsiniz. Etkinleştirilirse, koleksiyon bir ekran paylaşım akışı ve kamera video akışları içerir. özelliğini TeamsCallinceleyerek uzak katılımcıların video akışlarını alabilirsiniz.remoteParticipants burada her katılımcı özelliğinde videoStreamsbir video akışları koleksiyonuna sahiptir.

Sesi kapatma ve açma

Teams kullanıcılarının sesini yerel olarak kapatmak veya açmak için örnekte zaman uyumsuz API'ler TeamsCall kullanabilirsiniz.mute unmute Yerel sessiz, sesin diğer katılımcılara gönderilmesini engeller.

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

Diğer katılımcıların sesini kapatma

Diğer tüm katılımcıların sesini kapatmak veya belirli bir katılımcının sesini kapatmak için, aramada ve mute uzak katılımcıda zaman uyumsuz API'leri muteAllRemoteParticipants kullanabilirsiniz:

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

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

Uzak katılımcıları yönetme

Diğer çağrı katılımcıları, örneğinde TeamsCall özelliğinin remoteParticipantsaltında bulunur. Bu bir nesne koleksiyonu.RemoteParticipant Aramadaki diğer katılımcıları listeleyebilir, ekleyebilir ve kaldırabilirsiniz.

nesnesinde TeamsCallyöntemini addParticipant çağırarak Teams çağrısına veya Teams toplantısına yeni Teams kullanıcı veya telefon numarası ekleyebilirsiniz. yöntemi, tanımlayıcıları MicrosoftTeamsUserIdentifier veya PhoneNumberIdentifier giriş olarak kabul eder ve örneği zaman uyumlu olarak döndürür ve örnekte RemoteParticipant olayı remoteParticipantsUpdated TeamsCall tetikler.

Bir katılımcıyı Teams çağrısından veya Teams toplantısından kaldırmak için örnekteki yöntemi TeamsCall zaman uyumsuz olarak çağırabilirsinizremoveParticipant. yöntemi, tanımlayıcıları veya PhoneNumberIdentifier giriş olarak kabul ederMicrosoftTeamsUserIdentifier. yöntemi koleksiyondan remoteParticipants kaldırıldığında RemoteParticipant çözümlenir ve örnekteki TeamsCall olay remoteParticipantsUpdated tetiklenir.

Diğer arama katılımcılarını listeleyin:

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

Teams aramasına veya Teams toplantısına Teams kullanıcı ve telefon numarası ekleyin:

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 aramasından veya Teams toplantısından Teams kullanıcı ve telefon numarasını kaldırın:

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

Uzak katılımcılar

Uzak katılımcılar, devam eden Teams çağrısına veya Teams toplantısına bağlı bir uç noktayı temsil eder. sınıfı remoteParticipant aşağıdaki özellik ve koleksiyon kümesine sahiptir:

• identifier: Şu tanımlayıcılardan birini döndürür: CommunicationUserIdentifier, MicrosoftTeamsUserIdentifier, PhoneNumberIdentifierveya UnknownIdentifier.

const identifier = remoteParticipant.identifier;

• state: Uzak katılımcının string durumunu temsil eden bir döndürür. Durum aşağıdaki değerlerden birine sahip olabilir:

Bire bir veya grup çağrılarındaki uzak katılımcıların durumları:

Teams toplantılarındaki uzak katılımcıların durumları:

const state = remoteParticipant.state;

• callEndReason: Çağrının sona erme nedeni hakkında ek bilgi içeren bir nesne döndürür. Özellik code , nedenle ilişkili bir sayı döndürür ve subCode kodla ve nedenle ilişkili bir sayı döndürür. Hata kodları hakkında daha fazla bilgi için bkz . Arama sonu yanıt kodlarıyla ilgili sorunları giderme.

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

• isMuted: Yerel sessiz durumunu temsil eden değeri döndürür Boolean .

const isMuted = remoteParticipant.isMuted;

• isSpeaking: Gönderilmekte olan sesin durumunu temsil eden değeri döndürür Boolean .

const isSpeaking = remoteParticipant.isSpeaking;

• videoStreams: Katılımcılar tarafından gönderilen nesnelerin koleksiyonunu RemoteVideoStream döndürür.

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

• displayName: Temsil eden bir string görünen ad döndürür. İletişim Hizmetleri çağrı SDK'sı, Teams kullanıcıları için bu değeri ayarlamaz.

const displayName = remoteParticipant.displayName;

Call

• id: Benzersiz bir çağrı tanımlayıcısını temsil eden bir dize döndürür.

const callId = call.id;

• info: Arama hakkındaki bilgileri döndürür:

• info: Çağrı hakkında bilgi içeren nesneyi döndürür. özelliği threadId , Teams istemcisinde gösterilen sohbetin yazışma kimliğini temsil eden bir dizedir.

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

• remoteParticipants: Teams çağrısındaki veya Teams toplantısındaki diğer katılımcıları temsil eden bir nesne koleksiyonu remoteParticipant döndürür.

const remoteParticipants = call.remoteParticipants;

• callerInfo: Gelen çağrılar CallerInfo için nesneyi döndürür. özelliği identifier aşağıdaki nesnelerden CommunicationUserIdentifierbiri olabilir: , MicrosoftTeamsUserIdentifier, PhoneNumberIdentifierveya UnknownIdentifier. özelliği displayName , ayarlanırsa görüntülenecek adı temsil eden bir dizedir.

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

• state: Çağrının durumunu temsil eden bir dize döndürür. özelliği aşağıdaki değerlerden birine sahip olabilir:

Bire bir veya grup çağrıları için durumlar:

Teams toplantıları için durumlar:

const callState = call.state;

• callEndReason: Çağrının sona ermiş olduğu hakkında ek bilgi içeren nesneyi CallEndReason döndürür. özelliği code , nedeni ile ilişkilendirilmiş bir sayı döndürür ve subCode kodla ve nedenle ilişkilendirilmiş bir sayı döndürür. Hata kodları hakkında daha fazla bilgi için bkz . Arama sonu yanıt kodlarıyla ilgili sorunları giderme.

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

• direction: Çağrının yönünü temsil eden bir string döndürür. özelliği şu değerlerden birine sahip olabilir: "Gelen' veya Outgoing.

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

• isMuted: Yerel sessiz durumunu temsil eden değeri döndürür Boolean .

const muted = call.isMuted;

• isScreenSharingOn: Ekran paylaşımı akışını diğer katılımcılara gönderiyorsanız true değerini döndürür Boolean .

const isScreenSharingOn = call.isScreenSharingOn;

• localVideoStreams: Uzak katılımcılara gönderilen video akışlarını temsil eden bir nesne koleksiyonu LocalVideoStream döndürür.

const localVideoStreams = call.localVideoStreams;

Sohbet yazışmalarını yönetme

Sohbet kimliği sağlamak, grup aramaları yapmak ve mevcut aramalara katılımcı eklemek için isteğe bağlıdır. İlişkili sohbet ve aramanın ayrı bir katılımcı listesi vardır. Aramaya katılımcı eklemeden önce kullanıcıyı sohbete ekleyerek en iyi kullanıcı deneyimini sağlayın ve bilgi engeli gereksinimlerini karşılayın. Kullanıcıyı sohbete eklemeden aramaya kullanıcı eklemek, bir bilgi engeli ayarlanırsa özel durumlara neden olabilir.

Alice'in Bob'a çağrı yaptığı, ardından Alice'in Charlie'yi eklediği ve 3 dakika sonra Alice'in Charlie'yi aramadan kaldırdığı aşağıdaki senaryoyu düşünün.

1. Alice, Bob ve Charlie arasında bir sohbet yazışması oluşturun. Sohbeti threadId daha sonraya bırakın.
2. Alice, örneğinde yöntemini kullanarak startCall Bob ve Charlie'yi TeamsCallAgent çağırır.
3. Üye eklemek için Sohbet Grafı API'sini kullanarak sohbet yazışmasına threadId Dan ekleme
4. Alice, yöntemini call kullanarak addParticipant Çağrıya Dan ekler ve öğesini belirtirthreadId
5. Alice, üzerinde call yöntemini kullanarak removeParticipant Dan'i çağrısından kaldırır vethreadId
6. Üyeyi kaldırmak için Sohbet Grafı API'sini kullanarak Dan'i sohbet yazışmasından threadId kaldırma

Teams kullanıcısı arama kaydını durdurursa, kayıt yazışmayla ilişkilendirilmiş sohbete yerleştirilir. Sağlanan sohbet kimliği, Teams istemcilerindeki Teams kullanıcılarının deneyimini etkiler.

Sohbet kimliğinin yönetimi için öneriler:

• Başka bir telefon katılımcısı ekleyerek 1:1 telefon aramasının ilerletilmesi:
  • Yöntemi addParticipant , isteğe bağlı parametre sohbet kimliği sağlamanıza olanak tanır. Parametre sağlanmazsa yeni bir grup sohbeti oluşturulur ve tüm katılımcılar arama ve sohbet katılımcıları listesine eklenir. Parametre sağlanmışsa, Teams kullanıcıları Teams uygulamasında bu grup sohbeti ile ilişkili devam eden çağrıyı görebilir. Graph API aracılığıyla yeni grup sohbeti oluşturabilirsiniz.

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

• Tek Bir Microsoft 365 kullanıcısı ve birden çok telefon katılımcısı ile grup araması başlatın:
  • Yöntem API'si startCall , birden çok katılımcıyla grup araması başlatmanıza ve isteğe bağlı olarak sohbet kimliği sağlamanıza olanak tanır. Parametre sağlanmazsa yeni bir grup sohbeti oluşturulur ve tüm Microsoft 365 katılımcıları arama ve sohbet katılımcıları listesine eklenir. Parametre sağlanmışsa, Teams kullanıcıları Teams uygulamasında bu grup sohbeti ile ilişkili devam eden çağrıyı görebilir. Graph API aracılığıyla yeni grup sohbeti oluşturabilirsiniz.

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

  • Katılımcı olarak yalnızca Teams kullanıcısıyla mevcut sohbet kimliğini almak veya katılımcılarla yeni bir grup sohbeti oluşturmak için Graph API'sini kullanın: Teams kullanıcı kimliği ve "00000000-0000-0000-000000000000".
• 2'den fazla Microsoft 365 kullanıcısı ile grup araması başlatın:
  • (İsteğe bağlı yol) ACS Arama SDK'sını kullanan 2'den fazla Microsoft 365 kullanıcısı olan bir grup araması yaparken SDK, iş parçacığını varsayılan olarak otomatik olarak oluşturur.

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

  • İstenirse, geliştirici grup aramasını başlatmak veya katılımcı eklemek için benzersiz bir sohbet kimliği sağlayabilir. Bu durumda ACS Arama SDK'sı, grup aramasını oluşturmak için verilen sohbet kimliğini kullanır. Teams kullanıcıları için bir sohbet yazışması oluşturulur ve bu yazışma Teams uygulamasındaki kullanıcılar için grup çağrısıyla ilişkilendirilir. Bu, arama sırasında sohbet etmelerini sağlar. Sohbet yazışması yönetimi Graph API aracılığıyla yapılabilir