Hantera anrop för Teams-användare med Communication Services som anropar SDK

Lär dig hur du hanterar samtal med Azure Communication Services SDKS. Vi får lära oss hur du ringer samtal, hanterar deras deltagare och egenskaper.

Förutsättningar

• Ett Azure-konto med en aktiv prenumeration. Skapa ett konto utan kostnad.
• En distribuerad Communication Services-resurs. Skapa en Communication Services-resurs.
• A User Access Token för att aktivera anropsklienten. Mer information om hur du får en User Access Token
• Valfritt: Slutför snabbstarten för att komma igång med att lägga till videosamtal i ditt program

Installera SDK:n

npm install Använd kommandot för att installera Azure Communication Services-anropet och vanliga SDK:er för JavaScript.

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

Initiera nödvändiga objekt

Skapa en CallClient instans för att initiera den anropande stacken. Du kan konfigurera loggning av anropande SDK med instansen AzureLogger och setLogLevel metoden. Du kan få åtkomst till deviceManager för operativsystemet med -metoden getDeviceManager.

Använd sedan metoden createTeamsCallAgent för att skapa asynkront en TeamsCallAgent instans som hanterar inkommande och utgående anrop för en Teams-användare. Metoden tar CommunicationTokenCredential som ett argument som representerar åtkomsttoken för Teams-användare.

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

Ringa ett samtal

Starta ett synkront en-till-en-anrop eller ett gruppanrop med startCall API:et på teamsCallAgent. Du kan ange MicrosoftTeamsUserIdentifier eller PhoneNumberIdentifier som en parameter för att definiera målet för anropet. Metoden returnerar den TeamsCall instans som gör att du kan prenumerera på anropshändelser.

Kommentar

Starta ett gruppsamtal med teamsCallAgent kräver chatt threadId när du anropar startCall metoden. Den skapade TeamsCall instansen har en egenskap threadId som samlar in den här tråden. Communication Services Calling SDK håller inte deltagarna i chatt- och samtalslistan synkroniserade. Microsft uppmuntrar utvecklare att hålla listan synkroniserad för bästa användarupplevelse. Lär dig hur du hanterar chatttråd.

Starta ett 1-till-ett VoIP-anrop (Voice-over IP) till Teams-användare:

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

Starta ett en-till-en-telefonsamtal till E.164-telefonnummer:

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

Starta ett gruppsamtal till Teams-användare med Voice-over IP (VoIP) och telefonnummer:

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

Ansluta till ett samtal

Ansluta till Teams-möte

Du kan ansluta Teams-möten med metoden join på instansen teamsCallAgent . Teams-användare kan ansluta till Teams-mötet genom att tillhandahålla ett TeamsMeetingLinkLocator, TeamsMeetingCoordinatesLocatoreller TeamsMeetingIdLocator.

Delta i Teams-mötet med mötes-URL:

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

Delta i Teams-mötet med en kombination av tråd-ID, organisatörs-ID, klientorganisations-ID och meddelande-ID:

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

Delta i Teams-mötet med möteskod och lösenord:

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

Delta i Teams-möte med mötes-ID och lösenord:

Utvecklare kan ansluta deltagare till ett Teams-möte på flera sätt. Ett sätt är att använda ett mötes-ID och lösenord som gör det möjligt för personer att ansluta till Teams-mötet som de bjuds in till från en enhet eller ett program. Du måste alltid ange både mötes-ID och lösenord för att ansluta till mötet. Lösenord är skiftlägeskänsligt.

• Format för mötes-ID och lösenord:

  • Mötes-ID: 12 siffror.
  • Lösenord: 6 tecken

• Hur ofta behöver du uppdatera mötes-ID och lösenord?

  • Mötes-ID och lösenord ändras inte när de har skapats. Utvecklare behöver inte uppdatera någon av dem.
  • En Teams-mötesorganisatör kan inte återskapa mötes-ID och lösenord.

• Finns det någon skillnad i en Teams-mötesupplevelse om en person ansluter via URL eller mötes-ID och lösenord?

  • Nej, deltagarna har samma upplevelse om de ansluter till ett Teams-möte med antingen Teams mötes-URL eller mötes-ID och lösenord.

• Hur ska utvecklare lagra och hantera lösenord?

  • Mötes-ID och lösenord är koordinater för att ansluta till mötet. Utvecklare bör behandla dem som hemligheter, som ska krypteras och om de lagras se till att de finns i en åtkomstkontrollerad miljö.
  • Om koordinaterna visas kan vem som helst ansluta till mötet och förstöra upplevelsen för alla i mötet.

