Versenden proaktiver NachrichtenSend proactive messages

Wichtig

Die Codebeispiele in diesem Abschnitt basieren auf 4,6 und höheren Versionen des bot Framework SDK.The code samples in this section are based on 4.6 and later versions of the Bot Framework SDK. Wenn Sie nach einer Dokumentation für frühere Versionen suchen, lesen Sie den Abschnitt Bots-V3 SDK im Ordner Resources der Dokumentation.If you're looking for documentation for earlier versions, see the Bots - v3 SDK section in the Resources folder of the documentation.

Eine proaktive Nachricht ist eine Nachricht, die von einem bot gesendet wird, die nicht direkt auf eine Anforderung eines Benutzers reagiert.A proactive message is any message sent by a bot that is not in direct response to a request from a user. Dies kann beispielsweise folgende Nachrichten enthalten:This can include messages like:

  • WillkommensnachrichtenWelcome messages
  • BenachrichtigungenNotifications
  • Geplante NachrichtenScheduled messages

Damit Ihr bot eine proaktive Nachricht senden kann, muss er Zugriff auf den Benutzer, den Gruppenchat oder das Team haben, an das Sie die Nachricht senden möchten.In order for your bot to send a proactive message, it must have access to the user, group chat, or team that you wish to send the message to. Für einen Gruppenchat oder ein Team bedeutet dies, dass die APP, die ihren bot enthält, zuerst an diesem Speicherort installiert werden muss.For a group chat or team, this means the app that contains your bot must first be installed to that location. Sie können Ihre APP bei Bedarf proaktiv mithilfe von Graph in einem Team installieren oder mithilfe einer APP- Richtlinie apps an Microsoft Teams und Benutzer in Ihrem Mandanten verschieben.You can proactively install your app using Graph in a team if necessary, or use an app policy to push apps out to teams and users in your tenant. Für Benutzer muss Ihre APP entweder für diesen Benutzer installiert sein, oder der Benutzer muss Teil eines Teams sein, in dem die APP installiert ist.For users, your app either needs to be installed for that user, or your user needs to be part of a team where your app is installed.

Das Senden einer proaktiven Nachricht unterscheidet sich vom Senden einer regulären Nachricht dadurch, dass Sie keine aktive Person turnContext für eine Antwort verwenden müssen.Sending a proactive message is different than sending a regular message in that you won't have an active turnContext to use for a reply. Möglicherweise müssen Sie auch die Unterhaltung erstellen (beispielsweise einen neuen eins-zu-eins-Chat oder einen neuen Unterhaltungsthread in einem Kanal), bevor Sie die Nachricht senden.You may also need to create the conversation (for example a new one-to-one chat, or a new conversation thread in a channel) before sending the message. Sie können keinen neuen Gruppenchat oder einen neuen Kanal in einem Team mit proaktivem Messaging erstellen.You cannot create a new group chat or a new channel in a team with proactive messaging.

Auf einer hohen Ebene müssen Sie die folgenden Schritte ausführen, um eine proaktive Nachricht zu senden:At a high level the steps you'll need to complete to send a proactive message are:

  1. Rufen Sie die Benutzer-ID oder die Team-/Kanal-ID (falls erforderlich) ab.Get the user ID or team/channel ID (if needed).
  2. Erstellen Sie den Unterhaltung-oder Unterhaltungsthread (falls erforderlich).Create the conversation or conversation thread (if needed).
  3. Rufen Sie die Unterhaltungs-IDab.Get the conversation ID.
  4. Senden Sie die Nachricht.Send the message.

Die Codeausschnitte im folgenden Abschnitt " Beispiele " dienen zum Erstellen einer 1:1-Unterhaltung, im Abschnitt " Verweise " finden Sie Links zu vollständigen Arbeitsbeispielen für einmalige Unterhaltungen und Gruppen/Kanäle.The code snippets in the examples section below are for creating a one-to-one conversation, see the references section for links to complete working samples for both one-to-once conversations and group/channels.

Abrufen der Benutzer-ID oder der Team/Kanal-IDGet the user ID or team/channel ID

