Besprechungs-Apps-APIs

Die Besprechungserweiterbarkeit bietet APIs zur Verbesserung der Besprechungserfahrung. Mit Hilfe der aufgeführten APIs können Sie Folgendes ausführen:

  • Erstellen Sie Apps oder integrieren Sie vorhandene Apps in den Meeting-Lebenszyklus.
  • Verwenden Sie APIs, um Ihre App auf Meetings aufmerksam zu machen.
  • Wählen Sie die erforderlichen APIs aus, um das Besprechungserlebnis zu verbessern.

Hinweis

Verwenden Sie die Microsoft Teams JavaScript-Clientbibliothek (TeamsJS) (Version: 1.10 und höher), damit Single Sign-On (SSO) im Besprechungsseitenbereich funktioniert.

Die folgende Tabelle enthält eine Liste der APIs, die im Teams SDK und in der TeamsJS-Bibliothek verfügbar sind:

Methode Beschreibung Quelle
Teilnehmer abrufen Rufen Sie Teilnehmerinformationen nach Meeting-ID und Teilnehmer-ID ab. Teams-SDK
Senden Sie eine Besprechungsbenachrichtigung Stellt Besprechungssignale mithilfe der Unterhaltungsbenachrichtigungs-API für den Benutzer-Bot-Chat bereit und ermöglicht es dem Bot, Benutzeraktionen zu benachrichtigen, die eine Besprechungsbenachrichtigung anzeigen. Teams-SDK
Besprechungsdetails abrufen Rufen Sie die statischen Metadaten eines Meetings ab. Teams-SDK
Senden Sie Untertitel in Echtzeit Senden Sie Untertitel in Echtzeit an ein laufendes Meeting. TeamsJS-Bibliothek
Teilen Sie App-Inhalte auf der Bühne Teilen Sie bestimmte Teile der App für die Meeting-Phase aus dem Seitenbereich der App in einem Meeting. TeamsJS-Bibliothek
Empfangen von Teams-Besprechungsereignissen in Echtzeit Empfangen Sie Besprechungsereignisse in Echtzeit, z. B. den Anfang und das Ende einer Besprechung oder das Beitreten und Verlassen der Besprechung. Teams-SDK

Holen Sie sich die Benutzerkontext-API

Wichtig

  • Standardmäßig unterstützt der neue Teams-Client helle Designs für Apps in Teams-Besprechungen. Wenn die Eigenschaft in der app.theme getContext-API den default Wert zurückgibt, befindet sich der Teams-Client im hellen Design.
  • Frühere Versionen von Teams-Clients unterstützen nur das dunkle und kontrastierende Design für Apps in Teams-Besprechungen

Informationen zum Identifizieren und Abrufen von Kontextinformationen für Ihre Registerkarteninhalte finden Sie unter Abrufen von Kontext für Ihre Registerkarte "Teams". wird von einer meetingId Registerkarte verwendet, die im Besprechungskontext ausgeführt wird, und wird für die Antwortnutzlast hinzugefügt.

Beispiele

