Správa volání pro uživatele Teams pomocí sady SDK pro volání komunikačních služeb

Zjistěte, jak spravovat volání pomocí sady SDK služby Azure Communication Services. Naučíme se, jak zavolat, spravovat jejich účastníky a vlastnosti.

Požadavky

• Účet Azure s aktivním předplatným. Vytvoření účtu zdarma
• Nasazený prostředek komunikační služby. Vytvořte prostředek komunikační služby.
• A User Access Token , aby bylo možné povolit klienta volání. Další informace o tom, jak získat User Access Token
• Volitelné: Dokončení rychlého startu pro zahájení přidávání videohovorů do aplikace

Nainstalujte sadu SDK .

npm install Pomocí příkazu nainstalujte volání služby Azure Communication Services a běžné sady SDK pro JavaScript.

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

Inicializace požadovaných objektů

Vytvořte CallClient instanci, která zahájí volání zásobníku. Protokolování volání sady SDK můžete nakonfigurovat pomocí AzureLogger instance a setLogLevel metody. Pomocí metody getDeviceManagermůžete získat přístup k deviceManager operačnímu systému .

Pak pomocí metody createTeamsCallAgent vytvořte asynchronně TeamsCallAgent instanci, která bude spravovat příchozí a odchozí hovory pro uživatele Teams. Metoda přebírá CommunicationTokenCredential jako argument představující přístupový token pro uživatele 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();

Volání

Spusťte synchronní volání 1:1 nebo skupin pomocí startCall rozhraní API na .teamsCallAgent Můžete zadat MicrosoftTeamsUserIdentifier nebo PhoneNumberIdentifier jako parametr definovat cíl volání. Metoda vrátí TeamsCall instanci, která umožňuje přihlásit se k odběru událostí volání.

Poznámka:

Zahájení skupinového hovoru vyžaduje teamsCallAgent chat threadId při volání startCall metody. Vytvořená TeamsCall instance má vlastnost threadId zachytávání tohoto vlákna. Sada SDK pro volání komunikačních služeb neudržuje účastníky v chatu a seznamu volání synchronizovaných. Microsft doporučuje vývojářům udržovat seznam synchronizovaný, aby měli co nejlepší uživatelské prostředí. Zjistěte, jak spravovat vlákno chatu.

Spusťte hovor s 1:1 hlasovou IP adresou (VoIP) uživatelem Teams:

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

Zahájení telefonního hovoru 1:164 na telefonní číslo E.164:

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

Zahájení skupinového hovoru s uživatelem Teams s ip adresou voice-over (VoIP) a telefonním číslem:

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

Připojení k hovoru

Připojení ke schůzce Teams

Ke schůzkám Teams se můžete připojit pomocí metody join v teamsCallAgent instanci. Uživatelé Teams se můžou ke schůzce Teams připojit zadáním nebo TeamsMeetingLinkLocatorTeamsMeetingCoordinatesLocatorTeamsMeetingIdLocator.

Připojte se ke schůzce Teams pomocí adresy URL schůzky:

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

Připojte se ke schůzce Teams pomocí kombinace ID vlákna, ID organizátora, ID tenanta a ID zprávy:

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

Připojte se ke schůzce v Teams pomocí kódu schůzky a hesla:

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

Připojte se ke schůzce Teams pomocí ID schůzky a hesla:

Vývojáři můžou účastníky připojit ke schůzce v Teams několika způsoby. Jedním zezpůsobůchm kódům je použití ID schůzky a hesla, které uživatelům umožní připojit se ke schůzce Teams, ke které jsou pozvaní ze zařízení nebo aplikace. Pro připojení ke schůzce musíte vždy zadat ID schůzky i heslo. U hesla se rozlišují malá a velká písmena.

• Formát ID schůzky a hesla:

  • ID schůzky: 12 číslic.
  • Heslo: 6 znaků

