Aktivieren der proaktiven bot-Installation und proaktiver Nachrichten in Microsoft Graph-Teams (öffentliche Vorschau)Enable proactive bot installation and proactive messaging in Teams with Microsoft Graph (Public Preview)

Wichtig

Microsoft Graph und Microsoft Teams öffentliche Vorschauen stehen für den frühzeitigen Zugriff und das Feedback zur Verfügung.Microsoft Graph and Microsoft Teams public previews are available for early-access and feedback. Obwohl diese Version umfangreiche Tests unterzogen wurde, ist Sie nicht für die Verwendung in der Produktion vorgesehen.Although this release has undergone extensive testing, it is not intended for use in production.

Proaktives Messaging in Microsoft TeamsProactive messaging in Teams

Proaktive Nachrichten werden von Bots initiiert, um Unterhaltungen mit einem Benutzer zu starten.Proactive messages are initiated by bots to start conversations with a user. Sie dienen zahlreichen Zwecken, beispielsweise beim Senden von Begrüßungsnachrichten, durchführen von Umfragen oder Umfragen sowie bei der Ausstrahlung organisationsweiter Benachrichtigungen.They serve many purposes including sending welcome messages, conducting surveys or polls, and broadcasting organization-wide notifications. Proaktive Nachrichten in Microsoft Teams können entweder als Ad-hoc -oder dialogbasierte Unterhaltungen bereitgestellt werden:Proactive messages in Teams can be delivered as either ad-hoc or dialog-based conversations:

NachrichtentypMessage Type BeschreibungDescription
Ad-hoc-proaktive NachrichtAd-hoc proactive message Der bot interject eine Nachricht, ohne den Unterhaltungs Fluss zu unterbrechen.The bot interjects a message without interrupting the conversation flow.
Dialog basierte proaktive NachrichtDialog-based proactive message Der bot erstellt einen neuen Dialog-Thread, übernimmt die Steuerung einer Unterhaltung, liefert die proaktive Nachricht, schließt und gibt die Steuerung an das vorherige Dialogfeld zurück.The bot creates a new dialog thread, takes control of a conversation, delivers the proactive message, closes, and returns control to the previous dialog.

Siehe, senden proaktiver Benachrichtigungen an Benutzer SDK V4See, Send proactive notifications to users SDK v4

Proaktive App-Installation in Microsoft TeamsProactive app installation in Teams

Bevor Ihr bot einen Benutzer proaktiv Nachrichten kann, muss er entweder als persönliche APP oder in einem Team installiert sein, in dem der Benutzer Mitglied ist.Before your bot can proactively message a user, it needs to be installed either as a personal app, or in a team where the user is a member. Gelegentlich müssen Sie Benutzer proaktiv Nachrichten, die noch nicht mit Ihrer APP installiert oder zuvor interagiert haben.At times, you may need to proactively message users that have not installed or previously interacted with your app. Zum Beispiel die Notwendigkeit, wichtige Informationen an alle Benutzer in Ihrer Organisation zu senden.For instance, the need to message vital information to everyone in your organization. Für solche Szenarien können Sie die Microsoft Graph-API verwenden, um Ihren bot proaktiv für Ihre Benutzer zu installieren.For such scenarios, you can use the Microsoft Graph API to proactively install your bot for your users.

BerechtigungenPermissions

Mit den Ressourcentypen Berechtigungen von Microsoft Graph teamsAppInstallation können Sie den Installationslebenszyklus Ihrer APP für alle Benutzer (persönlichen) oder Team (Kanal) Bereiche innerhalb der Microsoft Teams-Plattform verwalten:Microsoft Graph teamsAppInstallation resource type permissions allow you to manage your app's installation lifecycle for all user (personal) or team (channel) scopes within the Microsoft Teams platform:

AnwendungsberechtigungApplication permission BeschreibungDescription
TeamsAppInstallation.ReadWriteSelfForUser.All Ermöglicht einer Teams-APP, sich selbst für einen beliebigen Benutzerohne vorherige Anmeldung oder Verwendung zu lesen, zu installieren, zu aktualisieren und zu deinstallieren.Allows a Teams app to read, install, upgrade, and uninstall itself for any user, without prior sign in or use.
TeamsAppInstallation.ReadWriteSelfForTeam.All Ermöglicht einer Teams-APP, sich selbst in jedem Teamzu lesen, zu installieren, zu aktualisieren und zu deinstallieren, ohne vorherige Anmeldung oder Verwendung.Allows a Teams app to read, install, upgrade, and uninstall itself in any team, without prior sign in or use.

Um diese Berechtigungen zu verwenden, müssen Sie Ihrem App-Manifest einen webApplicationInfo -Schlüssel mit den folgenden Werten hinzufügen:To use these permissions, you must add a webApplicationInfo key to your app manifest with the following values:

  • ID – ihre Azure AD App-ID.id — your Azure AD app id.
  • Resource – die Ressourcen-URL für die app.resource — the resource URL for the app.