Im Folgenden finden Sie die TeamsJS v2-Antworten für die API zum Abrufen des Benutzerkontexts basierend auf Besprechungstyp, Benutzertyp und Anruftyp:

  • Besprechungstyp

    Im Folgenden finden Sie eine JSON-Nutzlastantwort für eine Kanalbesprechung für Mandantenbenutzer:

    {
    "app": {
    "locale": "en-us",
    "sessionId": "ff47ec00-e6a7-4dc1-a6ae-f44110f50c94",
    "theme": "default",
    "iconPositionVertical": 0,
    "osLocaleInfo": {
      "platform": "windows",
      "regionalFormat": "en-in",
      "shortDate": "dd-MM-yyyy",
      "longDate": "dd MMMM yyyy",
      "shortTime": "HH:mm",
      "longTime": "HH:mm:ss"
    },
    "parentMessageId": "1678109354022",
    "userClickTime": 1678109521159,
    "userFileOpenPreference": "inline",
    "host": {
      "name": "Teams",
      "clientType": "desktop",
      "sessionId": "c3c3c0a0-f7a1-b070-6b89-c8cd1f380042",
      "ringId": "ring1"
    },
    "appLaunchId": "7346ae66-5cac-47f9-8a0d-1228dac474cb"
    },
    "page": {
    "id": "Test",
    "frameContext": "sidePanel",
    "subPageId": "",
        "isFullScreen": false,
        "isMultiWindow": true,
        "sourceOrigin": ""
       },
       "user": {
        "id": "57efa5f3-273c-47e2-a871-4879e5d849cf",
        "displayName": "",
        "isCallingAllowed": undefined,
        "isPSTNCallingAllowed": undefined,
        "licenseType": "Unknown",
        "loginHint": "user@microsoft.com",
        "userPrincipalName": "user@microsoft.com",
        "tenant": {
         "id": "72f988bf-86f1-41af-91ab-2d7cd011db47",
         "teamsSku": "enterprise"
        }
       },
       "channel": {
        "id": "19:49683807ffce4318ad6d6d7a24dbde45@thread.tacv2",
        "displayName": undefined,
        "relativeUrl": undefined,
        "membershipType": undefined,
        "defaultOneNoteSectionId": undefined,
        "ownerGroupId": undefined,
        "ownerTenantId": undefined
       },
       "chat": {
        "id": "19:49683807ffce4318ad6d6d7a24dbde45@thread.tacv2"
       },
       "meeting": {
        "id": "MCMxOTo0OTY4MzgwN2ZmY2U0MzE4YWQ2ZDZkN2EyNGRiZGU0NUB0aHJlYWQudGFjdjIjMTY3ODEwOTM1NDAyMg=="
       },
       "sharepoint": undefined,
       "team": {
        "internalId": "19:b34aeec3f8e54240a5c283e86bfc4878@thread.tacv2",
        "displayName": undefined,
        "type": undefined,
        "groupId": undefined,
        "templateId": undefined,
        "isArchived": undefined,
        "userRole": 1
       },
       "sharePointSite": {
        "teamSiteUrl": "",
        "teamSiteDomain": "microsoft.sharepoint.com",
        "teamSitePath": "",
        "teamSiteId": "",
        "mySitePath": undefined,
        "mySiteDomain": undefined
       }
      }

  • Benutzertyp

    Im Folgenden finden Sie eine JSON-Nutzlastantwort in einer geplanten privaten Besprechung für einen Gastbenutzer:

      {
        "app": {
         "locale": "en-us",
         "sessionId": "268beeb4-a52d-4ba8-b1c8-8b9f0b9b3492",
         "theme": "default",
         "iconPositionVertical": 23,
         "osLocaleInfo": {
          "platform": "windows",
          "regionalFormat": "en-in",
          "longDate": "dd MMMM yyyy",
          "shortDate": "dd-MM-yyyy",
          "longTime": "HH:mm:ss",
          "shortTime": "HH:mm"
         },
         "parentMessageId": "",
         "userClickTime": 1678023265131,
         "userFileOpenPreference": "inline",
         "host": {
          "name": "Teams",
          "clientType": "desktop",
          "sessionId": "967c980b-1e41-a2cd-eac0-a4bff8f73ce7",
          "ringId": "ring1"
         },
         "appLaunchId": "c35c4496-f28c-4107-8e6c-2dba09fb881a"
        },
        "page": {
         "id": "Test",
         "frameContext": "content",
         "subPageId": "",
         "isFullScreen": false,
         "isMultiWindow": false,
         "sourceOrigin": NULL
        },
        "user": {
         "id": "57efa5f3-273c-47e2-a871-4879e5d849cf",
         "displayName": undefined,
         "isCallingAllowed": undefined,
         "isPSTNCallingAllowed": undefined,
         "licenseType": "Unknown",
         "loginHint": "user@microsoft.com",
         "userPrincipalName": "user@microsoft.com",
         "tenant": {
          "id": "72f988bf-86f1-41af-91ab-2d7cd011db47",
          "teamsSku": "enterprise"
         }
        },
        "channel": undefined,
        "chat": {
         "id": "19:meeting_YmU5NWM3NGEtZjMyMi00ZDg4LTk4OGUtMjUzMGJkZjRhMDhm@thread.v2"
        },
        "meeting": {
         "id": "MCMxOTptZWV0aW5nX1ltVTVOV00zTkdFdFpqTXlNaTAwWkRnNExUazRPR1V0TWpVek1HSmtaalJoTURobUB0aHJlYWQudjIjMA=="
        },
        "sharepoint": undefined,
        "team": undefined,
        "sharePointSite": {
         "teamSiteUrl": "",
         "teamSiteDomain": "microsoft.sharepoint.com",
         "teamSitePath": "",
         "teamSiteId": undefined,
         "mySitePath": "/personal/user_microsoft_com",
         "mySiteDomain": "microsoft-my.sharepoint.com"
        }
  }

  • Anruftyp

    Im Folgenden finden Sie eine JSON-Nutzlastantwort für einen Einzelanruf für einen In-Mandanten-Benutzer:

          {
       "app": {
        "locale": "en-us",
        "sessionId": "1b3dc47e-f6ae-4fe2-8ed6-844a505f3186",
        "theme": "dark",
        "iconPositionVertical": null,
        "osLocaleInfo": {
         "platform": "windows",
         "regionalFormat": "en-in",
         "shortDate": "dd-MM-yyyy",
         "longDate": "dd MMMM yyyy",
         "shortTime": "HH:mm",
         "longTime": "HH:mm:ss"
        },
        "parentMessageId": "",
        "userClickTime": 1678088052473,
        "userFileOpenPreference": undefined,
        "host": {
         "name": "Teams",
         "clientType": "desktop",
         "sessionId": "",
         "ringId": "general"
        },
        "appLaunchId": undefined
       },
       "page": {
        "id": "Test",
        "frameContext": "sidePanel",
        "subPageId": "",
        "isFullScreen": undefined,
        "isMultiWindow": true,
        "sourceOrigin": ""
       },
       "user": {
        "id": "e652dd92-dd63-4fcc-b5b2-2005681e8e9f",
        "displayName": undefined,
        "isCallingAllowed": undefined,
        "isPSTNCallingAllowed": undefined,
        "licenseType": "Unknown",
        "loginHint": "user@microsoft.com",
        "userPrincipalName": "user@microsoft.com",
        "tenant": {
         "id": "aa923623-ae61-49ee-b401-81f414b6ad5a",
         "teamsSku": "unknown"
        }
       },
       "channel": undefined,
       "chat": {
        "id": "19:a74d8489-4455-4670-9581-7b38a8017c58_e652dd92-dd63-4fcc-b5b2-2005681e8e9f@unq.gbl.spaces"
       },
       "meeting": {
        "id": "MCMxOTphNzRkODQ4OS00NDU1LTQ2NzAtOTU4MS03YjM4YTgwMTdjNThfZTY1MmRkOTItZGQ2My00ZmNjLWI1YjItMjAwNTY4MWU4ZTlmQHVucS5nYmwuc3BhY2VzIzA="
       },
       "sharepoint": undefined,
       "team": undefined,
       "sharePointSite": {
        "teamSiteUrl": undefined,
        "teamSiteDomain": "microsoft.sharepoint.com",
        "teamSitePath": undefined,
        "teamSiteId": undefined,
        "mySitePath": undefined,
        "mySiteDomain": undefined
       }
      }