• Jak často potřebujete aktualizovat ID schůzky a heslo?

  • ID schůzky a heslo se po vytvoření nezmění. Vývojáři nemusí aktualizovat ani jeden.
  • Organizátor schůzky Teams nemůže znovu vygenerovat ID a heslo schůzky.

• Existuje nějaký rozdíl v prostředí schůzky v Teams, pokud se někdo připojí přes adresu URL nebo ID schůzky a heslo?

  • Ne, účastníci mají stejné prostředí, pokud se připojí ke schůzce Teams pomocí adresy URL schůzky Teams nebo ID schůzky a hesla.

• Jak by vývojáři měli ukládat a spravovat hesla?

  • ID schůzky a heslo jsou souřadnice pro připojení ke schůzce. Vývojáři by je měli považovat za tajné kódy, které by se měly šifrovat, a pokud se ukládají, ujistěte se, že jsou v prostředí řízeném přístupem.
  • Pokud jsou souřadnice vystavené, může se ke schůzce připojit kdokoli a zničit prostředí pro všechny účastníky schůzky.

• Jak získat ID schůzky a heslo?

  1. Graph API: Použití rozhraní Graph API k načtení informací o onlineMeeting prostředku a kontrole objektu ve vlastnosti joinMeetingIdSettings.
  2. Teams: V aplikaci Teams přejděte do Calendar aplikace a otevřete podrobnosti o schůzce. Online schůzky mají ID schůzky a heslo v definici schůzky.
  3. Outlook: ID schůzky a heslo najdete v událostech kalendáře nebo v e-mailových pozvánkách na schůzku.
  4. Vývojáři nemůžou načíst ID schůzky a heslo prostřednictvím volání sady SDK nebo ho načíst z podrobných protokolů konzoly.

• Jak můžu ověřit, jestli je ID schůzky a heslo správné?

  • Id schůzky a ověření hesla je možné provést prostřednictvím: https://www.microsoft.com/en-us/microsoft-teams/join-a-meeting.

Přijetí příchozího hovoru v Teams

Můžete se přihlásit k odběru incomingCall události v teamsCallAgent instanci a zaregistrovat příchozí hovory pro uživatele Teams. Událost má teamsIncomingCall vlastnost s TeamsIncomingCall instancí, která umožňuje příchozí accept hovor nebo reject příchozí hovor.

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

Povolení a zakázání videa

Místní kolekci streamů videa můžete získat z vlastnosti localVideoStreams v TeamsCall instanci. Pokud je tato možnost povolená, kolekce obsahuje stream sdílení obrazovky a kanály videa z fotoaparátu. Streamy videa vzdálených účastníků můžete získat kontrolou vlastnosti TeamsCall.remoteParticipants kde každý účastník má kolekci video streamů ve vlastnosti videoStreams.

Vypnutí a zapnutí zvuku

Pomocí a unmute asynchronních rozhraní API v TeamsCall instanci můžete mute ztlumit nebo zrušit ztlumení uživatelů Teams místně. Místní ztlumení zabrání odesílání zvuku ostatním účastníkům.

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

Ztlumení ostatních účastníků

Pokud chcete ztlumit všechny ostatní účastníky nebo ztlumit konkrétního účastníka, můžete použít asynchronní rozhraní API muteAllRemoteParticipants pro volání a mute vzdáleného účastníka:

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

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

Poznámka:

Toto rozhraní API se poskytuje jako verze Preview pro vývojáře a může se změnit na základě zpětné vazby, kterou dostaneme. Nepoužívejte toto rozhraní API v produkčním prostředí. Pokud chcete použít toto rozhraní API, použijte beta verzi webové sady SDK pro volání služeb Azure Communication Services.

Správa vzdálených účastníků

Ostatní účastníci hovoru jsou k dispozici v TeamsCall instanci pod vlastností remoteParticipants. Jedná se o kolekci RemoteParticipant objektů. Z hovoru můžete vypsat, přidat a odebrat další účastníky.

Poznámka:

Přidání metody účastníka vyžaduje chat threadId. Sada SDK pro volání komunikačních služeb neudržuje účastníky v chatu a seznamu volání synchronizovaných. Microsft doporučuje vývojářům udržovat seznam synchronizovaný, aby měli co nejlepší uživatelské prostředí. Zjistěte, jak spravovat vlákno chatu.

Do hovoru nebo schůzky Teams můžete přidat nového uživatele nebo telefonní číslo Teams voláním metody addParticipant na objektu TeamsCall. Metoda přijímá identifikátory MicrosoftTeamsUserIdentifier nebo PhoneNumberIdentifier jako vstup a vrací synchronně instanci RemoteParticipant a aktivuje událost remoteParticipantsUpdated v TeamsCall instanci.

Účastníka můžete odebrat z hovoru v Teams nebo ze schůzky Teams tak, že metodu removeParticipant vyvoláte v TeamsCall instanci asynchronně. Metoda přijímá identifikátory MicrosoftTeamsUserIdentifier nebo PhoneNumberIdentifier jako vstup. Metoda je vyřešena při RemoteParticipant odebrání z remoteParticipants kolekce a událost remoteParticipantsUpdated v TeamsCall instanci se aktivuje.

Uveďte další účastníky hovoru:

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

Přidejte uživatele a telefonní číslo Teams do hovoru v Teams nebo ke schůzce 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>' });

Odebrání uživatele a telefonního čísla Teams z hovoru v Teams nebo schůzky Teams:

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

Vzdálení účastníci

Vzdálení účastníci představují koncový bod připojený k probíhajícímu hovoru v Teams nebo ke schůzce Teams. remoteParticipant Třída má následující sadu vlastností a kolekcí:

• identifier: Vrátí jeden z následujících identifikátorů: CommunicationUserIdentifier, MicrosoftTeamsUserIdentifier, PhoneNumberIdentifiernebo UnknownIdentifier.

const identifier = remoteParticipant.identifier;

• state: Vrátí string stav vzdáleného účastníka. Stav může mít jednu z následujících hodnot:

Hodnota stavu	Když	Popis
Idle	Počáteční stav	Toto je první stav účastníka.
Connecting	Po datu Idle	Stav přechodu, když se účastník připojuje k hovoru.
Ringing	Po datu Connecting	Účastník obdržel incomingCall oznámení nebo klient Teams vyzvání
Connected	Za Ringing, Connecting, EarlyMedianebo InLobby	Účastník přijal pozvánku na hovor nebo se připojil k hovoru. Média proudí k účastníkovi.
Hold	Po datu Connected	Účastník hovoru je přidržený.
EarlyMedia	Po datu Connecting	Multimédia se přehrají před tím, než se účastník připojí k hovoru.
InLobby	Connecting Po Ringing, neboEarlyMedia	Účastník je v předsálí schůzky Teams.
Disconnected	Koncový stav	Účastník se od hovoru odpojí. Pokud vzdálený účastník ztratí připojení k síti, změní se stav po Disconnected dvou minutách.

Stavy vzdálených účastníků při volání 1:1 nebo skupině:

Stavy vzdálených účastníků schůzek v Teams:

const state = remoteParticipant.state;

• callEndReason: Vrátí objekt obsahující další informace o důvodu ukončení volání. Vlastnost code vrátí číslo přidružené k důvodu a subCode vrátí číslo přidružené ke kódu a důvod. Další informace o kódech chyb najdete v tématu Řešení potíží s kódy koncových odpovědí volání.

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

• isMuted: Vrátí Boolean hodnotu představující stav místního ztlumení.

const isMuted = remoteParticipant.isMuted;

• isSpeaking: Vrátí Boolean hodnotu představující stav neodesílaného zvuku.

const isSpeaking = remoteParticipant.isSpeaking;

• videoStreams: Vrátí kolekci RemoteVideoStream objektů odeslaných účastníky.

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

• displayName: Vrátí zobrazovaný string název. Sada SDK pro volání komunikačních služeb nenastavuje tuto hodnotu pro uživatele Teams.