Hinweis

  • Ihr bot erfordert keine Benutzer Delegierten Berechtigungen für die Anwendung , da die Installation nicht für sich selbst, sondern für andere ist.Your bot requires application not user delegated permissions because the installation is not for yourself but for others.

  • Ein Azure AD mandantenadministrator muss explizit Berechtigungen für eine Anwendung erteilen.An Azure AD tenant administrator must explicitly grant permissions to an application. Nachdem einer Anwendung Berechtigungen erteilt wurden, erhalten alle Mitglieder des Azure AD Mandanten die gewährten Berechtigungen.After an application is granted permissions, all members of the Azure AD tenant will gain the granted permissions.

Aktivieren der proaktiven App-Installation und des MessagingEnable proactive app installation and messaging

Wichtig

In Microsoft Graph werden nur apps installiert, die im App-Katalog Ihres Unternehmens oder in AppSourceveröffentlicht wurden.Microsoft Graph will only install apps published within your organization's app catalog or in AppSource.

✔ Erstellen und Veröffentlichen Ihres proaktiven Messaging-bot für Teams✔ Create and publish your proactive messaging bot for Teams

Für die ersten Schritte benötigen Sie einen bot für Teams mit proaktiven Messaging Funktionen, die im App-Katalog Ihres Unternehmens oder in AppSource veröffentlicht werden.To get started, you will need a bot for Teams with proactive messaging capabilities and published in your organization's app catalog or in AppSource.

Tipp

Die produktionsfertige Unternehmens-Communicator -App-Vorlage aktiviert Broadcastnachrichten und ist eine gute Grundlage für die Erstellung Ihrer proaktiven bot-Anwendung.The production-ready Company Communicator app template enables broadcast messaging and is a good foundation for building your proactive bot application.

✔ Abrufen der teamsAppId für Ihre APP✔ Get the teamsAppId for your app

1. Sie benötigen die teamsAppId für die nächsten Schritte.1. You will need the teamsAppId for the next steps.

Der teamsAppId kann aus dem App-Katalog Ihrer Organisation abgerufen werden:The teamsAppId can be retrieved from your organization's app catalog:

Microsoft Graph-Seitenreferenz: teamsApp Resource TypeMicrosoft Graph page reference: teamsApp resource type

HTTP Get -Anforderung:HTTP GET request:

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

Die Anforderung gibt ein teamsApp -Objekt zurück.The request will return a teamsApp object. Das zurückgegebene Objekt ist id die vom Katalog generierte APP-ID der APP und unterscheidet sich von der ID:, die Sie in Ihrem Teams-App-Manifest angegeben haben:The returned object's id is the app's catalog generated app id and is different from the "id:" that you provided in your Teams app manifest:

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

2. Wenn Ihre APP bereits für einen Benutzer im persönlichen Bereich hochgeladen/quer geladene wurde, können Sie die teamsAppId wie folgt abrufen:2. If your app has already been uploaded/sideloaded for a user in the personal scope, you can retrieve the teamsAppId as follows:

Microsoft Graph-Seitenreferenz: Auflisten von apps, die für den Benutzer installiert sindMicrosoft Graph page reference: List apps installed for user

HTTP Get -Anforderung:HTTP GET request:

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

3. Wenn Ihre APP bereits für einen Kanal im Teambereich hochgeladen/quer geladene wurde, können Sie die teamsAppId wie folgt abrufen:3. If your app has already been uploaded/sideloaded for a channel in the team scope, you can retrieve the teamsAppId as follows:

Microsoft Graph-Seitenreferenz: Auflisten von apps im TeamMicrosoft Graph page reference: List apps in team

HTTP Get -Anforderung:HTTP GET request:

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

Tipp

Sie können nach einem der Felder des teamsApp -Objekts filtern, um die Ergebnisliste einzugrenzen.You can filter on any of the fields of the teamsApp object to narrow the list of results.

✔ Bestimmen, ob Ihr bot derzeit für einen Nachrichtenempfänger installiert ist✔ Determine whether your bot is currently installed for a message recipient

Microsoft Graph-Seitenreferenz: Auflisten von apps, die für den Benutzer installiert sindMicrosoft Graph page reference: List apps installed for user

HTTP Get -Anforderung:HTTP GET request:

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

Diese Anforderung gibt ein leeres Array zurück, wenn die APP nicht installiert ist, oder ein Array mit einem einzelnen teamsAppInstallation -Objekt, wenn es installiert wurde.This request will return an empty array if the app is not installed, or an array with a single teamsAppInstallation object if it has been installed.

✔ Installieren Ihrer APP✔ Install your app