Teilnehmer-API abrufen

Mit der API "Teilnehmer abrufen" kann Ihre App Teilnehmerinformationen anhand der Besprechungs-ID und Teilnehmer-ID abrufen. Die API ist über das Teams SDK verfügbar.

Hinweis

  • Der Benutzertyp ist nicht in der API "getParticipantRole " enthalten.
  • Teilnehmerrollen nicht zwischenspeichern, da der Besprechungsorganisator die Rollen jederzeit ändern kann.
  • Die GetParticipant API wird nur für Verteilerlisten oder Dienstpläne mit weniger als 350 Teilnehmern unterstützt.

Abfrageparameter

Tipp

Rufen Sie Teilnehmer-IDs und Mandanten-IDs auf der Registerkarte SSO-Authentifizierung ab.

Die Meeting API muss über participantId, und tenantId als Parameter verfügenmeetingId. Die Parameter sind als Teil des Teams SDK-Aktivitätskontexts und der TeamsJS-Bibliothek verfügbar.

Die folgende Tabelle enthält die Abfrageparameter:

Wert Typ Erforderlich Beschreibung
meetingId Zeichenfolge Ja Der Besprechungsbezeichner ist über Bot Invoke und die TeamsJS-Bibliothek verfügbar.
participantId Zeichenfolge Ja Die Teilnehmer-ID ist die Benutzer-ID. Es ist in Tab SSO, Bot Invoke und TeamsJS-Bibliothek verfügbar. Es wird empfohlen, eine Teilnehmer-ID vom Tab SSO zu erhalten.
tenantId Zeichenfolge Ja Die Mandanten-ID ist für die Mandantenbenutzer erforderlich. Es ist in Tab SSO, Bot Invoke und TeamsJS-Bibliothek verfügbar. Es wird empfohlen, eine Mandanten-ID von Tab SSO zu erhalten.

Beispiel

app.OnMessage(async (context, cancellationToken) =>
{
    var meetingId = context.Activity.ChannelData?.Meeting?.Id;
    var tenantId = context.Activity.ChannelData?.Tenant?.Id;
    var userId = context.Activity.From?.AadObjectId;

    if (meetingId != null && tenantId != null && userId != null)
    {
        // Gets the details for the given meeting participant.
        var participant = await context.Api.Meetings.GetParticipantAsync(meetingId, userId, tenantId);

        // Sends a message activity to the sender of the incoming activity.
        await context.Send($"The participant role is: {participant.Meeting?.Role}", cancellationToken);
    }
});
Eigenschaftenname Beschreibung
user.id ID des Benutzers.
user.aadObjectId Microsoft Entra-Objekt-ID des Benutzers.
user.name Der Name des Benutzers.
user.givenName Vorname des Benutzers.
user.surname Nachname des Benutzers.
user.email E-Mail-ID des Benutzers.
user.userPrincipalName UPN des Benutzers.
user.tenantId Microsoft Entra-Mandanten-ID.
user.userRole Rolle des Benutzers. Beispiel: "Administrator" oder "Benutzer".
meeting.role Die Rolle des Teilnehmers in der Besprechung. Beispiel: "Organisator" oder "Referent" oder "Teilnehmer".
meeting.inMeeting Der Wert, der angibt, ob der Teilnehmer an der Besprechung teilnimmt.
conversation.id Die ID des Besprechungschats.
conversation.isGroup Boolescher Wert, der angibt, ob die Konversation mehr als zwei Teilnehmer hat.

Antwortcodes

Die folgende Tabelle enthält die Antwortcodes:

Antwortcode Beschreibung
403 Get-Teilnehmerinformationen werden nicht mit der App geteilt. Wenn die App nicht im Meeting installiert ist, löst sie die Fehlerantwort 403 aus. Wenn der Administrator die App während der Livewebsitemigration deaktiviert oder blockiert, wird die Fehlerantwort 403 ausgelöst.
200 Die Teilnehmerinformationen wurden erfolgreich abgerufen.
401 Die App antwortet mit einem ungültigen Token.
404 Die Besprechung ist entweder abgelaufen oder die Teilnehmer sind nicht verfügbar.

Senden Sie eine Besprechungsbenachrichtigung

Alle Benutzer in einem Meeting erhalten die Benachrichtigungen, die über die Nutzlast für Benachrichtigungen im Meeting gesendet werden. Die Payload „In-Meeting-Benachrichtigung“ löst eine In-Meeting-Benachrichtigung aus und ermöglicht es Ihnen, Meeting-Signale bereitzustellen, die mithilfe der vorhandenen Konversationsbenachrichtigungs-API für Benutzer-Bot-Chat bereitgestellt werden. Sie können eine Meeting-Benachrichtigung basierend auf einer Benutzeraktion senden. Die Nutzlast ist über das Teams SDK verfügbar.

Sie können auch gezielte Besprechungsbenachrichtigungen an einen bestimmten Teilnehmer in einer Besprechung senden. Weitere Informationen finden Sie unter Gezielte Benachrichtigung während einer Besprechung.