const displayName = remoteParticipant.displayName;

Call

• id: Vrátí řetězec představující jedinečný identifikátor volání.

const callId = call.id;

• info: Vrátí informace o volání:

Poznámka:

Toto rozhraní API se poskytuje jako verze Preview pro vývojáře a může se změnit na základě zpětné vazby, kterou dostaneme. Nepoužívejte toto rozhraní API v produkčním prostředí. Pokud chcete toto rozhraní API použít, použijte beta verzi webové sady SDK pro volání služeb Azure Communication Services.

• info: Vrátí objekt obsahující informace o volání. Vlastnost threadId je řetězec představující ID vlákna chatu zobrazeného v klientovi Teams.

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

• remoteParticipants: Vrátí kolekci remoteParticipant objektů představujících ostatní účastníky hovoru v Teams nebo ve schůzce Teams.

const remoteParticipants = call.remoteParticipants;

• callerInfo: Vrátí CallerInfo objekt pro příchozí volání. Vlastnost identifier může být jeden z následujících objektů CommunicationUserIdentifier, MicrosoftTeamsUserIdentifier, PhoneNumberIdentifier, nebo UnknownIdentifier. Vlastnost displayName je řetězec představující název, který se má zobrazit, pokud je nastaven.

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

• state: Vrátí řetězec představující stav volání. Vlastnost může mít jednu z následujících hodnot:

Hodnota stavu	Když	Popis
None	Počáteční stav	Počáteční stav volání.
Connecting	Po datu None	Stav, kdy se umístí hovor přes Teams nebo schůzka Teams, připojí se nebo přijme.
Ringing	Po datu Connecting	Vzdálený účastník obdržel incomingCall událost nebo klient Teams vyzvání.
EarlyMedia	Za nebo po RingingConnecting	Médium se přehraje před připojením hovoru.
Connected	Po Ringing, EarlyMedia, InLobby, LocalHolda RemoteHold	Hovor je připojený. Média proudí mezi místními koncovými body a vzdálenými účastníky.
LocalHold	Po datu Connected	Hovor byl přidržen místním účastníkem. Mezi místním koncovým bodem a vzdálenými účastníky neprotékají žádná média.
RemoteHold	Po datu Connected	Hovor byl přidržen vzdáleným účastníkem. Mezi místním koncovým bodem a vzdálenými účastníky neprotékají žádná média.
InLobby	Za nebo po RingingConnecting	Vzdálený účastník je v předsálí schůzky Teams. Mezi místním koncovým bodem a vzdálenými účastníky neprotékají žádná média.
Disconnecting	Po jakémkoli stavu	Stav přechodu před voláním Disconnected přejde do stavu.
Disconnected	Koncový stav	Konečný stav volání. Pokud dojde ke ztrátě síťového připojení, stav se změní na Disconnected po dvou minutách.

Stavy pro volání 1:1 nebo skupiny:

Stavy schůzek v Teams:

const callState = call.state;

• callEndReason: Vrátí objekt CallEndReason obsahující další informace o ukončení volání. Vlastnost code vrátí číslo přidružené k důvodu a subCode vrátí číslo přidružené ke kódu a důvod. Další informace o kódech chyb najdete v tématu Řešení potíží s kódy koncových odpovědí volání.

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

• direction: Vrátí string směr volání. Vlastnost může mít jednu z následujících hodnot: Příchozí nebo Outgoing.

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

• isMuted: Vrátí Boolean hodnotu představující stav místního ztlumení.

const muted = call.isMuted;

• isScreenSharingOn: Vrátí Boolean hodnotu true, pokud posíláte stream sdílení obrazovky ostatním účastníkům.

const isScreenSharingOn = call.isScreenSharingOn;

• localVideoStreams: Vrátí kolekci LocalVideoStream objektů představujících streamy videa, které se odesílají vzdáleným účastníkům.

const localVideoStreams = call.localVideoStreams;

Spravovat vlákno chatu

Důležité