Wenn Sie einen neuen Unterhaltungs-oder Unterhaltungsthread in einem Kanal erstellen müssen, benötigen Sie zunächst die richtige ID, um die Unterhaltung zu erstellen.If you need to create a new conversation or conversation thread in a channel you'll first need the right ID to create the conversation. Sie können diese ID auf verschiedene Arten empfangen/abrufen:You can receive/retrieve this ID in multiple ways:

  1. Wenn Ihre APP in einem bestimmten Kontext installiert ist, erhalten Sie eine onMembersAdded Aktivität.When your app is installed in any particular context, you'll receive a onMembersAdded Activity.
  2. Wenn einem Kontext, in dem Ihre APP installiert ist, ein neuer Benutzer hinzugefügt wird, erhalten Sie eine onMembersAdded Aktivität.When a new user is added to a context where your app is installed, you'll receive a onMembersAdded Activity.
  3. Sie können die Liste der Kanäle in einem Team abrufen, auf dem Ihre APP installiert ist.You can retrieve the list of channels in a team your app is installed.
  4. Sie können die Liste der Mitglieder eines Teams abrufen, auf dem Ihre APP installiert ist.You can retrieve the list of members of a team your app is installed.
  5. Jede Aktivität, die ihr bot erhält, enthält die notwendigen Informationen.Every Activity your bot receives will contain the necessary information.

Unabhängig davon, wie Sie die Informationen erhalten, müssen Sie die tenantId -und entweder die oder-speichern, um userId channelId eine neue Unterhaltung zu erstellen.Regardless of how you gain the information, you'll need to store the tenantId and either the userId or channelId in order to create a new conversation. Sie können auch die verwenden teamId , um einen neuen Unterhaltungsthread im allgemeinen/Standardkanal eines Teams zu erstellen.You can also use the teamId to create a new conversation thread in the general/default channel of a team.

Die userId ist für Ihre bot-ID und einen bestimmten Benutzer eindeutig, Sie können Sie nicht zwischen Bots wieder verwenden.The userId is unique to your bot Id and a particular user, you cannot re-use them between bots. Das channelId ist Global, aber Ihr bot muss im Team installiert sein, bevor Sie eine proaktive Nachricht an einen Kanal senden können.The channelId is global, however your bot must be installed in the team before you can send a proactive message to a channel.

Erstellen der UnterhaltungCreate the conversation

Sobald Sie über die Benutzer/Kanal-Informationen verfügen, müssen Sie die Unterhaltung erstellen, wenn Sie noch nicht vorhanden ist (oder Sie wissen nicht, welche conversationId ).Once you have the user/channel information, you'll need to create the conversation if it doesn't already exist (or you don't know the conversationId). Sie sollten die Unterhaltung nur einmal erstellen; Stellen Sie sicher, dass Sie den conversationId Wert oder das conversationReference Objekt speichern, das in Zukunft verwendet werden soll.You should only create the conversation once; make sure you store the conversationId value or conversationReference object to use in the future.

Abrufen der Unterhaltungs-IDGet the conversation ID

Nachdem die Unterhaltung erstellt wurde, verwenden Sie entweder das conversationReference -Objekt oder das conversationId und- tenantId , um die Nachricht zu senden.Once the conversation has been created, you will use either the conversationReference object or the conversationId and the tenantId to send the message. Sie können diese ID abrufen, indem Sie die Unterhaltung entweder erstellen oder aus einer Aktivität speichern, die Sie aus diesem Kontext erhalten haben.You can get this Id by either creating the conversation, or storing it from any Activity sent to you from that context. Stellen Sie sicher, dass Sie diese ID speichern.Make certain that you store this Id.

Senden der NachrichtSend the message

Da Sie nun über die richtigen Adressinformationen verfügen, können Sie Ihre Nachricht senden.Now that you have the right address information, you can send your message. Wenn Sie das SDK verwenden, verwenden Sie die continueConversation -Methode und den conversationId und tenantId , um einen direkten API-Aufruf zu tätigen.If you're using the SDK, you'll do so using the continueConversation method,and the conversationId and tenantId to make a direct API call. Sie müssen das conversationParameters ordnungsgemäße festlegen, um Ihre Nachricht erfolgreich zu senden-siehe die Beispiele unten oder verwenden Sie eines der Beispiele im Abschnitt Verweise aufgeführt.You'll need to set the conversationParameters correctly to successfully send your message - see the examples below or use one of the samples listed in the references section.

Bewährte Methoden für proaktives MessagingBest practices for proactive messaging

Das Senden proaktiver Nachrichten an Benutzer kann eine sehr effektive Möglichkeit zur Kommunikation mit ihren Benutzern sein.Sending proactive messages to users can be a very effective way to communicate with your users. Aus ihrer Perspektive kann diese Nachricht jedoch vollständig unaufgefordert angezeigt werden, und im Fall von Begrüßungsnachrichten ist dies das erste Mal, dass Sie mit Ihrer APP interagieren.However, from their perspective this message can appear completely unprompted and, in the case of welcome messages, it will be the first time they've interacted with your app. Daher ist es sehr wichtig, diese Funktionalität sparsam zu verwenden (keine Spam-e-Mail-Benutzer) und genügend Informationen bereitzustellen, damit Benutzer verstehen, warum Sie Nachrichten erhalten.As such, it is very important to use this functionality sparingly (don't spam your users) and to provide enough information to let users understand why they are being messaged.