Hinweis

  • Wenn eine Meeting-Benachrichtigung aufgerufen wird, wird der Inhalt als Chat-Nachricht präsentiert.
  • Sie müssen die Funktion submitTask() aufrufen, damit sie automatisch geschlossen wird, nachdem ein Benutzer eine Aktion in der Webansicht ausgeführt hat. Dies ist eine Voraussetzung für die App-Übermittlung. Weitere Informationen finden Sie unter Teams SDK-Aufgabenmodul.
  • Wenn Sie möchten, dass Ihre App anonyme Benutzer unterstützt, muss sich die Nutzlast der anfänglichen Aufrufanforderung auf from.id Anforderungsmetadaten im from Objekt und nicht auf from.aadObjectId Anforderungsmetadaten stützen. from.idist die Benutzer-ID und from.aadObjectId ist die Microsoft Entra ID des Benutzers. Weitere Informationen finden Sie unter Aufgabenmodule in Registerkarten verwenden und Aufgabenmodul erstellen und senden.

Abfrageparameter

Die folgende Tabelle enthält den Abfrageparameter:

Wert Typ Erforderlich Beschreibung
conversationId Zeichenfolge Ja Die Konversations-ID ist als Teil von Bot Invoke verfügbar.

Beispiele

Bot ID wird im Manifest deklariert, und der Bot empfängt ein Ergebnisobjekt.

Hinweis

  • Der completionBotId Parameter von externalResourceUrl ist im angeforderten Payload-Beispiel optional.
  • Die externalResourceUrl Breiten- und Höhenparameter müssen in Pixel angegeben werden. Weitere Informationen finden Sie unter Designrichtlinien.
  • Die URL ist die Seite, die wie in <iframe> der Besprechungsbenachrichtigung geladen wird. Die Domäne muss sich im validDomains Array der Apps in Ihrem App-Manifest befinden.
app.OnMessage(async (context, cancellationToken) =>
{
    // Send an in-meeting notification with an external resource URL.
    await context.Send(new Activity
    {
        Type = "message",
        Text = "This is a meeting signal test",
        ChannelData = new
        {
            notification = new
            {
                alertInMeeting = true,
                externalResourceUrl = "https://teams.microsoft.com/l/bubble/APP_ID?url=<url>&height=<height>&width=<width>&title=<title>&completionBotId=BOT_APP_ID"
            }
        }
    }, cancellationToken);
});
Eigenschaftenname Beschreibung
type Aktivitätstyp.
text Der Textinhalt der Nachricht.
summary Der zusammenfassende Text der Nachricht.
channelData.notification.alertInMeeting Boolescher Wert, der angibt, ob dem Benutzer während einer Besprechung eine Benachrichtigung angezeigt werden soll.
channelData.notification.externalResourceUrl Der Wert der externen Ressourcen-URL der Benachrichtigung.
replyToId Die ID der übergeordneten oder Stammnachricht des Threads.
APP_ID Im Manifest deklarierte App-ID.
completionBotId Bot-App-ID.

Antwortcodes

Die folgende Tabelle hat die Antwortcodes:

Antwortcode Beschreibung
201 Die Aktivität mit Signal wurde erfolgreich gesendet.
401 Die App antwortet mit einem ungültigen Token.
403 Die App kann das Signal nicht senden. Der Antwortcode 403 kann aus verschiedenen Gründen auftreten, z. B. wenn der Administrator die App während der Livesitemigration deaktiviert und blockiert. In diesem Fall enthält die Payload eine detaillierte Fehlermeldung.
404 Der Meeting-Chat existiert nicht.

Gezielte Besprechungsbenachrichtigung und App-Symbol-Badging-API

Die targetedMeetingNotification API ermöglicht Apps das Senden gezielter Besprechungsbenachrichtigungen und zeigt bestimmten Teilnehmern in einer Besprechung App-Symbol-Badging an. Apps senden basierend auf Benutzeraktionen gezielte Benachrichtigungen während einer Besprechung und App-Symbol-Badging. Die API ist über die Bot-API verfügbar.

Voraussetzungen

Sie müssen Ihr App-Manifest mit RSC-Berechtigungen unter der Eigenschaft konfigurieren, um webApplicationInfo bestimmten Teilnehmern in einer Besprechung gezielte Benachrichtigungen während einer Besprechung zu senden und App-Symbol-Badging anzuzeigen. Verwenden Sie die folgenden Beispiele, um Ihr Manifest zu konfigurieren:


Für App-Manifestversion 1.12 und höher 
"webApplicationInfo": {
    "id": "<<MICROSOFT-APP-ID>>",
    "resource": "https://RscBasedStoreApp"  },
  "authorization": {
    "permissions": {
      "resourceSpecific": [
            {
                "name": "OnlineMeetingNotification.Send.Chat",
                "type": "Application"
            }
        ]    
    }
}


Für App-Manifest Version 1.11 und früher 
"webApplicationInfo": {
    "id": "<<MICROSOFT-APP-ID>>",
    "resource": "https://RscBasedStoreApp",
    "applicationPermissions": [
      "OnlineMeetingNotification.Send.Chat"
    ]
}

Hinweis

  • Die API-Nutzlast lässt nur einen Dialog mit einer URL zu.
  • Die Benutzer-ID-Formate aadObjectid und UPN werden nicht unterstützt.

Abrufen des unterstützten Benutzer-ID-Formats für gezielte Benachrichtigungen während einer Besprechung und App-Symbol-Badging:

Beispiel

Im Folgenden finden Sie ein Beispiel für Anforderungsnutzlasten für gezielte In-Meeting-Benachrichtigungen und App-Symbol-Badging:

POST /v1/meetings/{meetingId}/notification

