Senden von proaktiven Installationsmeldungen

  • Artikel

Proaktives Messaging in Microsoft Teams

Proaktive Nachrichten werden von Bots initiiert, um Unterhaltungen mit Benutzern zu beginnen. Sie dienen vielen Zwecken, darunter dem Senden von Begrüßungsnachrichten, dem Durchführen von Umfragen oder dem Senden organisationsweiter Benachrichtigungen. Proaktive Nachrichten in Microsoft Teams können als Ad-hoc- oder dialogbasierte Unterhaltungen gesendet werden:

Nachrichtentyp Beschreibung
Proaktive Ad-hoc-Nachrichten Der Bot schiebt eine Nachricht ein, ohne die Unterhaltung zu unterbrechen.
Dialogbasierte proaktive Nachrichten Der Bot erstellt einen neuen Dialogthread, übernimmt die Kontrolle über eine Unterhaltung, übermittelt die proaktive Nachricht, schließt und gibt die Steuerung an den vorherigen Dialogthread zurück.

Proaktive App-Installation in Microsoft Teams

Bevor Ihr Bot proaktiv eine Nachricht an einen Benutzer senden kann, muss er entweder als persönliche App oder in einem Team installiert werden, in dem der Benutzer Mitglied ist. Manchmal müssen Sie Benutzern, die Ihre App noch nicht installiert haben oder zuvor mit Ihrer App interagiert haben, proaktiv nachrichten. Wenn Sie beispielsweise wichtige Informationen an alle Benutzer in Ihrem organization senden müssen, können Sie den Microsoft Graph-API verwenden, um Ihren Bot proaktiv für Ihre Benutzer zu installieren.

Berechtigungen

Microsoft Graph-Berechtigungen für den teamsAppInstallation-Ressourcentyp helfen Ihnen, den Installationslebenszyklus Ihrer App für alle Benutzerbereiche (persönlich) oder Teambereiche (Kanal) innerhalb der Microsoft Teams-Plattform zu verwalten:

Anwendungsberechtigung Beschreibung
TeamsAppInstallation.ReadWriteSelfForUser.All Ermöglicht es einer Microsoft-Teams-App, sich selbst für einen Benutzer ohne vorherige Anmeldung oder Nutzung zu lesen, installieren, aktualisieren und deinstallieren.
TeamsAppInstallation.ReadWriteSelfForTeam.All Ermöglicht es einer Microsoft-Teams-App, sich selbst für ein beliebiges Team ohne vorherige Anmeldung oder Nutzung zu lesen, installieren, aktualisieren und deinstallieren.

Um diese Berechtigungen verwenden zu können, müssen Sie Ihrem App-Manifest (zuvor Teams-App-Manifest genannt) einen webApplicationInfo-Schlüssel mit den folgenden Werten hinzufügen:

  • id: Ihre Microsoft Entra App-ID.
  • resource: Die Ressourcen-URL für die App

Hinweis

  • Ihr Bot benötigt Anwendungsberechtigungen und keine delegierten Benutzerberechtigungen, da die Installation für andere vorgesehen ist.

  • Ein Microsoft Entra Mandantenadministrator muss einer Anwendung explizit Berechtigungen erteilen. Nachdem der Anwendung Berechtigungen erteilt wurden, erhalten alle Mitglieder des Microsoft Entra Mandanten die gewährten Berechtigungen.

Aktivieren der proaktiven Bot-Installation und des proaktiven Bot-Messagings

Wichtig

Microsoft Graph kann nur Apps installieren, die im App Store Ihrer organization oder im Microsoft Teams Store veröffentlicht wurden.

Erstellen und Veröffentlichen eines proaktiven Messaging-Bots für Microsoft Teams

Um zu beginnen, benötigen Sie einen Bot für Teams mit proaktiven Messagingfunktionen, der sich im App Store Ihres organization oder im Teams Store befindet.

Tipp

Die produktionsbereite Company Communicator-App-Vorlage ermöglicht Messaging und ist ein guter Ausgangspunkt zum Erstellen Ihrer proaktiven Bot-Anwendung.

Abrufen der teamsAppId für Ihre App

Sie können die teamsAppId wie folgt abrufen:

  • Aus dem App-Katalog Ihrer Organisation:

    Microsoft Graph-Seitenreferenz:teamsApp-Ressourcentyp

    HTTP GET-Anforderung:

    GET https://graph.microsoft.com/v1.0/appCatalogs/teamsApps?$filter=externalId eq '{IdFromManifest}'

    Die Anforderung muss ein teamsApp-Objekt id zurückgeben, bei dem es sich um die vom App-Katalog generierte App-ID handelt. Dies unterscheidet sich von der ID, die Sie in Ihrem App-Manifest angegeben haben:

    {
  "value": [
    {
      "id": "b1c5353a-7aca-41b3-830f-27d5218fe0e5",
      "externalId": "f31b1263-ba99-435a-a679-911d24850d7c",
      "name": "Test App",
      "version": "1.0.1",
      "distributionMethod": "Organization"
    }
  ]
}

    Hinweis

    Wenn sich die App im Teams Store befindet, ist identisch teamsAppId mit IdFromManifest und externalId darf in diesem Fall nicht verwendet werden.

  • Wenn Ihre App bereits für einen Benutzer im persönlichen Bereich hochgeladen wurde:

    Microsoft Graph-Seitenreferenz:Auflisten von Apps, die für Benutzer installiert sind

    HTTP GET-Anforderung:

    GET https://graph.microsoft.com/v1.0/users/{user-id}/teamwork/installedApps?$expand=teamsApp&$filter=teamsApp/externalId eq '{IdFromManifest}'

  • Wenn Ihre App bereits für einen Kanal im Teambereich hochgeladen wurde:

    Microsoft Graph-Seitenreferenz:Apps im Team auflisten

    HTTP GET-Anforderung:

    GET https://graph.microsoft.com/v1.0/teams/{team-id}/installedApps?$expand=teamsApp&$filter=teamsApp/externalId eq '{IdFromManifest}'

    Tipp

    Um die Ergebnisliste einzugrenzen, können Sie jedes der Felder des teamsApp-Objekts filtern.