WillkommensnachrichtenWelcome messages

Bei Verwendung von proaktivem Messaging zum Senden einer Willkommensnachricht an einen Benutzer müssen Sie Bedenken, dass für die meisten Personen, die die Nachricht erhalten, kein Kontext dafür vorhanden ist, warum Sie Sie empfangen.When using proactive messaging to send a welcome message to a user you must keep in mind that, for most people receiving the message, there will be no context for why they are receiving it. Dies ist auch das erste Mal, dass Sie mit Ihrer APP interagieren; Es ist Ihre Gelegenheit, einen guten ersten Eindruck zu erstellen.This is also the first time they will have interacted with your app; it is your opportunity to create a good first impression. Die besten Begrüßungsnachrichten umfassen Folgendes:The best welcome messages will include:

  • Warum ein Benutzer die Nachricht empfängt.Why a user is receiving the message. Dem Benutzer sollte sehr deutlich sein, warum er die Nachricht empfängt.It should be very clear to the user why they are receiving the message. Wenn Ihr bot in einem Kanal installiert wurde und Sie eine Willkommensnachricht an alle Benutzer gesendet haben, sollten Sie wissen, in welchem Kanal Sie installiert wurde und wer Sie möglicherweise installiert hat.If your bot was installed in a channel and you sent a welcome message to all users, let them know what channel it was installed in and potentially who installed it.
  • Was bieten Sie an?What do you offer. Was können Sie mit Ihrer APP tun?What can they do with your app? Welchen Wert können Sie Ihnen bringen?What value can you bring to them?
  • Was sollten Sie als nächstes tun?What should they do next. Laden Sie Sie ein, einen Befehl auszuprobieren oder mit ihrer app in irgendeiner Weise zu interagieren.Invite them to try out a command, or interact with your app in some way.

Denken Sie daran, dass schlechte Begrüßungsnachrichten dazu führen können, dass Benutzer ihren bot blockieren.Remember, poor welcome messages can lead to users blocking your bot. Sie sollten viel Zeit damit verbringen, ihre Begrüßungsnachrichten zu entwerfen und Sie zu durchlaufen, wenn Sie nicht den gewünschten Effekt haben.You should spend plenty of time crafting your welcome messages, and iterate on them if they are not having the desired effect.

BenachrichtigungenNotification messages

Bei der Verwendung von proaktivem Messaging zum Senden von Benachrichtigungen müssen Sie sicherstellen, dass Ihre Benutzer über einen klaren Pfad verfügen, um häufige Aktionen basierend auf Ihrer Benachrichtigung durchzuführen, und ein klares Verständnis dafür, warum die Benachrichtigung erfolgt ist.When using proactive messaging to send notifications you need to make sure your users have a clear path to take common actions based on your notification and a clear understanding of why the notification occurred. Gute Benachrichtigungsnachrichten umfassen im Allgemeinen Folgendes:Good notification messages will generally include:

  • Was ist passiert.What happened. Ein klarer Hinweis darauf, was passiert ist, um die Benachrichtigung zu verursachen.A clear indication of what happened to cause the notification.
  • Was war das Ergebnis?What was the result. Es sollte klar sein, welches Element/Ding aktualisiert wurde, um die Benachrichtigung zu verursachen.It should be clear what item/thing was updated to cause the notification.
  • Wer/was hat ihn ausgelöst.Who/what triggered it. Die Person oder die Aktion, die die Benachrichtigung gesendet hat.Who or what took action that caused the notification to be sent.
  • Was können Benutzer als Antwort tun?What can users do in response. Erleichtern Sie Ihren Benutzern das Ausführen von Aktionen basierend auf Ihren Benachrichtigungen.Make it easy for your users to take actions based on your notifications.
  • Wie können sich Benutzer abmelden? Sie müssen einen Pfad angeben, damit Benutzer zusätzliche Benachrichtigungen deaktivieren können.How can users opt out. You need to provide a path for users to opt out of additional notifications.

Proaktive Installation Ihrer App mithilfe von GraphProactively install your app using Graph

Hinweis

Die proaktive Installation von apps mithilfe von Microsoft Graph befindet sich derzeit in der Betaphase.Proactively installing apps using the Microsoft Graph is currently in beta.