• Hur hämtar jag mötes-ID och lösenord?

  1. Graph API: Använd Graph API för att hämta information om onlineMeeting resursen och kontrollera objektet i egenskapen joinMeetingIdSettings.
  2. Teams: I ditt Teams-program går du till Calendar appen och öppnar information om ett möte. Onlinemöten har mötes-ID och lösenord i definitionen av mötet.
  3. Outlook: Du hittar mötes-ID och lösenord i kalenderhändelser eller i e-postmöten.
  4. Utvecklare kan inte hämta mötes-ID och lösenord genom att anropa SDK eller hämta det från utförliga konsolloggar.

• Hur kan jag kontrollera att mötes-ID och lösenord är korrekta?

  • MeetingId och lösenordsverifiering kan göras via: https://www.microsoft.com/en-us/microsoft-teams/join-a-meeting.

Ta emot ett inkommande Teams-samtal

Du kan prenumerera incomingCall på händelsen på teamsCallAgent instansen för att registrera inkommande samtal till Teams-användaren. Händelsen har en egenskap med en teamsIncomingCall instans som gör att accept du kan eller reject det inkommande TeamsIncomingCall samtalet.

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

Aktivera och inaktivera video

Du kan hämta din lokala videoströmsamling från egenskapen localVideoStreams i instansen TeamsCall . Om den är aktiverad innehåller samlingen en skärmdelningsström och kameravideoflöden. Du kan hämta fjärrdeltagarnas videoströmmar genom att inspektera egenskapen TeamsCall.remoteParticipants där varje deltagare har en samling videoströmmar i egenskapen videoStreams.

Slå av och på ljud

Du kan använda mute och unmute asynkrona API:er på instansen TeamsCall för att stänga av eller inaktivera Teams-användare lokalt. Lokal ljudavstängning förhindrar att ljud skickas till andra deltagare.

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

Stäng av ljudet för andra deltagare

Om du vill stänga av ljudet för alla andra deltagare eller stänga av ljudet för en specifik deltagare kan du använda asynkrona API:er muteAllRemoteParticipants för anropet och mute på fjärrdeltagaren:

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

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

Kommentar

Detta API tillhandahålls som en förhandsversion för utvecklare och kan komma att ändras utifrån den feedback vi får. Använd inte detta API i en produktionsmiljö. Om du vill använda det här API:et använder du "beta"-versionen av Azure Communication Services Calling Web SDK

Hantera fjärrdeltagare

Andra samtalsdeltagare är tillgängliga i instansen TeamsCall under egenskapen remoteParticipants. Det är en samling RemoteParticipant objekt. Du kan lista, lägga till och ta bort andra deltagare från anropet.

Kommentar

Att lägga till en deltagarmetod kräver chattens threadId. Communication Services Calling SDK håller inte deltagarna i chatt- och samtalslistan synkroniserade. Microsft uppmuntrar utvecklare att hålla listan synkroniserad för bästa användarupplevelse. Lär dig hur du hanterar chatttråd.

Du kan lägga till en ny Teams-användare eller ett nytt telefonnummer i Teams-samtalet eller Teams-mötet genom att anropa metoden addParticipant för objektet TeamsCall. Metoden accepterar identifierare eller som indata och returnerar synkront instansen av RemoteParticipant och utlöser händelsen remoteParticipantsUpdated på instansenTeamsCall.PhoneNumberIdentifier MicrosoftTeamsUserIdentifier

Du kan ta bort en deltagare från Teams-anropet eller Teams-mötet genom att removeParticipant anropa metoden på instansen TeamsCall asynkront. Metoden accepterar identifierare MicrosoftTeamsUserIdentifier eller PhoneNumberIdentifier som indata. Metoden löses när RemoteParticipant tas bort från remoteParticipants samlingen och händelsen remoteParticipantsUpdated på instansen TeamsCall utlöses.

Visa en lista över andra samtalsdeltagare:

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

Lägg till Teams-användare och telefonnummer i Teams-samtalet eller Teams-mötet:

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

Ta bort Teams-användare och telefonnummer från Teams-samtal eller Teams-möte:

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

Fjärrdeltagare

Fjärrdeltagare representerar en slutpunkt som är ansluten till det pågående Teams-samtalet eller Teams-mötet. Klassen remoteParticipant har följande uppsättning egenskaper och samlingar:

• identifier: Returnerar någon av följande identifierare: CommunicationUserIdentifier, MicrosoftTeamsUserIdentifier, PhoneNumberIdentifiereller UnknownIdentifier.

const identifier = remoteParticipant.identifier;

• state: Returnerar en string som representerar ett tillstånd för en fjärrdeltagare. Tillståndet kan ha något av följande värden:

Tillståndsvärde	När	beskrivning
Idle	Initialt tillstånd	Detta är det första tillståndet för deltagaren
Connecting	Efter Idle	Övergångstillstånd när en deltagare ansluter till anropet.
Ringing	Efter Connecting	Deltagaren fick ett incomingCall meddelande eller teams-klienten ringer
Connected	Efter Ringing, Connecting, EarlyMediaeller InLobby	Deltagaren accepterade samtalsinbjudan eller anslöt sig till samtalet. Media flödar mot deltagaren.
Hold	Efter Connected	Deltagaren i anropet är spärrad.
EarlyMedia	Efter Connecting	Media spelas upp innan en deltagare ansluter till samtalet
InLobby	Efter Ringing, Connecting eller EarlyMedia	Deltagaren finns i teams möteslobby.
Disconnected	Slutligt tillstånd	Deltagaren är frånkopplad från anropet. Om fjärrdeltagaren förlorar sin nätverksanslutning ändras deras tillstånd till Disconnected efter två minuter.

Tillstånd för fjärranslutna deltagare i en-till-en- eller gruppsamtal:

Tillstånd för fjärranslutna deltagare i Teams-möten:

const state = remoteParticipant.state;

• callEndReason: Returnerar ett objekt som innehåller ytterligare information om orsaken till att anropet avslutades. Egenskapen code returnerar ett tal som är associerat med orsaken och subCode returnerar ett tal som är associerat med koden och orsaken. Mer information om felkoder finns i Felsöka svarskoder för samtalsslut.

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

• isMuted: Returnerar Boolean ett värde som representerar statusen lokal ljudavstängning.

const isMuted = remoteParticipant.isMuted;

• isSpeaking: Returnerar Boolean värdet som representerar statusen för inget ljud som skickas.

const isSpeaking = remoteParticipant.isSpeaking;

• videoStreams: Returnerar en samling RemoteVideoStream objekt som skickats av deltagarna.

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

• displayName: Returnerar ett string visningsnamn som representerar. Kommunikationstjänster som anropar SDK anger inte det här värdet för Teams-användare.

const displayName = remoteParticipant.displayName;

Ring

• id: Returnerar en sträng som representerar en unik anropsidentifierare.

const callId = call.id;

• info: Returnerar information om samtalet:

Kommentar

Detta API tillhandahålls som en förhandsversion för utvecklare och kan komma att ändras utifrån den feedback vi får. Använd inte detta API i en produktionsmiljö. Om du vill använda det här API:et använder du betaversionen av Azure Communication Services Calling Web SDK

• info: Returnerar objekt som innehåller information om anropet. threadId Egenskapen är en sträng som representerar chattens tråd-ID som visas i Teams-klienten.

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

• remoteParticipants: Returnerar en samling remoteParticipant objekt som representerar andra deltagare i Teams-anropet eller Teams-mötet.

const remoteParticipants = call.remoteParticipants;

• callerInfo: Returnerar objektet CallerInfo för inkommande anrop. Egenskapen identifier kan vara något av följande objekt CommunicationUserIdentifier, MicrosoftTeamsUserIdentifier, PhoneNumberIdentifiereller UnknownIdentifier. displayName Egenskapen är en sträng som representerar namnet som ska visas om den anges.

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

• state: Returnerar en sträng som representerar anropets tillstånd. Egenskapen kan ha något av följande värden:

Tillståndsvärde	När	beskrivning
None	Initialt tillstånd	Samtalets ursprungliga tillstånd.
Connecting	Efter None	Tillståndet när ett Teams-samtal eller Teams-möte placeras, ansluts eller godkänns.
Ringing	Efter Connecting	Fjärrdeltagaren tog emot incomingCall händelsen eller Teams-klienten ringer.
EarlyMedia	Efter Ringing eller Connecting	Mediet spelas upp innan samtalet ansluts.
Connected	Efter Ringing, EarlyMedia, InLobby, LocalHoldoch RemoteHold	Samtalet är anslutet. Media flödar mellan lokala slutpunkter och fjärranslutna deltagare.
LocalHold	Efter Connected	Samtalet spärrades av en lokal deltagare. Inget media flödar mellan den lokala slutpunkten och fjärrdeltagarna.
RemoteHold	Efter Connected	Samtalet spärrades av en fjärrdeltagare. Inget media flödar mellan den lokala slutpunkten och fjärrdeltagarna.
InLobby	Efter Ringing eller Connecting	Fjärrdeltagaren finns i teams möteslobby. Inget media flödar mellan den lokala slutpunkten och fjärrdeltagarna.
Disconnecting	Efter alla tillstånd	Övergångstillståndet innan anropet går till ett Disconnected tillstånd.
Disconnected	Slutligt tillstånd	Det slutliga tillståndet för samtalet. Om nätverksanslutningen går förlorad ändras tillståndet till Disconnected efter två minuter.

Tillstånd för en-till-en- eller gruppanrop:

Tillstånd för Teams-möten:

const callState = call.state;

• callEndReason: Returnerar objekt CallEndReason som innehåller ytterligare information om att samtalet avslutades. Egenskapen code returnerar ett tal som är associerat med orsaken och subCode returnerar ett tal som är associerat med koden och orsaken. Mer information om felkoder finns i Felsöka svarskoder för samtalsslut.

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

• direction: Returnerar en string som representerar anropets riktning. Egenskapen kan ha något av följande värden: "Inkommande" eller Outgoing.

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

• isMuted: Returnerar Boolean ett värde som representerar statusen lokal ljudavstängning.

const muted = call.isMuted;

• isScreenSharingOn: Returnerar Boolean värdet true om du skickar skärmdelningsström till andra deltagare.

const isScreenSharingOn = call.isScreenSharingOn;

• localVideoStreams: Returnerar en samling LocalVideoStream objekt som representerar videoströmmar som skickas till fjärranslutna deltagare.

const localVideoStreams = call.localVideoStreams;

Hantera chatttråd

Viktigt!

Det valfria chatt-ID:t är endast tillgängligt i 1.29.1 eller senare av calling SDK för JavaScript. Om du använder en tidigare version kontrollerar du att du anger ett unikt chatt-ID manuellt.

Att ange ett chatt-ID är valfritt för att ringa gruppsamtal och lägga till deltagare i befintliga samtal. Tillhörande chatt och samtal har en separat lista över deltagare. Innan du lägger till deltagare i samtalet lägger du till användaren i chatten för att tillhandahålla den bästa användarupplevelsen och uppfylla informationsbarriärkraven. Att lägga till en användare i anropet utan att lägga till användaren i chatten kan resultera i undantag om en informationsbarriär har konfigurerats.

Tänk på följande scenario, där Alice ringer ett anrop till Bob, sedan lägger Alice till Charlie, och 3 minuter senare tar Alice bort Charlie från samtalet.

1. Skapa en chatttråd mellan Alice, Bob och Charlie. Behåll chatten threadId för senare.
2. Alice anropar Bob och Charlie med hjälp av startCall metoden på TeamsCallAgent instansen.
3. Lägg till Dan i chatttråden med threadId hjälp av Chat Graph API för att lägga till medlem
4. Alice lägger till Dan i anropet med metoden addParticipant på call och anger threadId
5. Alice tar bort Dan från anropet med metoden removeParticipant på call och anger threadId
6. Ta bort Dan från chatttråden med threadId hjälp av Chat Graph API för att ta bort medlem

Om Teams-användaren stoppar samtalsinspelningen placeras inspelningen i chatten som är associerad med tråden. Det tillhandahållna chatt-ID:t påverkar upplevelsen för Teams-användare i Teams-klienter.

Rekommendationer för hantering av chatt-ID:

• Eskalering av 1:1-telefonsamtalet genom att lägga till en annan telefondeltagare:
  • Med metoden addParticipant kan du ange valfritt parameterchatt-ID. Om parametern inte anges skapas en ny gruppchatt och alla deltagare läggs till i listan med samtals- och chattdeltagare. Om parametern anges kan Teams-användare se pågående samtal som är associerade till den här gruppchatten i Teams-appen. Du kan skapa en ny gruppchatt via Graph API.

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

• Starta gruppsamtal med en enskild Microsoft 365-användare och flera telefondeltagare:
  • Med metod-API startCall kan du starta ett gruppsamtal med flera deltagare och eventuellt ange chatt-ID. Om parametern inte anges skapas en ny gruppchatt och alla Microsoft 365-deltagare läggs till i listan med samtals- och chattdeltagare. Om parametern anges kan Teams-användare se pågående samtal som är associerade till den här gruppchatten i Teams-appen. Du kan skapa en ny gruppchatt via Graph API.

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

  • Använd Graph API för att hämta befintligt chatt-ID med endast Teams-användare som deltagare eller skapa en ny gruppchatt med deltagare: Teams användar-ID och "00000000-0000-0000-0000000000000".
• Starta gruppsamtal med fler än 2 Microsoft 365-användare:
  • (Valfritt sätt) När du gör ett gruppsamtal med fler än 2 Microsoft 365-användare som använder ACS Calling SDK skapar SDK:t automatiskt tråden som standard.

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

  • Om så önskas kan utvecklaren ange ett unikt chatt-ID för att starta gruppsamtalet eller lägga till deltagare. I det här fallet använder ACS Calling SDK det angivna chatt-ID:t för att skapa gruppanropet. En chatttråd skapas för Teams-användare och den här tråden är associerad med gruppanropet för användare i Teams-appen. På så sätt kan de chatta under samtalet. Hantering av chatttrådar kan göras via Graph API