Ermitteln, ob Ihr Bot derzeit für einen Nachrichtenempfänger installiert ist

Sie können wie folgt ermitteln, ob Ihr Bot derzeit für einen Nachrichtenempfänger installiert ist:

Microsoft Graph-Seitenreferenz:Auflisten von Apps, die für Benutzer installiert sind

HTTP GET-Anforderung:

GET https://graph.microsoft.com/v1.0/users/{user-id}/teamwork/installedApps?$expand=teamsApp&$filter=teamsApp/id eq '{teamsAppId}'

Die Anforderung gibt Folgendes zurück:

  • Ein leeres Array, wenn die App nicht installiert ist.
  • Ein Array mit einem einzelnen teamsAppInstallation-Objekt, wenn die App installiert ist.

Installieren Ihrer App

Sie können Ihre App wie folgt installieren:

Microsoft Graph-Seitenreferenz:App für Benutzer installieren

HTTP POST-Anforderung:

POST https://graph.microsoft.com/v1.0/users/{user-id}/teamwork/installedApps
Content-Type: application/json

{
   "teamsApp@odata.bind" : "https://graph.microsoft.com/v1.0/appCatalogs/teamsApps/{teamsAppId}"
}

Wenn Microsoft Teams bei dem Benutzer gerade aktiv ist, erfolgt die App-Installation sofort. Möglicherweise ist ein Neustart erforderlich, damit die installierte App angezeigt wird.

Abrufen der chatId einer Unterhaltung

Wenn Ihre App für den Benutzer installiert ist, empfängt der Bot eine conversationUpdateEreignisbenachrichtigung , die die erforderlichen Informationen zum Senden der proaktiven Nachricht enthält.

Microsoft Graph-Seitenreferenz:Chat abrufen

  1. Sie müssen über die {teamsAppInstallationId} Ihrer App verfügen. Wenn sie nicht vorhanden ist, verwenden Sie Folgendes:

    HTTP GET-Anforderung:

    GET https://graph.microsoft.com/v1.0/users/{user-id}/teamwork/installedApps?$expand=teamsApp&$filter=teamsApp/id eq '{teamsAppId}'

    Die id-Eigenschaft der Antwort ist die teamsAppInstallationId.

  2. Führen Sie die folgende Anforderung aus, um die chatId abzurufen:

    HTTP GET-Anforderung (Berechtigung—TeamsAppInstallation.ReadWriteSelfForUser.All):

    GET https://graph.microsoft.com/v1.0/users/{user-id}/teamwork/installedApps/{teamsAppInstallationId}/chat

    Die id-Eigenschaft der Antwort ist die chatId.

    Sie können die chatId auch mit der folgenden Anforderung abrufen, sie erfordert jedoch die umfassendere Chat.Read.All-Berechtigung:

    HTTP GET-Anforderung (Berechtigung—Chat.Read.All):

    GET https://graph.microsoft.com/v1.0/users/{user-id}/chats?$filter=installedApps/any(a:a/teamsApp/id eq '{teamsAppId}')

Senden proaktiver Nachrichten

Ihr Bot kann proaktive Nachrichten senden, nachdem er für einen Benutzer oder ein Team hinzugefügt wurde und alle Benutzerinformationen erhalten hat.

Codeausschnitte

Der folgende Code stellt ein Beispiel für das Senden proaktiver Nachrichten dar:

public async Task<int> SendNotificationToAllUsersAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
   int msgSentCount = 0;

   // Send notification to all the members.
   foreach (var conversationReference in _conversationReferences.Values)
   {
       await turnContext.Adapter.ContinueConversationAsync(_configuration["MicrosoftAppId"], conversationReference, BotCallback, cancellationToken);
       msgSentCount++;
   }

   return msgSentCount;
}

private async Task BotCallback(ITurnContext turnContext, CancellationToken cancellationToken)
{
    // Sends an activity to the sender of the incoming activity.
   await turnContext.SendActivityAsync("Proactive hello.");
}

Codebeispiel

Beispielname Beschreibung .NET Node.js
Proaktive Installation der App und Senden proaktiver Benachrichtigungen Dieses Beispiel zeigt, wie Sie die proaktive Installation der App für Benutzer verwenden und proaktive Benachrichtigungen senden können, indem Sie Microsoft Graph APIs aufrufen. View Anzeigen

Zusätzliche Codebeispiele

Codebeispiele für proaktives Messaging in Teams

Siehe auch