Microsoft Graph-Referenz: Installieren der APP für den BenutzerMicrosoft Graph reference: Install app for user

Http Post -Anforderung:HTTP POST request:

POST https://graph.microsoft.com/beta/users/{user-id}/teamwork/installedApps
{
   "teamsApp@odata.bind" : "https://graph.microsoft.com/beta/appCatalogs/teamsApps/{teamsAppId}"
}

Wenn der Benutzer Microsoft Teams ausführt, wird möglicherweise sofort die APP-Installation angezeigt.If the user has Microsoft Teams running, they may see the app install immediately. Alternativ kann ein Neustart erforderlich sein, um die installierte App anzuzeigen.Alternatively, a restart may be necessary to see the installed app.

✔ Abrufen der Unterhaltungs- Chat -Funktion✔ Retrieve the conversation chatId

Wenn Ihre APP für den Benutzer installiert ist, erhält der bot eine conversationUpdate Ereignisbenachrichtigung , die die erforderlichen Informationen zum Senden der proaktiven Nachricht enthalten wird.When your app is installed for the user, the bot will receive a conversationUpdate event notification that will contain the necessary information to send the proactive message.

Die chatId kann auch wie folgt abgerufen werden:The chatId can also be retrieved as follows:

Microsoft Graph-Referenz: Chat abrufenMicrosoft Graph reference: Get chat

1. Sie benötigen Ihre apps {teamsAppInstallationId} .1. You will need your app's {teamsAppInstallationId}. Wenn Sie diesen nicht haben, verwenden Sie Folgendes:If you don't have it, use the following:

HTTP Get -Anforderung:HTTP GET request:

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

Die ID -Eigenschaft der Antwort ist die teamsAppInstallationId .The id property of the response is the teamsAppInstallationId.

2. führen Sie die folgende Anforderung aus, um Folgendes abzurufen chatId :2. Make the following request to fetch the chatId:

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

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

Die ID -Eigenschaft der Antwort ist die chatId .The id property of the response is the chatId.

Alternativ können Sie die chatId mit der folgenden Anforderung abrufen, aber Sie erfordert die breitere Chat.Read.All Berechtigung:Alternately, you can retrieve the chatId with the request below, but it will require the broader Chat.Read.All permission:

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

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

✔ Senden von proaktiven Nachrichten✔ Send proactive messages

Sobald Ihr bot für einen Benutzer oder ein Team hinzugefügt wurde und die erforderlichen Benutzerinformationen erworben hat, kann er mit dem senden proaktiver Nachrichtenbeginnen.Once your bot has been added for a user or team and has acquired the necessary user information, it can begin to send proactive messages.

Der folgende Codeausschnitt stammt aus den Microsoft bot Framework-Beispielen für C#.The following code snippet is from the Microsoft Bot Framework Samples for C#.

using System.Collections.Concurrent;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Bot.Builder;
using Microsoft.Bot.Schema;

namespace Microsoft.BotBuilderSamples
{
    public class ProactiveBot : ActivityHandler
    {
        // Message to send to users when the bot receives a Conversation Update event
        private const string WelcomeMessage = "Welcome to the Proactive Bot sample.  Navigate to http://localhost:3978/api/notify to proactively message everyone who has previously messaged this bot.";

        // Dependency injected dictionary for storing ConversationReference objects used in NotifyController to proactively message users
        private readonly ConcurrentDictionary<string, ConversationReference> _conversationReferences;

        public ProactiveBot(ConcurrentDictionary<string, ConversationReference> conversationReferences)
        {
            _conversationReferences = conversationReferences;
        }

        private void AddConversationReference(Activity activity)
        {
            var conversationReference = activity.GetConversationReference();
            _conversationReferences.AddOrUpdate(conversationReference.User.Id, conversationReference, (key, newValue) => conversationReference);
        }

        protected override Task OnConversationUpdateActivityAsync(ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
        {
            AddConversationReference(turnContext.Activity as Activity);

            return base.OnConversationUpdateActivityAsync(turnContext, cancellationToken);
        }

        protected override async Task OnMembersAddedAsync(IList<ChannelAccount> membersAdded, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
        {
            foreach (var member in membersAdded)
            {
                // Greet anyone that was not the target (recipient) of this message.
                if (member.Id != turnContext.Activity.Recipient.Id)
                {
                    await turnContext.SendActivityAsync(MessageFactory.Text(WelcomeMessage), cancellationToken);
                }
            }
        }

        protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
        {
            AddConversationReference(turnContext.Activity as Activity);

            // Echo back what the user said
            await turnContext.SendActivityAsync(MessageFactory.Text($"You sent '{turnContext.Activity.Text}'"), cancellationToken);
        }
    }
}

Anzeigen zusätzlicher CodebeispieleView additional code samples