{

  "type": "targetedMeetingNotification",
  "value": {
    "recipients": [ 
"29:1I12M_iy2wTa97T6LbjTh4rJCWrtw2PZ3lxpD3yFv8j2YPnweY2lpCPPAn3RI0PP7rghfHauUz48I1t7ANhj4CA"
     ], 
    "surfaces": [ 
      { 
        "surface": "meetingStage", 
        "contentType": "task", 
        "content": { 
          "value": { 
            "height": "300", 
            "width": "400", 
            "title": "Targeted meeting Notification", 
            "url": "https://somevalidurl.com"           
}
        } 
      } 
    ] 
  },
  "channelData": { // optional if a developer doesn't want to support user attributes.
    "onBehalfOf": [ 
      { 
        "itemid": 0, 
        "mentionType": "person", 
        "mri": "29:1mDOCfGM9825lMHlwP8NjIVMJeQAbN-ojYBT5VzQfPpnst1IFQeYB1QXC8Zupn2RhgfLIW27HmynQk-4bdx_YhA", 
        "displayName": "yunny chung"      } 
    ] 
  }
}
Eigenschaftenname Beschreibung
meetingId Die Besprechungs-ID ist über den Bot-Aufruf und die TeamsJS-Bibliothek verfügbar.
type targetedMeetingNotification
recipients Liste der Benutzer-IDs. Abrufen von Benutzer-IDs für Besprechungsteilnehmer über die API zum Abrufen von Teilnehmern. Rufen Sie die gesamte Liste der Chatliste mithilfe der API "Mitglieder abrufen" ab. Eine leere Empfängerliste oder eine Null-Empfängerliste gibt 400 zurück.
surface Eine Art von Oberfläche. Die unterstützten Oberflächentypen sind meetingStage und .meetingTabIcon
surfaces Liste der Oberflächen, auf denen Benachrichtigungen gerendert werden können.
contentType Der Typ des Inhalts, der von der gezielten Besprechungsbenachrichtigung gerendert wird. Der unterstützte Wert ist task.
content TaskModuleContinueResponse
content.value.height Optional; angeforderte Höhe der Benachrichtigung.
content.value.width Optional; angeforderte Breite der Benachrichtigung.
content.value.title Optional; Titel der Benachrichtigung.
content.value.url Optional; URL, die in der Benachrichtigung dargestellt werden soll. Stellen Sie sicher, dass die URL Teil des In-App-Manifests validDomains ist. Wenn eine leere Zeichenfolge oder keine URL angegeben wird, wird in einer Besprechungsbenachrichtigung nichts gerendert.
ChannelData.OnBehalfOf Optional; Dies dient zur Unterstützung von Benutzerattributen.
onBehalfOf.itemid Beschreibt die Identifizierung des Elements. Der Wert muss 0 sein.
onBehalfOf.mentionType personSchlüsselwort (keyword). Beschreibt die Erwähnung einer Person.
onBehalfOf.mri Benutzer-MRI als Absender angezeigt.
onBehalfOf.displayName Optional; Name der person. Wird als Fallback für den Fall verwendet, dass die Namensauflösung nicht verfügbar ist.

Hinweis

Wenn Sie eine ungültige Eingabe eingeben, gibt die API den Status 400 zurück.

Antwortcode

Die folgende Tabelle hat die Antwortcodes:

Antwortcode Beschreibung
202 Die Benachrichtigung wurde erfolgreich gesendet.
207 Benachrichtigungen werden nur an wenige Teilnehmer gesendet.
400 Fehler bei der Validierung der Besprechungsbenachrichtigungsanforderung.
401 Bottoken ist ungültig.
403 Der Bot darf die Benachrichtigung nicht senden.
404 Der Besprechungschat wird nicht gefunden, oder keiner der Teilnehmer wurde in der Liste gefunden.

Rufen Sie die Besprechungsdetails-API ab

Mit der Besprechungsdetails-API kann Ihre App die statischen Metadaten einer Besprechung abrufen. Die Metadaten stellen Datenpunkte bereit, die sich nicht dynamisch ändern. Die API ist über das Teams SDK verfügbar. Sowohl private geplante oder wiederkehrende Besprechungen als auch vom Kanal geplante oder wiederkehrende Besprechungen unterstützen die API mit unterschiedlichen RSC-Berechtigungen.

Die Besprechungsdetails-API muss über eine Botregistrierung und eine Bot-ID verfügen. Um die Besprechungsdetails-API verwenden zu können, müssen Sie je nach Umfang einer Besprechung, z. B. einer privaten Besprechung oder einer Kanalbesprechung, unterschiedliche RSC-Berechtigungen einholen.

Wird zur Erweiterung durch Eins-zu-Eins-Anrufe verwendet getMeetingDetailsVerbose

Die getMeetingDetailsVerbose Funktion erweitert die Funktionalität der getMeetingDetails API, um Anrufe über das Telefonfestnetz (PSTN) und Teams-zu-Teams-Anrufe für persönliche Registerkarten-Apps zu ermöglichen. Sie gibt die IMeetingDetailsResponse Schnittstelle mit zusätzlichen Aufrufdetails zurück.

Weitere Informationen finden Sie unter Erstellen von Registerkarten für Anrufe.

Hinweis

Die Besprechungsdetails-API wird für geplante private Besprechungen, geplante Kanalbesprechungen, Sofortbesprechungen (Jetzt besprechen), Einzelanrufe und Gruppenanrufe in Microsoft Teams-Desktop- und mobilen Clients unterstützt.