Volitelné ID chatu je k dispozici pouze ve verzi 1.29.1 nebo novější v sadě SDK pro volání pro JavaScript. Pokud používáte starší verzi, ujistěte se, že zadáte jedinečné ID chatu ručně.

Poskytnutí ID chatu je volitelné pro skupinové hovory a přidání účastníků do stávajících hovorů. Přidružený chat a hovor mají samostatný seznam účastníků. Před přidáním účastníků do hovoru přidejte uživatele do chatu, abyste zajistili co nejlepší uživatelské prostředí a splňovali požadavky na informační bariéru. Přidání uživatele do hovoru bez přidání uživatele do chatu může vést k výjimkám, pokud je nastavena informační bariéra.

Představte si následující scénář, kdy Alice zavolá Bobovi, pak Alice přidá Charlieho a o 3 minuty později Alice z hovoru odebere Charlieho.

1. Vytvořte chatovací vlákno mezi Alicí, Bobem a Charliem. Nechte chat threadId pro pozdější použití.
2. Alice volá Boba a Charlieho pomocí startCall metody v TeamsCallAgent instanci.
3. Přidání dana do vlákna chatu pomocí threadId rozhraní Graph API chatu pro přidání člena
4. Alice přidá Dana do volání pomocí addParticipant metody on call a určí threadId
5. Alice odebere Dana z volání pomocí removeParticipant metody on call a určuje threadId
6. Odebrání dana z vlákna chatu pomocí threadId rozhraní Graph API chatu k odebrání člena

Pokud uživatel Teams zastaví nahrávání hovorů, nahrávka se umístí do chatu přidruženého k vláknu. Zadané ID chatu má vliv na prostředí uživatelů Teams v klientech Teams.

Doporučení pro správu ID chatu:

• Eskalace telefonního hovoru 1:1 přidáním dalšího účastníka telefonu:
  • Metoda addParticipant umožňuje zadat volitelné ID chatu parametru. Pokud parametr není zadaný, vytvoří se nový skupinový chat a všichni účastníci se přidají do seznamu účastníků hovoru a chatu. Pokud je parametr zadaný, uživatelé Teams uvidí probíhající volání přidružené k tomuto skupinovému chatu v aplikaci Teams. Pomocí rozhraní Graph API můžete vytvořit nový skupinových chatů.

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

• Zahájení skupinového hovoru s jedním uživatelem Microsoftu 365 a více účastníky telefonu:
  • Rozhraní API metody startCall umožňuje zahájit skupinové volání s více účastníky a volitelně zadat ID chatu. Pokud parametr není zadaný, vytvoří se nový skupinový chat a všichni účastníci Microsoftu 365 se přidají do seznamu účastníků hovoru a chatu. Pokud je parametr zadaný, uživatelé Teams uvidí probíhající volání přidružené k tomuto skupinovému chatu v aplikaci Teams. Pomocí rozhraní Graph API můžete vytvořit nový skupinových chatů.

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

  • Rozhraní Graph API umožňuje získat existující ID chatu jenom s uživatelem Teams jako účastníkem nebo vytvořit nový skupinový chat s účastníky: ID uživatele Teams a "0000000-0000-0000-0000-0000000000000".
• Zahájení skupinového hovoru s více než 2 uživateli Microsoftu 365:
  • (Volitelný způsob) Při skupinovém volání s více než 2 uživateli Microsoftu 365 pomocí sady SDK pro volání služby ACS sada SDK automaticky vytvoří vlákno ve výchozím nastavení.

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

  • V případě potřeby může vývojář poskytnout jedinečné ID chatu, které zahájí skupinový hovor nebo přidá účastníky. V tomto případě sada SDK pro volání služby ACS použije dané ID chatu k vytvoření skupinového volání. Vytvoří se vlákno chatu pro uživatele Teams a toto vlákno je přidružené ke skupinovému volání pro uživatele v aplikaci Teams. To jim umožní chatovat během hovoru. Správu vláken chatu je možné provádět prostřednictvím rozhraní Graph API.