Gelegentlich kann es erforderlich sein, Benutzer proaktiv Nachrichten zu verständigen, die zuvor noch nicht mit Ihrer APP installiert oder mit ihr interagiert haben.Occasionally it may be necessary to proactively message users that have not installed or interacted with your app previously. Beispielsweise möchten Sie das Unternehmens Communicator verwenden, um Nachrichten an die gesamte Organisation zu senden.For example, you want to use the company communicator to send messages to your entire organization. In diesem Szenario können Sie die Graph-API verwenden, um Ihre APP proaktiv für Ihre Benutzer zu installieren, und dann die erforderlichen Werte aus dem Ereignis Zwischenspeichern, das conversationUpdate Ihre APP bei der Installation empfangen wird.For this scenario you can use the Graph API to proactively install your app for your users, then cache the necessary values from the conversationUpdate event your app will receive upon install.

Sie können nur apps installieren, die sich in Ihrem Organisations-App-Katalog oder im Microsoft Teams-App-Store befinden.You can only install apps that are in your organizational app catalogue, or the Teams app store.

Siehe Installieren von Apps für Benutzer in der Graph-Dokumentation und proaktive bot-Installation und-Messaging in Microsoft Teams mit Microsoft Graph.See Install apps for users in the Graph documentation and Proactive bot installation and messaging in Teams with Microsoft Graph. Es gibt auch ein Microsoft .NET Framework-Beispiel auf der GitHub-Plattform.There is also a Microsoft .NET framework sample on the GitHub platform.

BeispieleExamples

private async Task MessageAllMembersAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    var teamsChannelId = turnContext.Activity.TeamsGetChannelId();
    var serviceUrl = turnContext.Activity.ServiceUrl;
    var credentials = new MicrosoftAppCredentials(_appId, _appPassword);
    ConversationReference conversationReference = null;

    //Get the set of member IDs to send the message to
    var members = await GetPagedMembers(turnContext, cancellationToken);

    foreach (var teamMember in members)
    {
        var proactiveMessage = MessageFactory.Text($"Hello {teamMember.GivenName} {teamMember.Surname}. I'm a Teams conversation bot.");

        var conversationParameters = new ConversationParameters
        {
            IsGroup = false,
            Bot = turnContext.Activity.Recipient,
            Members = new ChannelAccount[] { teamMember },
            TenantId = turnContext.Activity.Conversation.TenantId,
        };
        //create the new one-to-one conversations
        await ((BotFrameworkAdapter)turnContext.Adapter).CreateConversationAsync(
            teamsChannelId,
            serviceUrl,
            credentials,
            conversationParameters,
            async (t1, c1) =>
            {
                //Get the conversationReference
                conversationReference = t1.Activity.GetConversationReference();
                //Send the proactive message
                await ((BotFrameworkAdapter)turnContext.Adapter).ContinueConversationAsync(
                    _appId,
                    conversationReference,
                    async (t2, c2) =>
                    {
                        await t2.SendActivityAsync(proactiveMessage, c2);
                    },
                    cancellationToken);
            },
            cancellationToken);
    }

    await turnContext.SendActivityAsync(MessageFactory.Text("All messages have been sent."), cancellationToken);
}

InformationsquellenReferences

Die offiziellen Proactive Messaging-Beispiele sind unten aufgeführt.The official proactive messaging samples are listed below.

Nein.No. Beispiel NameSample Name BeschreibungDescription .NET.NET JavaScriptJavaScript PythonPython
5757 Grundlagen der Microsoft Teams-KonversationTeams Conversation Basics Veranschaulicht Grundlagen der Unterhaltungen in Microsoft Teams, einschließlich des Sendens von 1:1-Nachrichten.Demonstrates basics of conversations in Teams, including sending one-to-one proactive messages. .Net-   Kern.NET Core JavaScriptJavaScript PythonPython
5858 Neuen Thread in einem Kanal startenStart new thread in a channel Veranschaulicht das Erstellen eines neuen Threads in einem Kanal.Demonstrates creating a new thread in a channel. .Net-   Kern.NET Core JavaScriptJavaScript PythonPython

Das Beispiel unten veranschaulicht die minimale Menge an Informationen, die zum Senden einer proaktiven Nachricht benötigt werden (ohne Verwendung eines conversationReference Objekts).The sample below demonstrates the minimal amount of information needed to send a proactive message (without using a conversationReference object). Dieses Beispiel kann hilfreich sein, wenn Sie Rest-API-Aufrufe direkt verwenden oder keine vollständigen conversationReference Objekte gespeichert haben.This sample can be useful if you're using REST API calls directly, or haven't been storing full conversationReference objects.

Anzeigen von zusätzlichem CodeView additional code