Voraussetzungen

  • Um die Besprechungsdetails-API verwenden zu können, müssen Sie je nach Umfang einer Besprechung, z. B. einer privaten Besprechung oder einer Kanalbesprechung, unterschiedliche RSC-Berechtigungen einholen.

  • Um Anrufe zu aktivieren, stellen Sie sicher, dass Sie die OnlineMeetingParticipant.Read.Chat RSC-Berechtigung erhalten haben.

  • Teams JS SDK erforderlich: TeamsJS SDK-Version neueste Version.


Für App-Manifestversion 1.12 und höher

Verwenden Sie das folgende Beispiel, um die App-Manifeste webApplicationInfo und authorization -Eigenschaften für eine private Besprechung zu konfigurieren:

"webApplicationInfo": {
    "id": "<bot id>",
    "resource": "https://RscPermission",
},
"authorization": {
    "permissions": {
        "resourceSpecific": [
            {
                "name": "OnlineMeeting.ReadBasic.Chat",
                "type": "Application"
            }
        ]
    }
}

Verwenden Sie das folgende Beispiel, um die Manifeste webApplicationInfo und authorization Eigenschaften Ihrer App für ein beliebiges Kanalmeeting zu konfigurieren:

"webApplicationInfo": {
    "id": "<bot id>",
    "resource": "https://RscPermission",
},
"authorization": {
    "permissions": {
        "resourceSpecific": [
            {
                "name": "ChannelMeeting.ReadBasic.Group",
                "type": "Application"
            }
        ]
    }
}


Für App-Manifest Version 1.11 und früher

Verwenden Sie das folgende Beispiel, um die webApplicationInfo Eigenschaft Ihres App-Manifests für ein privates Meeting zu konfigurieren:

"webApplicationInfo": {
    "id": "<bot id>",
    "resource": "https://RscPermission",
    "applicationPermissions": [
      "OnlineMeeting.ReadBasic.Chat"
    ]
}

Verwenden Sie das folgende Beispiel, um die webApplicationInfo Eigenschaft Ihres App-Manifests für ein beliebiges Kanalmeeting zu konfigurieren:

"webApplicationInfo": {
    "id": "<bot id>",
    "resource": "https://RscPermission",
    "applicationPermissions": [
      "ChannelMeeting.ReadBasic.Group"
    ]
}

Hinweis

  • Wenn die ChannelMeeting.ReadBasic.Group Berechtigung zum Manifest hinzugefügt wird, empfängt der Bot die Start- oder Endereignisse der Besprechung automatisch aus den Kanalbesprechungen, die in allen Teams erstellt wurden, denen der Bot hinzugefügt wurde.
  • Bei einem Einzelanruf organizer ist der Initiator des Chats und bei Gruppenanrufen organizer der Initiator des Anrufs. Bei öffentlichen Kanalbesprechungen organizer ist die Person, die den Kanalbeitrag erstellt hat.

Abfrageparameter

Die folgende Tabelle listet die Abfrageparameter auf:

Wert Typ Erforderlich Beschreibung
meetingId Zeichenfolge Ja Die Besprechungs-ID ist über Bot Invoke und die TeamsJS-Bibliothek verfügbar.

Beispiel

app.OnMessage(async (context, cancellationToken) =>
{
    var meetingId = context.Activity.ChannelData?.Meeting?.Id;

    if (meetingId != null)
    {
        // Gets the information for the given meeting id.
        var meetingInfo = await context.Api.Meetings.GetByIdAsync(meetingId);

        // Sends a message activity to the sender of the incoming activity.
        await context.Send(JsonConvert.SerializeObject(meetingInfo), cancellationToken);
    }
});
Eigenschaftenname Beschreibung
details.id Die ID der Besprechung, codiert als BASE64-Zeichenfolge.
details.msGraphResourceId Die MsGraphResourceId, die speziell für MS Graph-API-Aufrufe verwendet wird.
details.scheduledStartTime Die geplante Startzeit der Besprechung in UTC.
details.scheduledEndTime Die geplante Endzeit der Besprechung in UTC.
details.joinUrl Die URL, die für den Beitritt zur Besprechung verwendet wird.
details.title Der Titel der Besprechung.
details.type Der Besprechungstyp (OneToOneCall, GroupCall, Scheduled, Recurring, MeetNow, ChannelScheduled und ChannelRecurring).
conversation.isGroup Boolescher Wert, der angibt, ob die Konversation mehr als zwei Teilnehmer hat.
conversation.conversationType Der Unterhaltungstyp.
conversation.id Die ID des Besprechungschats.
organizer.id Die Benutzer-ID des Organisators.
organizer.aadObjectId Die Microsoft Entra-Objekt-ID des Organisators.
organizer.tenantId Die Microsoft Entra-Mandanten-ID des Organisators.
ursprünglicher Caller MRT für den ursprünglichen Anrufer eines Anrufs.
dialedEntity MRT, das das Original als gewählt bezeichnete
trackingId Eine persistente ID, die auf einen Aufruf und alle zugehörigen Aufrufe verweist.

Im Falle eines Besprechungsserientyps:

startDate: Gibt das Datum an, an dem mit der Anwendung des Musters begonnen werden soll. Der Wert von startDate muss dem Datumswert der start-Eigenschaft der Ereignisressource entsprechen. Das erste Vorkommen der Besprechung findet möglicherweise nicht an diesem Datum statt, wenn es nicht in das Muster passt.

endDate: Gibt das Datum an, an dem die Anwendung des Musters beendet werden soll. Das letzte Vorkommen der Besprechung findet möglicherweise nicht an diesem Datum statt, wenn es nicht dem Muster entspricht.

API zum Senden von Beschriftungen in Echtzeit

Die API zum Senden von Echtzeituntertiteln macht einen POST-Endpunkt für den Zugriff auf die Teams-Kommunikation verfügbar, CART-Untertitel (Real-Time Translation), von Menschen eingegebene Untertitel. An diesen Endpunkt gesendete Textinhalte werden Endbenutzern in einer Teams-Besprechung angezeigt, wenn sie Untertitel aktiviert haben.

CART-URL

Sie können die CART-URL für den POST-Endpunkt von der Seite Besprechungsoptionen in einer Teams-Besprechung abrufen. Weitere Informationen finden Sie unter CART-Beschriftungen in einer Microsoft Teams Besprechung. Sie müssen die CART-URL nicht ändern, um CART-Beschriftungen zu verwenden.

Abfrageparameter

Die CART-URL enthält die folgenden Abfrageparameter:

Wert Typ Erforderlich Beschreibung
meetingId Zeichenfolge Ja Die Besprechungs-ID ist über Bot Invoke und die TeamsJS-Bibliothek verfügbar.
Beispiel: meetingid=%7b%22tId%22%3a%2272f234bf-86f1-41af-91ab-2d7cd0321b47%22%2c%22oId%22%3a%22e071f268-4241-47f8-8cf3-fc6b84437f23%22%2c%22thId%22%3a%2219%3ameeting_NzJiMjNkMGQtYzk3NS00ZDI1LWJjN2QtMDgyODVhZmI3NzJj%40thread.v2%22%2c%22mId%22%3a%220%22%7d
token Zeichenfolge Ja Autorisierungstoken.
Beispiel: token=04751eac

Beispiel

https://api.captions.office.microsoft.com/cartcaption?meetingid=%7b%22tId%22%3a%2272f234bf-86f1-41af-91ab-2d7cd0321b47%22%2c%22oId%22%3a%22e071f268-4241-47f8-8cf3-fc6b84437f23%22%2c%22thId%22%3a%2219%3ameeting_NzJiMjNkMGQtYzk3NS00ZDI1LWJjN2QtMDgyODVhZmI3NzJj%40thread.v2%22%2c%22mId%22%3a%220%22%7d&token=gjs44ra

Methode

Ressource Methode Beschreibung
/cartcaption POST Behandeln Sie Beschriftungen für das Meeting, das gestartet wurde

Hinweis

Stellen Sie sicher, dass der Inhaltstyp für alle Anforderungen Klartext mit UTF-8-Codierung ist. Der Anfragetext enthält nur Bildunterschriften.

Beispiel

POST /cartcaption?meetingid=04751eac-30e6-47d9-9c3f-0b4ebe8e30d9&token=04751eac&lang=en-us HTTP/1.1
Host: api.captions.office.microsoft.com
Content-Type: text/plain
Content-Length: 22
Hello I'm Cortana, welcome to my meeting.

Hinweis

Jede POST-Anforderung generiert eine neue Zeile mit Untertiteln. Um sicherzustellen, dass der Endbenutzer genügend Zeit hat, den Inhalt zu lesen, begrenzen Sie jeden POST-Anforderungstext auf 80–120 Zeichen.

Fehlercodes

Die folgende Tabelle enthält die Fehlercodes:

Fehlercode Beschreibung
400 Ungültige Anforderung. Der Antworttext enthält weitere Informationen. Beispielsweise werden nicht alle erforderlichen Parameter dargestellt.
401 Unbefugt. Ungültiges oder abgelaufenes Token. Wenn Sie diesen Fehler erhalten, generieren Sie eine neue WARENKORB-URL in Teams.
404 Besprechung nicht gefunden oder nicht gestartet. Wenn Sie diese Fehlermeldung erhalten, stellen Sie sicher, dass Sie das Meeting starten und Startuntertitel auswählen. Nachdem Untertitel im Meeting aktiviert wurden, können Sie damit beginnen, Untertitel in das Meeting zu posten.
500 Internal server error. (Interner Serverfehler) Wenden Sie sich für weitere Informationen an den Support oder geben Sie Feedback.

Empfangen von Teams-Besprechungsereignissen in Echtzeit

Sie können Besprechungsereignisse in Echtzeit empfangen, z. B. Ereignisse zum Starten und Beenden einer Besprechung oder zum Beitritt und Verlassen von Teilnehmern.

Empfangen von Start- und Endereignissen für Besprechungen

Hinweis

Start- und Endereignisse für Besprechungen werden für geplante und Kanalbesprechungen unterstützt.

Der Benutzer kann Meeting-Ereignisse in Echtzeit empfangen. Sobald eine App mit einem Meeting verknüpft ist, werden die tatsächliche Start- und Endzeit des Meetings mit dem Bot geteilt. Die tatsächliche Start- und Endzeit eines Meetings unterscheidet sich von der geplanten Start- und Endzeit. Die Besprechungsdetails-API enthält die geplante Start- und Endzeit. Das Ereignis gibt die tatsächliche Start- und Endzeit an.

Wenn die ChannelMeeting.ReadBasic.GroupOnlineMeeting.ReadBasic.Chat und-Berechtigungen im Manifest hinzugefügt werden, beginnt der Bot automatisch mit dem Empfang der Start- oder Endereignisse für die Besprechungstypen "Geplant" und "Kanal".

Voraussetzungen

Ihr App-Manifest muss über die webApplicationInfo Eigenschaft verfügen, die Start- und Endereignisse des Meetings zu empfangen. Verwenden Sie die folgenden Beispiele, um Ihr Manifest zu konfigurieren:


Für App-Manifestversion 1.12 und höher 
"webApplicationInfo": {
    "id": "<bot id>",
    "resource": "https://RscPermission",
    }
"authorization": {
    "permissions": {
        "resourceSpecific": [
            {
                "name": "OnlineMeeting.ReadBasic.Chat",
                "type": "Application"
            },
            {
                "name": "ChannelMeeting.ReadBasic.Group",
                "type": "Application"
            }
        ]    
    }
}


Für App-Manifest Version 1.11 und früher 
"webApplicationInfo": {
    "id": "<bot id>",
    "resource": "https://RscPermission",
    "applicationPermissions": [
      "OnlineMeeting.ReadBasic.Chat",
      "ChannelMeeting.ReadBasic.Group"
    ]
}

Beispiel für das Abrufen von Start- oder Endereignissen für Besprechungen

Der Bot empfängt die Start- und Endereignisse der Besprechung über die OnTeamsMeetingStartAsync und-Handler OnTeamsMeetingEndAsync . Die Informationen im Zusammenhang mit dem Besprechungsereignis sind Teil des MeetingStartEventDetails Objekts, das die Metadatenfelder wie , meetingType, title, startTimeidjoinUrl, und EndTimeenthält.

Hinweis

  • Besprechungs-ID abrufen von context.Activity.ChannelData.
  • Konversations-ID nicht als Besprechungs-ID verwenden.
  • Verwenden Sie keine Besprechungs-ID aus der Nutzlast der Besprechungsereignisse activity.value.

Die folgenden Beispiele zeigen, wie die Start- und Endereignisse der Besprechung erfasst werden:

Meeting-Startereignis

// Register meeting start handler
teamsApp.OnMeetingStart(async (context, cancellationToken) =>
{
    var activity = context.Activity.Value;
    var card = new AdaptiveCard
    {
        Schema = "http://adaptivecards.io/schemas/adaptive-card.json",
        Body = new List<CardElement>
        {
            new TextBlock("The meeting has started.")
            {
                Wrap = true,
                Weight = TextWeight.Bolder,
                Size = TextSize.Large
            },
            new TextBlock($"**Title:** {activity.Title}")
            {
                Wrap = true
            },
            new TextBlock($"**Start Time:** {activity.StartTime}")
            {
                Wrap = true
            }
        },
        Actions = new List<Microsoft.Teams.Cards.Action>
        {
            new OpenUrlAction(activity.JoinUrl)
            {
                Title = "Join Meeting"
            }
        }
    };

    await context.Send(card, cancellationToken);
});


app.on('meetingStart', async ({ activity, send }) => {
  const value = activity.value;

  const card = new AdaptiveCard(
    new TextBlock('The meeting has started.', { weight: 'Bolder', size: 'Large', wrap: true }),
    new TextBlock(`**Title:** ${value.title || 'N/A'}`, { wrap: true }),
    new TextBlock(`**Start Time:** ${value.startTime || 'N/A'}`, { wrap: true })
  ).withActions(
    new OpenUrlAction(value.joinUrl, { title: 'Join Meeting' })
  );
  
  await send(card);
});

Es folgen Beispiele für die Ereignisnutzlasten für das Beitritt und Verlassen von Teilnehmern:

Im Folgenden finden Sie ein Beispiel für die Ereignisnutzlast "Teilnehmerbeitritt":

{ 

    "type": "event", 
    "name": "application/vnd.microsoft.meetingParticipantJoin",
    "timestamp": "2023-02-23T19:34:07.478Z", 
    "channelId": "msteams", 
    "serviceUrl": "https://smba.trafficmanager.net/amer/", 
    "from": { 
        "id": "29:id_xyz" 
    }, 
    "conversation": { 
        "isGroup": true, 
        "conversationType": "groupchat", 
        "id": "19:meeting_threadId@thread.v2" 
    }, 
    "recipient": { 
        "id": "28:botid" 
    },  
    "value": { 
       "members": [ 
       { 
        "user": { 
            "tenantId": "tenantid", 
            "objectId": "user_object_Id", 
            "id": "29:userId ", 
            "name": "Test User", 
            "aadObjectId": " user_object_Id " 
        },   
        "meeting": { 
            "inMeeting": true, 
            "role": "Organizer" //Attendee, Organizer, Presenter 
        },  
        }], 
    }, 
    "channelData": { 
        "tenant": { 
            "id": "tenantId" 
        }, 
        "meeting": { 
            "id": "encoded_meetingId" 
        } 
    } 
}

Codebeispiel

Beispielname Beschreibung .NET Node.js Manifest
Erweiterbarkeit von Besprechungen Beispiel für die Erweiterbarkeit von Teams-Besprechungen zum Übergeben von Token. View View View
Besprechungsinterne Benachrichtigung Veranschaulicht, wie die Besprechungsbenachrichtigung mithilfe eines Bots implementiert wird. View View View
Besprechungsseitenbereich Beispiel für die Erweiterbarkeit von Teams-Besprechungen für die Interaktion mit dem Seitenbereich in einer Besprechung. View Anzeigen
Registerkarte „Details“ im Meeting Diese Beispiel-App zeigt das Feature zur Erweiterbarkeit von Teams-Besprechungen, bei dem der Benutzer eine Umfrage erstellen kann und Mitglieder die Umfrage in der Besprechung beantworten können. View View Anzeigen
Beispiel für Meeting-Ereignisse Dieses Beispiel zeigt Teams-Besprechungsereignisse in Echtzeit mithilfe eines Bots. View View –
Beispiel für die Rekrutierung von Meetings Diese Beispiel-App zeigt eine Besprechungsumgebung für das Rekrutierungsszenario mithilfe von Apps in Besprechungen. View View Anzeigen

Siehe auch

  • Last updated on